synchronize GTK2 minimum version in docs
[wxWidgets.git] / interface / wx / treelist.h
index 66f861031446ced2a64f5a20d7651163651ea9ff..21649a5f718fc2a318440f428ddd3446ea066539 100644 (file)
@@ -9,6 +9,31 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
+   wxTreeListCtrl styles.
+
+   Notice that using wxTL_USER_3STATE implies wxTL_3STATE and wxTL_3STATE in
+   turn implies wxTL_CHECKBOX.
+*/
+enum
+{
+    wxTL_SINGLE         = 0x0000,       /// This is the default anyhow.
+    wxTL_MULTIPLE       = 0x0001,       /// Allow multiple selection.
+    wxTL_CHECKBOX       = 0x0002,       /// Show checkboxes in the first column.
+    wxTL_3STATE         = 0x0004,       /// Allow 3rd state in checkboxes.
+    wxTL_USER_3STATE    = 0x0008,       /// Allow user to set 3rd state.
+
+    wxTL_DEFAULT_STYLE  = wxTL_SINGLE,
+    wxTL_STYLE_MASK     = wxTL_SINGLE |
+                          wxTL_MULTIPLE |
+                          wxTL_CHECKBOX |
+                          wxTL_3STATE |
+                          wxTL_USER_3STATE
+};
+
+
+/**
+    @class wxTreeListItem
+   
     Unique identifier of an item in wxTreeListCtrl.
 
     This is an opaque class which can't be used by the application in any other
@@ -38,11 +63,74 @@ public:
     bool IsOk() const;
 };
 
+
+/**
+    @class wxTreeListItemComparator
+   
+    Class defining sort order for the items in wxTreeListCtrl.
+
+    @see wxTreeListCtrl
+
+    @library{wxadv}
+    @category{ctrl}
+
+    @since 2.9.3
+ */
+class wxTreeListItemComparator
+{
+public:
+    /**
+        Default constructor.
+
+        Notice that this class is not copyable, comparators are not passed by
+        value.
+     */
+    wxTreeListItemComparator();
+
+    /**
+        Pure virtual function which must be overridden to define sort order.
+
+        The comparison function should return negative, null or positive value
+        depending on whether the first item is less than, equal to or greater
+        than the second one. The items should be compared using their values
+        for the given column.
+
+        @param treelist
+            The control whose contents is being sorted.
+        @param column
+            The column of this control used for sorting.
+        @param first
+            First item to compare.
+        @param second
+            Second item to compare.
+        @return
+            A negative value if the first item is less than (i.e. should appear
+            above) the second one, zero if the two items are equal or a
+            positive value if the first item is greater than (i.e. should
+            appear below) the second one.
+     */
+    virtual int
+    Compare(wxTreeListCtrl* treelist,
+            unsigned column,
+            wxTreeListItem first,
+            wxTreeListItem second) = 0;
+
+    /**
+        Trivial but virtual destructor.
+
+        Although this class is not used polymorphically by wxWidgets itself,
+        provide virtual dtor in case it's used like this in the user code.
+     */
+    virtual ~wxTreeListItemComparator();
+};
+
+
 /**
     Container of multiple items.
  */
 typedef wxVector<wxTreeListItem> wxTreeListItems;
 
+
 /**
     Special wxTreeListItem value meaning "insert before the first item".
 
@@ -51,6 +139,7 @@ typedef wxVector<wxTreeListItem> wxTreeListItems;
  */
 extern const wxTreeListItem wxTLI_FIRST;
 
+
 /**
     Special wxTreeListItem value meaning "insert after the last item".
 
@@ -59,7 +148,10 @@ extern const wxTreeListItem wxTLI_FIRST;
  */
 extern const wxTreeListItem wxTLI_LAST;
 
