X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0a98423eb038738b5c4c76c575435034ee8b7d56..b8737371e220ef1920e6a3d2aed88c4bc2b04daf:/interface/wx/listctrl.h

diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index d6ede9abb4..c6252bca22 100644
--- a/interface/wx/listctrl.h
+++ b/interface/wx/listctrl.h
@@ -1,9 +1,9 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        listctrl.h
+// Name:        wx/listctrl.h
 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -19,10 +19,11 @@
     and attributes) is managed by the main program and is requested by the control
     itself only when needed which allows to have controls with millions of items
     without consuming much memory. To use virtual list control you must use
-    wxListCtrl::SetItemCount first and overload at least wxListCtrl::OnGetItemText
+    wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText
     (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,47 +83,68 @@
     @endStyleTable
 
 
-    @beginEventTable{wxListEvent}
+    @beginEventEmissionTable{wxListEvent}
     @event{EVT_LIST_BEGIN_DRAG(id, func)}
            Begin dragging with the left mouse button.
+          Processes a @c wxEVT_COMMAND_LIST_BEGIN_DRAG event type.
     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
-           Begin dragging with the right mouse button..
+           Begin dragging with the right mouse button.
+           Processes a @c wxEVT_COMMAND_LIST_BEGIN_RDRAG event type.
     @event{EVT_BEGIN_LABEL_EDIT(id, func)}
            Begin editing a label. This can be prevented by calling Veto().
+           Processes a @c wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT event type.
     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
            Finish editing a label. This can be prevented by calling Veto().
+           Processes a @c wxEVT_COMMAND_LIST_END_LABEL_EDIT event type.
     @event{EVT_LIST_DELETE_ITEM(id, func)}
            An item was deleted.
+           Processes a @c wxEVT_COMMAND_LIST_DELETE_ITEM event type.
     @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
            All items were deleted.
+           Processes a @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event type.
     @event{EVT_LIST_ITEM_SELECTED(id, func)}
            The item has been selected.
+           Processes a @c wxEVT_COMMAND_LIST_ITEM_SELECTED event type.
     @event{EVT_LIST_ITEM_DESELECTED(id, func)}
            The item has been deselected.
+           Processes a @c wxEVT_COMMAND_LIST_ITEM_DESELECTED event type.
     @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
            The item has been activated (ENTER or double click).
+           Processes a @c wxEVT_COMMAND_LIST_ITEM_ACTIVATED event type.
     @event{EVT_LIST_ITEM_FOCUSED(id, func)}
            The currently focused item has changed.
+           Processes a @c wxEVT_COMMAND_LIST_ITEM_FOCUSED event type.
     @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
-           The middle mouse button has been clicked on an item.
+           The middle mouse button has been clicked on an item. This is
+           only supported by the generic control.
+           Processes a @c wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK event type.
     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
           The right mouse button has been clicked on an item.
+          Processes a @c wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK event type.
     @event{EVT_LIST_KEY_DOWN(id, func)}
            A key has been pressed.
+           Processes a @c wxEVT_COMMAND_LIST_KEY_DOWN event type.
     @event{EVT_LIST_INSERT_ITEM(id, func)}
            An item has been inserted.
+           Processes a @c wxEVT_COMMAND_LIST_INSERT_ITEM event type.
     @event{EVT_LIST_COL_CLICK(id, func)}
            A column (m_col) has been left-clicked.
+           Processes a @c wxEVT_COMMAND_LIST_COL_CLICK event type.
     @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
            A column (m_col) has been right-clicked.
+           Processes a @c wxEVT_COMMAND_LIST_COL_RIGHT_CLICK event type.
     @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
            The user started resizing a column - can be vetoed.
+           Processes a @c wxEVT_COMMAND_LIST_COL_BEGIN_DRAG event type.
     @event{EVT_LIST_COL_DRAGGING(id, func)}
            The divider between columns is being dragged.
+           Processes a @c wxEVT_COMMAND_LIST_COL_DRAGGING event type.
     @event{EVT_LIST_COL_END_DRAG(id, func)}
            A column has been resized by the user.
+           Processes a @c wxEVT_COMMAND_LIST_COL_END_DRAG event type.
     @event{EVT_LIST_CACHE_HINT(id, func)}
            Prepare cache for a virtual list control.
+           Processes a @c wxEVT_COMMAND_LIST_CACHE_HINT event type.
     @endEventTable
 
 
@@ -160,9 +172,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
@@ -206,6 +219,9 @@ public:
 
     /**
         Deletes all items and all columns.
+
+        @note  This sends an event of type @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS
+               under all platforms.
     */
     void ClearAll();
 
@@ -222,9 +238,15 @@ public:
     /**
         Deletes all items in the list control.
 
-        @note This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
-              event because deleting many items from the control would be too slow
-              then (unlike wxListCtrl::DeleteItem).
+        This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
+        event because deleting many items from the control would be too slow
+        then (unlike wxListCtrl::DeleteItem) but it does send the special @c
+        wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event if the control was not empty.
+        If it was already empty, nothing is done and no event is sent.
+
+        @return @true if the items were successfully deleted or if the control
+            was already empty, @false if an error occurred while deleting the
+            items.
     */
     bool DeleteAllItems();
 
@@ -253,7 +275,30 @@ public:
         will be sent which can be vetoed as well.
     */
     wxTextCtrl* EditLabel(long item,
-                          wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
+                          wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl));
+
+    /**
+        Finish editing the label.
+
+        This method allows to programmatically end editing a list control item
+        in place. Usually it will only be called when editing is in progress,
+        i.e. if GetEditControl() returns non-NULL. In particular, do not call
+        it from EVT_LIST_BEGIN_LABEL_EDIT handler as the edit control is not
+        yet fully created by then, just veto the event in this handler instead
+        to prevent the editing from even starting.
+
+        Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT
+        event being generated.
+
+        Currently only implemented in wxMSW.
+
+        @param cancel If @true, discard the changes made by user, as if @c
+            Escape key was pressed. Otherwise, accept the changes as if @c
+            Return was pressed.
+        @return @true if item editing wad finished or @false if no item as
+            being edited.
+     */
+    bool EndEditLabel(bool cancel);
 
     /**
         Ensures this item is visible.
@@ -265,6 +310,8 @@ public:
         beginning if start is @c -1. The string comparison is case insensitive.
 
         If @a partial is @true then this method will look for items which begin with @a str.
+
+        @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
     */
     long FindItem(long start, const wxString& str,
                   bool partial = false);
