update for bakefile 0.2.6

[wxWidgets.git] / interface / wx / listctrl.h

diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index 69022eaebf41c5c30540e272684055003ac82f4e..bfd05c44af3b28cf69b1f71bbcd09a106931fc39 100644 (file)
--- a/interface/wx/listctrl.h
+++ b/interface/wx/listctrl.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        listctrl.h
+// Name:        wx/listctrl.h

 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -23,6 +23,7 @@
     (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
     wxListCtrl::OnGetItemAttr) to return the information about the items when the
     control requests it.
     (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
     wxListCtrl::OnGetItemAttr) to return the information about the items when the
     control requests it.

+

     Virtual list control can be used as a normal one except that no operations
     which can take time proportional to the number of items in the control happen
     -- this is required to allow having a practically infinite number of items.
     Virtual list control can be used as a normal one except that no operations
     which can take time proportional to the number of items in the control happen
     -- this is required to allow having a practically infinite number of items.


@@ -39,29 +40,19 @@
     <b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
     implementation for report mode, and uses a generic implementation for other
     modes. You can use the generic implementation for report mode as well by setting
     <b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
     implementation for report mode, and uses a generic implementation for other
     modes. You can use the generic implementation for report mode as well by setting

-    the @c mac.listctrl.always_use_generic system option (see wxSystemOption) to 1.
-
-    <b>wxMSW Note</b>: In report view, the control has several columns
-    which are identified by their internal indices. By default, these indices
-    correspond to their order on screen, i.e. the column 0 appears first (in the
-    left-to-right or maybe right-to-left if the current language uses this writing
-    direction), the column 1 next and so on. However it is possible to reorder the
-    columns visual order using SetColumnsOrder() method and the user can also
-    rearrange the columns interactively by dragging them. In this case, the index
-    of the column is not the same as its order and the functions GetColumnOrder()
-    and GetColumnIndexFromOrder() should be used to translate between them.
+    the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.

 
 
     @beginStyleTable
     @style{wxLC_LIST}
            Multicolumn list view, with optional small icons. Columns are
            computed automatically, i.e. you don't set columns as in
 
 
     @beginStyleTable
     @style{wxLC_LIST}
            Multicolumn list view, with optional small icons. Columns are
            computed automatically, i.e. you don't set columns as in

-           wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
+           @c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.

     @style{wxLC_REPORT}
            Single or multicolumn report view, with optional header.
     @style{wxLC_VIRTUAL}
            The application provides items text on demand. May only be used
     @style{wxLC_REPORT}
            Single or multicolumn report view, with optional header.
     @style{wxLC_VIRTUAL}
            The application provides items text on demand. May only be used

-           with wxLC_REPORT.
+           with @c wxLC_REPORT.

     @style{wxLC_ICON}
            Large icon view, with optional labels.
     @style{wxLC_SMALL_ICON}
     @style{wxLC_ICON}
            Large icon view, with optional labels.
     @style{wxLC_SMALL_ICON}


@@ -92,7 +83,7 @@
     @endStyleTable
 
 
     @endStyleTable
 
 

-    @beginEventTable{wxListEvent}
+    @beginEventEmissionTable{wxListEvent}

     @event{EVT_LIST_BEGIN_DRAG(id, func)}
            Begin dragging with the left mouse button.
     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
     @event{EVT_LIST_BEGIN_DRAG(id, func)}
            Begin dragging with the left mouse button.
     @event{EVT_LIST_BEGIN_RDRAG(id, func)}


@@ -160,9 +151,10 @@ public:
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos
             Window position.
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos
             Window position.

+            If ::wxDefaultPosition is specified then a default position is chosen.

         @param size
             Window size.
         @param size
             Window size.

-            If wxDefaultSize is specified then the window is sized appropriately.
+            If ::wxDefaultSize is specified then the window is sized appropriately.

         @param style
             Window style. See wxListCtrl.
         @param validator
         @param style
             Window style. See wxListCtrl.
         @param validator


@@ -273,7 +265,7 @@ public:
         Find an item whose data matches this data, starting from start or the
         beginning if 'start' is @c -1.
     */
         Find an item whose data matches this data, starting from start or the
         beginning if 'start' is @c -1.
     */

