X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c86b476dd540ac302ad023dc864c7c7d4f9ed823..574be073c070a9bbe81ad68e98187b0b9e82c2df:/interface/wx/listctrl.h

diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index 9a9b24fb69..bfd05c44af 100644
--- 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$
@@ -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.
+
     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
-    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
-           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
-           with wxLC_REPORT.
+           with @c wxLC_REPORT.
     @style{wxLC_ICON}
            Large icon view, with optional labels.
     @style{wxLC_SMALL_ICON}
@@ -92,7 +83,7 @@
     @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)}
@@ -160,9 +151,10 @@ public:
             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.
-            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
@@ -293,12 +285,30 @@ public:
     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;
 
@@ -309,7 +319,13 @@ public:
 
     /**
         Returns the array containing the orders of all columns.
+
         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;
 
@@ -641,14 +657,53 @@ public:
     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
-        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.
 
-        This function is valid in report view only.
+        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
+
+        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.
@@ -788,7 +843,7 @@ public:
         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
@@ -806,7 +861,7 @@ public:
 
         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:
 
@@ -820,10 +875,28 @@ protected:
 
         The base class version always returns @NULL.
 
-        @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText()
+        @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
+             OnGetItemColumnAttr()
     */
     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
@@ -832,14 +905,15 @@ protected:
         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
-        @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.
 
@@ -1011,7 +1085,7 @@ public:
     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
 
     @library{wxbase}
-    @category{ctrl}
+    @category{data}
 
     @see @ref overview_listctrl, wxListCtrl, wxListItem
 */
@@ -1223,7 +1297,7 @@ enum wxListColumnFormat
     If the colour/font is not specified, the default list control colour/font is used.
 
     @library{wxbase}
-    @category{ctrl}
+    @category{data}
 
     @see wxListCtrl
 */