@@ -272,18 +319,35 @@ public:
     /**
         Find an item whose data matches this data, starting from start or the
         beginning if 'start' is @c -1.
+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as FindItemData(start, data).
+        @endWxPerlOnly
+
+        @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
     */
     long FindItem(long start, wxUIntPtr data);
 
     /**
         Find an item nearest this position in the specified direction,
         starting from @a start or the beginning if @a start is -1.
+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
+        @endWxPerlOnly
+
+        @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
     */
     long FindItem(long start, const wxPoint& pt, int direction);
 
     /**
         Gets information about this column.
         See SetItem() for more information.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes only the @a col parameter and
+        returns a @c Wx::ListItem (or @c undef).
+        @endWxPerlOnly
     */
     bool GetColumn(int col, wxListItem& item) const;
 
@@ -293,12 +357,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 +391,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;
 
@@ -339,8 +427,15 @@ public:
 
     /**
         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.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes as parameter the ID of the item
+        and (optionally) the column, and returns a Wx::ListItem object.
+        @endWxPerlOnly
     */
     bool GetItem(wxListItem& info) const;
 
@@ -370,6 +465,11 @@ public:
 
     /**
         Returns the position of the item, in icon or small icon view.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes only the @a item parameter and
+        returns a @c Wx::Point (or @c undef).
+        @endWxPerlOnly
     */
     bool GetItemPosition(long item, wxPoint& pos) const;
 
@@ -378,6 +478,11 @@ public:
         coordinates.
 
         @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes only the @a item and @a code parameters and
+        returns a @c Wx::Rect (or @c undef).
+        @endWxPerlOnly
     */
     bool GetItemRect(long item, wxRect& rect,
                      int code = wxLIST_RECT_BOUNDS) const;
@@ -397,8 +502,14 @@ public:
 
     /**
         Gets the item text for this item.
+
+        @param item
+            Item (zero-based) index.
+        @param col
+            Item column (zero-based) index. Column 0 is the default. This
+            parameter is new in wxWidgets 2.9.1.
     */
-    wxString GetItemText(long item) const;
+    wxString GetItemText(long item, int col = 0) const;
 
     /**
         Returns the colour for this item.
@@ -523,6 +634,11 @@ public:
         the host system or the value stored in @a ptrSubItem will be always -1.
         To compile this feature into wxWidgets library you need to have access to
         commctrl.h of version 4.70 that is provided by Microsoft.
+
+        @beginWxPerlOnly
+        In wxPerl this method only takes the @a point parameter
+        and returns a 2-element list (item, flags).
+        @endWxPerlOnly
     */
     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 
@@ -553,6 +669,10 @@ public:
             Index of the new item, supplied by the application
         @param label
             String label
+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as InsertStringItem(index, label).
+        @endWxPerlOnly
     */
     long InsertItem(long index, const wxString& label);
 
@@ -563,6 +683,10 @@ public:
             Index of the new item, supplied by the application
         @param imageIndex
             Index into the image list associated with this control and view style
+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
+        @endWxPerlOnly
     */
     long InsertItem(long index, int imageIndex);
 
@@ -575,6 +699,10 @@ public:
             String label
         @param imageIndex
             Index into the image list associated with this control and view style
+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
+        @endWxPerlOnly
     */
     long InsertItem(long index, const wxString& label,
                     int imageIndex);
@@ -639,14 +767,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.
@@ -786,7 +953,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
@@ -803,13 +970,19 @@ public:
         items in the control.
 
         Please see the @ref page_samples_listctrl for an example of using this function.
+
+        @beginWxPerlOnly
+        In wxPerl the comparison function must take just two parameters;
+        however, you may use a closure to achieve an effect similar to the
+        SortItems third parameter.
+        @endWxPerlOnly
     */
-    bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
+    bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);
 
 protected:
 
     /**
-        This function may be overloaded in the derived class for a control with
+        This function may be overridden in the derived class for a control with
         @c wxLC_VIRTUAL style. It should return the attribute for the specified
         @c item or @NULL to use the default appearance parameters.
 
@@ -818,26 +991,45 @@ 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
+        Override this function in the derived class for a control with
         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
         index for the given line and column.
 
         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).
+        This function must be overridden in the derived class for a control with
+        @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
+        control doesn't have an image list, it is not necessary to override it).
         It should return the index of the items image in the controls image list
         or -1 for no image.
 
@@ -851,7 +1043,7 @@ protected:
     virtual int OnGetItemImage(long item) const;
 
     /**
-        This function @b must be overloaded in the derived class for a control with
+        This function @b must be overridden in the derived class for a control with
         @c wxLC_VIRTUAL style. It should return the string containing the text of
         the given @a column for the specified @c item.
 
@@ -1009,7 +1201,7 @@ public:
     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
 
     @library{wxbase}
-    @category{ctrl}
+    @category{data}
 
     @see @ref overview_listctrl, wxListCtrl, wxListItem
 */
@@ -1221,7 +1413,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
 */