-    long FindItem(long start, long data);
+    long FindItem(long start, wxUIntPtr data);

 
     /**
         Find an item nearest this position in the specified direction,
 
     /**
         Find an item nearest this position in the specified direction,


@@ -293,12 +285,30 @@ public:
     int GetColumnCount() const;
 
     /**
     int GetColumnCount() const;
 
     /**

-        Gets the column number by visual order index (report view only).
+        Gets the column index from its position in visual order.
+
+        After calling SetColumnsOrder(), the index returned by this function
+        corresponds to the value of the element number @a pos in the array
+        returned by GetColumnsOrder().
+
+        Please see SetColumnsOrder() documentation for an example and
+        additional remarks about the columns ordering.
+
+        @see GetColumnOrder()

     */
     */

-    int GetColumnIndexFromOrder(int order) const;
+    int GetColumnIndexFromOrder(int pos) const;

 
     /**
 
     /**

-        Gets the column visual order index (valid in report view only).
+        Gets the column visual order position.
+
+        This function returns the index of the column which appears at the
+        given visual position, e.g. calling it with @a col equal to 0 returns
+        the index of the first shown column.
+
+        Please see SetColumnsOrder() documentation for an example and
+        additional remarks about the columns ordering.
+
+        @see GetColumnsOrder(), GetColumnIndexFromOrder()

     */
     int GetColumnOrder(int col) const;
 
     */
     int GetColumnOrder(int col) const;
 


@@ -309,7 +319,13 @@ public:
 
     /**
         Returns the array containing the orders of all columns.
 
     /**
         Returns the array containing the orders of all columns.

+

         On error, an empty array is returned.
         On error, an empty array is returned.

+
+        Please see SetColumnsOrder() documentation for an example and
+        additional remarks about the columns ordering.
+
+        @see GetColumnOrder(), GetColumnIndexFromOrder()

     */
     wxArrayInt GetColumnsOrder() const;
 
     */
     wxArrayInt GetColumnsOrder() const;
 


@@ -339,8 +355,10 @@ public:
 
     /**
         Gets information about the item. See SetItem() for more information.
 
     /**
         Gets information about the item. See SetItem() for more information.

-        You must call @e info.SetId() to the ID of item you're interested in
-        before calling this method.
+
+        You must call @e info.SetId() to set the ID of item you're interested in
+        before calling this method, and @e info.SetMask() with the flags indicating
+        what fields you need to retrieve from @a info.

     */
     bool GetItem(wxListItem& info) const;
 
     */
     bool GetItem(wxListItem& info) const;
 


@@ -639,14 +657,53 @@ public:
     bool SetColumnWidth(int col, int width);
 
     /**
     bool SetColumnWidth(int col, int width);
 
     /**

-        Sets the order of all columns at once.
+        Changes the order in which the columns are shown.
+
+        By default, the columns of a list control appear on the screen in order
+        of their indices, i.e. the column 0 appears first, the column 1 next
+        and so on. However by using this function it is possible to arbitrarily
+        reorder the columns visual order and the user can also rearrange the
+        columns interactively by dragging them. In this case, the index of the
+        column is not the same as its order and the functions GetColumnOrder()
+        and GetColumnIndexFromOrder() should be used to translate between them.
+        Notice that all the other functions still work with the column indices,
+        i.e. the visual positioning of the columns on screen doesn't affect the
+        code setting or getting their values for example.

 
         The @a orders array must have the same number elements as the number of
 
         The @a orders array must have the same number elements as the number of

-        columns and contain each position exactly once.
+        columns and contain each position exactly once. Its n-th element
+        contains the index of the column to be shown in n-th position, so for a
+        control with three columns passing an array with elements 2, 0 and 1
+        results in the third column being displayed first, the first one next
+        and the second one last.
+
+        Example of using it:
+        @code
+            wxListCtrl *list = new wxListCtrl(...);
+            for ( int i = 0; i < 3; i++ )
+                list->InsertColumn(i, wxString::Format("Column %d", i));
+
+            wxArrayInt order(3);
+            order[0] = 2;
+            order[1] = 0;
+            order[2] = 1;
+            list->SetColumnsOrder(order);
+
+            // now list->GetColumnsOrder() will return order and
+            // list->GetColumnIndexFromOrder(n) will return order[n] and
+            // list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
+            // 1 and 2 respectively
+        @endcode

 
 

-        This function is valid in report view only.
+        Please notice that this function makes sense for report view only and
+        currently is only implemented in wxMSW port. To avoid explicit tests
+        for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
+        as this will allow it to start working under the other platforms when
+        support for the column reordering is added there.
+
+        @see GetColumnsOrder()

     */
     */

