Use /bin/echo for creation of Mac OS X PkgInfo files.

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

diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index bfa9b019bce850d0c23bbba99551374dc9bc31a9..6a7a539801d63c4123db9e74ba64f7aafe935a3f 100644 (file)
--- a/interface/wx/listctrl.h
+++ b/interface/wx/listctrl.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -86,44 +86,65 @@
     @beginEventEmissionTable{wxListEvent}
     @event{EVT_LIST_BEGIN_DRAG(id, func)}
            Begin dragging with the left mouse button.
     @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)}
     @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().
     @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().
     @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.
     @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.
     @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.
     @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.
     @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).
     @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.
     @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)}
     @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.
     @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.
     @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.
     @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.
     @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.
     @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.
     @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.
     @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.
     @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.
     @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
 
 
     @endEventTable
 
 


@@ -176,6 +197,19 @@ public:
     */
     virtual ~wxListCtrl();
 
     */
     virtual ~wxListCtrl();
 

+    /**
+        Adds a new column to the list control in report view mode.
+
+        This is just a convenient wrapper for InsertColumn() which adds the new
+        column after all the existing ones without having to specify its
+        position explicitly.
+
+        @since 2.9.4
+     */
+    long AppendColumn(const wxString& heading,
+                      int format = wxLIST_FORMAT_LEFT,
+                      int width = -1);
+

     /**
         Arranges the items in icon or small icon view.
         This only has effect on Win32. @a flag is one of:
     /**
         Arranges the items in icon or small icon view.
         This only has effect on Win32. @a flag is one of:


@@ -198,6 +232,9 @@ public:
 
     /**
         Deletes all items and all columns.
 
     /**
         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();
 
     */
     void ClearAll();
 


@@ -214,9 +251,15 @@ public:
     /**
         Deletes all items in the list control.
 
     /**
         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();
 
     */
     bool DeleteAllItems();
 


@@ -245,14 +288,20 @@ public:
         will be sent which can be vetoed as well.
     */
     wxTextCtrl* EditLabel(long item,
         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,
 
     /**
         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.
+        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.
 
 
         Currently only implemented in wxMSW.
 


@@ -539,7 +588,7 @@ public:
         coordinates, of the given subitem, i.e. the part of the row @a item in the
         column @a subItem.
 
         coordinates, of the given subitem, i.e. the part of the row @a item in the
         column @a subItem.
 

-        This method is only meaningfull when the wxListCtrl is in the report mode.
+        This method is only meaningful when the wxListCtrl is in the report mode.

         If @a subItem parameter is equal to the special value
         @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
         for GetItemRect().
         If @a subItem parameter is equal to the special value
         @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
         for GetItemRect().


@@ -607,16 +656,53 @@ public:
     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 
     /**
     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 
     /**

-        For report view mode (only), inserts a column. For more details, see SetItem().
+        Returns true if the control is currently using ::wxLC_REPORT style.
+     */
+    bool InReportView() const;
+
+    /**
+        For report view mode (only), inserts a column.
+
+        For more details, see SetItem(). Also see InsertColumn(long, const
+        wxString&, int, int) overload for a usually more convenient
+        alternative to this method and the description of how the item width
+        is interpreted by this method.

     */
     */

-    long InsertColumn(long col, wxListItem& info);
+    long InsertColumn(long col, const wxListItem& info);

 
     /**
 
     /**

-        For report view mode (only), inserts a column. For more details, see SetItem().
+        For report view mode (only), inserts a column.
+
+        Insert a new column in the list control in report view mode at the
+        given position specifying its most common attributes.
+
+        Notice that to set the image for the column you need to use
+        Insert(long, const wxListItem&) overload and specify ::wxLIST_MASK_IMAGE
+        in the item mask.
+
+        @param col
+            The index where the column should be inserted. Valid indices are
+            from 0 up to GetColumnCount() inclusive and the latter can be used
+            to append the new column after the last existing one.
+        @param heading
+            The string specifying the column heading.
+        @param format
+            The flags specifying the control heading text alignment.
+        @param width
+            If positive, the width of the column in pixels. Otherwise it can be
+            @c wxLIST_AUTOSIZE to choose the default size for the column or @c
+            wxLIST_AUTOSIZE_USEHEADER to fit the column width to @a heading or
+            to extend to fill all the remaining space for the last column.
+            Notice that in case of @c wxLIST_AUTOSIZE fixed width is used as
+            there are no items in this column to use for determining its best
+            size yet. If you want to fit the column to its contents, use
+            SetColumnWidth() after adding the items with values in this column.
+        @return
+            The index of the inserted column or -1 if adding it failed.

     */
     long InsertColumn(long col, const wxString& heading,
                       int format = wxLIST_FORMAT_LEFT,
     */
     long InsertColumn(long col, const wxString& heading,
                       int format = wxLIST_FORMAT_LEFT,

-                      int width = -1);
+                      int width = wxLIST_AUTOSIZE);

 
     /**
         Inserts an item, returning the index of the new item if successful, -1 otherwise.
 
     /**
         Inserts an item, returning the index of the new item if successful, -1 otherwise.


@@ -671,6 +757,11 @@ public:
     long InsertItem(long index, const wxString& label,
                     int imageIndex);
 
     long InsertItem(long index, const wxString& label,
                     int imageIndex);
 

+    /**
+        Returns true if the control is currently in virtual report view.
+     */
+    bool IsVirtual() const;
+

     /**
         Redraws the given @e item.
 
     /**
         Redraws the given @e item.
 


@@ -777,7 +868,7 @@ public:
 
         @see GetColumnsOrder()
     */
 
         @see GetColumnsOrder()
     */

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

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


@@ -917,7 +1008,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, wxIntPtr sortData)
+        int wxCALLBACK wxListCompareFunction(wxIntPtr item1, wxIntPtr 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


@@ -1049,7 +1140,7 @@ protected:
     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
         The right mouse button has been clicked on an item.
     @event{EVT_LIST_KEY_DOWN(id, func)}
     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
         The right mouse button has been clicked on an item.
     @event{EVT_LIST_KEY_DOWN(id, func)}

-        A key has been pressed.
+        A key has been pressed. GetIndex() may be -1 if no item is selected. 

     @event{EVT_LIST_INSERT_ITEM(id, func)}
         An item has been inserted.
     @event{EVT_LIST_COL_CLICK(id, func)}
     @event{EVT_LIST_INSERT_ITEM(id, func)}
         An item has been inserted.
     @event{EVT_LIST_COL_CLICK(id, func)}