+
 /**
+    @class wxTreeListCtrl
+
     A control combining wxTreeCtrl and wxListCtrl features.
 
     This is a multi-column tree control optionally supporting images and
@@ -81,6 +173,19 @@ extern const wxTreeListItem wxTLI_LAST;
     the other columns.
 
 
+    Unlike wxTreeCtrl or wxListCtrl this control can sort its items on its own.
+    To allow user to sort the control contents by clicking on some column you
+    should use wxCOL_SORTABLE flag when adding that column to the control. When
+    a column with this flag is clicked, the control resorts itself using the
+    values in this column. By default the sort is done using alphabetical order
+    comparison of the items text, which is not always correct (e.g. this
+    doesn't work for the numeric columns). To change this you may use
+    SetItemComparator() method to provide a custom comparator, i.e. simply an
+    object that implements comparison between the two items. The treelist
+    sample shows an example of doing this. And if you need to sort the control
+    programmatically, you can call SetSortColumn() method.
+
+
     Here are the styles supported by this control. Notice that using
     wxTL_USER_3STATE implies wxTL_3STATE and wxTL_3STATE in turn implies
     wxTL_CHECKBOX.
@@ -122,7 +227,7 @@ extern const wxTreeListItem wxTLI_LAST;
         the expansion of the given branch. This event is sent after the
         expansion occurs and can't be vetoed.
     @event{EVT_TREELIST_ITEM_CHECKED(id, func)}
-        Process @c wxEVT_COMMAND_TREELIST_ITEM_CHeCKED event notifying about
+        Process @c wxEVT_COMMAND_TREELIST_ITEM_CHECKED event notifying about
         the user checking or unchecking the item. You can use
         wxTreeListCtrl::GetCheckedState() to retrieve the new item state and
         wxTreeListEvent::GetOldCheckedState() to get the previous one.
@@ -132,6 +237,11 @@ extern const wxTreeListItem wxTLI_LAST;
     @event{EVT_TREELIST_ITEM_CONTEXT_MENU(id, func)}
         Process @c wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU event indicating
         that the popup menu for the given item should be displayed.
+    @event{EVT_TREELIST_COLUMN_SORTED(id, func)}
+        Process @c wxEVT_COMMAND_TREELIST_COLUMN_SORTED event indicating that
+        the control contents has just been resorted using the specified column.
+        The event doesn't carry the sort direction, use GetSortColumn() method
+        if you need to know it.
     @endEventTable
 
     @library{wxadv}
@@ -243,12 +353,15 @@ public:
         @param width
             The width of the column in pixels or the special
             wxCOL_WIDTH_AUTOSIZE value indicating that the column should adjust
-            to its contents.
+            to its contents. Notice that the first column is special and will
+            be always resized to fill all the space not taken by the other
+            columns, i.e. the width specified here is ignored for it.
         @param align
             Alignment of both the column header and its items.
         @param flags
-            Column flags, currently can only include wxCOL_RESIZABLE to allow
-            the user to resize the column.
+            Column flags, currently can include wxCOL_RESIZABLE to allow the
+            user to resize the column and wxCOL_SORTABLE to allow the user to
+            resort the control contents by clicking on this column.
         @return
             Index of the new column or -1 on failure.
      */
@@ -283,6 +396,9 @@ public:
 
         Set column width to either the given value in pixels or to the value
         large enough to fit all of the items if width is wxCOL_WIDTH_AUTOSIZE.
+
+        Notice that setting the width of the first column is ignored as this
+        column is always resized to fill the space left by the other columns.
      */
     void SetColumnWidth(unsigned col, int width);
 
@@ -664,8 +780,105 @@ public:
                                wxCheckBoxState state) const;
 
     //@}