-    bool SetColumnOrder(const wxArrayInt& orders) const;
+    bool SetColumnsOrder(const wxArrayInt& orders) const;

 
     /**
         Sets the image list associated with the control.
 
     /**
         Sets the image list associated with the control.


@@ -786,7 +843,7 @@ public:
         using the specified @a fnSortCallBack function. This function must have the
         following prototype:
         @code
         using the specified @a fnSortCallBack function. This function must have the
         following prototype:
         @code

-        int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
+        int wxCALLBACK wxListCompareFunction(long item1, long item2, wxIntPtr sortData)

         @endcode
 
         It is called each time when the two items must be compared and should return 0
         @endcode
 
         It is called each time when the two items must be compared and should return 0


@@ -804,7 +861,7 @@ public:
 
         Please see the @ref page_samples_listctrl for an example of using this function.
     */
 
         Please see the @ref page_samples_listctrl for an example of using this function.
     */

-    bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
+    bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);

 
 protected:
 
 
 protected:
 


@@ -818,10 +875,28 @@ protected:
 
         The base class version always returns @NULL.
 
 
         The base class version always returns @NULL.
 

-        @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText()
+        @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
+             OnGetItemColumnAttr()

     */
     virtual wxListItemAttr* OnGetItemAttr(long item) const;
 
     */
     virtual wxListItemAttr* OnGetItemAttr(long item) const;
 

+     /**
+        This function may be overridden in the derived class for a control with
+        @c wxLC_VIRTUAL style.
+
+        It should return the attribute for the for the specified @a item and @a
+        column or @NULL to use the default appearance parameters.
+
+        The base class version returns @c OnGetItemAttr(item).
+
+        @note Currently this function is only called under wxMSW, the other
+            ports only support OnGetItemAttr()
+
+        @see OnGetItemAttr(), OnGetItemText(),
+             OnGetItemImage(), OnGetItemColumnImage(),
+    */
+    virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
+

     /**
         Overload this function in the derived class for a control with
         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
     /**
         Overload this function in the derived class for a control with
         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image


@@ -830,14 +905,15 @@ protected:
         The base class version always calls OnGetItemImage() for the first column, else
         it returns -1.
 
         The base class version always calls OnGetItemImage() for the first column, else
         it returns -1.
 

-        @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr()
+        @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
+             OnGetItemColumnAttr()

     */
     virtual int OnGetItemColumnImage(long item, long column) const;
 
     /**
         This function must be overloaded in the derived class for a control with
     */
     virtual int OnGetItemColumnImage(long item, long column) const;
 
     /**
         This function must be overloaded in the derived class for a control with

-        @c wxLC_VIRTUAL style having an @ref SetImageList() "image list"
-        (if the control doesn't have an image list, it is not necessary to overload it).
+        @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
+        control doesn't have an image list, it is not necessary to overload it).

         It should return the index of the items image in the controls image list
         or -1 for no image.
 
         It should return the index of the items image in the controls image list
         or -1 for no image.
 


@@ -923,7 +999,7 @@ public:
     /**
         Constructor.
     */
     /**
         Constructor.
     */

-    wxListEvent(wxEventType commandType = 0, int id = 0);
+    wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);

 
     /**
         For @c EVT_LIST_CACHE_HINT event only: return the first item which the
 
     /**
         For @c EVT_LIST_CACHE_HINT event only: return the first item which the


@@ -1009,7 +1085,7 @@ public:
     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
 
     @library{wxbase}
     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
 
     @library{wxbase}

-    @category{ctrl}
+    @category{data}

 
     @see @ref overview_listctrl, wxListCtrl, wxListItem
 */
 
     @see @ref overview_listctrl, wxListCtrl, wxListItem
 */


@@ -1025,9 +1101,9 @@ public:
         Construct a wxListItemAttr with the specified foreground and
         background colors and font.
     */
         Construct a wxListItemAttr with the specified foreground and
         background colors and font.
     */

-    wxListItemAttr(const wxColour colText,
-                   const wxColour colBack,
-                   const wxFont font);
+    wxListItemAttr(const wxColour& colText,
+                   const wxColour& colBack,
+                   const wxFont& font);

 
     /**
         Returns the currently set background color.
 
     /**
         Returns the currently set background color.


@@ -1221,7 +1297,7 @@ enum wxListColumnFormat
     If the colour/font is not specified, the default list control colour/font is used.
 
     @library{wxbase}
     If the colour/font is not specified, the default list control colour/font is used.
 
     @library{wxbase}

-    @category{ctrl}
+    @category{data}

 
     @see wxListCtrl
 */
 
     @see wxListCtrl
 */