+
+    /**
+        Sorting.
+
+        If some control columns were added with wxCOL_SORTABLE flag, clicking
+        on them will automatically resort the control using the custom
+        comparator set by SetItemComparator() or by doing alphabetical
+        comparison by default.
+
+        In any case, i.e. even if the user can't sort the control by clicking
+        on its header, you may call SetSortColumn() to sort it programmatically
+        and call GetSortColumn() to determine whether it's sorted now and, if
+        so, by which column and in which order.
+     */
+    //@{
+
+    /**
+        Set the column to use for sorting and the order in which to sort.
+
+        Calling this method resorts the control contents using the values of
+        the items in the specified column. Sorting uses custom comparator set
+        with SetItemComparator() or alphabetical comparison of items texts if
+        none was specified.
+
+        Notice that currently there is no way to reset sort order.
+
+        @param col
+            A valid column index.
+        @param ascendingOrder
+            Indicates whether the items should be sorted in ascending (A to Z)
+            or descending (Z to A) order.
+     */
+    void SetSortColumn(unsigned col, bool ascendingOrder = true);
+
+    /**
+        Return the column currently used for sorting, if any.
+
+        If the control is currently unsorted, the function simply returns
+        @false and doesn't modify any of its output parameters.
+
+        @param col
+            Receives the index of the column used for sorting if non-@NULL.
+        @param ascendingOrder
+            Receives @true or @false depending on whether the items are sorted
+            in ascending or descending order.
+        @return
+            @true if the control is sorted or @false if it isn't sorted at all.
+     */
+    bool GetSortColumn(unsigned* col, bool* ascendingOrder = NULL);
+
+    /**
+        Set the object to use for comparing the items.
+
+        This object will be used when the control is being sorted because the
+        user clicked on a sortable column or SetSortColumn() was called.
+
+        The provided pointer is stored by the control so the object it points
+        to must have a life-time equal or greater to that of the control
+        itself. In addition, the pointer can be @NULL to stop using custom
+        comparator and revert to the default alphabetical comparison.
+     */
+    void SetItemComparator(wxTreeListItemComparator* comparator);
+
+    //@}
+
+
+    /**
+        View window.
+
+        This control itself is entirely covered by the "view window" which is
+        currently a wxDataViewCtrl but if you want to avoid relying on this to
+        allow your code to work with later versions which might not be
+        wxDataViewCtrl-based, use GetView() function only and only use
+        GetDataView() if you really need to call wxDataViewCtrl methods on it.
+     */
+    //@{
+
+    /**
+        Return the view part of this control as a wxWindow.
+
+        This method always returns non-@NULL pointer once the window was
+        created.
+     */
+    wxWindow* GetView() const;
+
+    /**
+        Return the view part of this control as wxDataViewCtrl.
+
+        This method may return @NULL in the future, non wxDataViewCtrl-based,
+        versions of this class, use GetView() unless you really need to use
+        wxDataViewCtrl methods on the returned object.
+     */
+    wxDataViewCtrl* GetDataView() const;
+
+    //@}
 };
 
+
+
 /**
     Event generated by wxTreeListCtrl.
 
@@ -674,6 +887,8 @@ public:
 class wxTreeListEvent : public wxNotifyEvent
 {
 public:
+    wxTreeListEvent();
+
     /**
         Return the item affected by the event.
 
@@ -685,13 +900,21 @@ public:
     /**
         Return the previous state of the item checkbox.
 
-        This method can be used with @c wxEVT_COMMAND_TREELIST_ITEM_CHeCKED
+        This method can be used with @c wxEVT_COMMAND_TREELIST_ITEM_CHECKED
         events only.
 
         Notice that the new state of the item can be retrieved using
         wxTreeListCtrl::GetCheckedState().
      */
     wxCheckBoxState GetOldCheckedState() const;
+
+    /**
+        Return the column affected by the event.
+
+        This is currently only used with @c wxEVT_COMMAND_TREELIST_COLUMN_SORTED
+        event.
+     */
+    unsigned GetColumn() const;
 };
 
 
@@ -704,4 +927,11 @@ public:
 #define wxTreeListEventHandler(func) \
     wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
 
-#endif // _WX_TREELIST_H_
+
+wxEventType wxEVT_COMMAND_TREELIST_SELECTION_CHANGED;
+wxEventType wxEVT_COMMAND_TREELIST_ITEM_EXPANDING;
+wxEventType wxEVT_COMMAND_TREELIST_ITEM_EXPANDED;
+wxEventType wxEVT_COMMAND_TREELIST_ITEM_CHECKED;
+wxEventType wxEVT_COMMAND_TREELIST_ITEM_ACTIVATED;
+wxEventType wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU;
+wxEventType wxEVT_COMMAND_TREELIST_COLUMN_SORTED;