Move code removing "-psn_xxx" command line arguments to common code.

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

diff --git a/interface/wx/treelist.h b/interface/wx/treelist.h
index 66f861031446ced2a64f5a20d7651163651ea9ff..6928a2d91d67d22c699a15077ec5abfee743efb5 100644 (file)
--- a/interface/wx/treelist.h
+++ b/interface/wx/treelist.h
@@ -3,12 +3,45 @@
 // Purpose:     wxTreeListCtrl class documentation
 // Author:      Vadim Zeitlin
 // Created:     2011-08-17
 // Purpose:     wxTreeListCtrl class documentation
 // Author:      Vadim Zeitlin
 // Created:     2011-08-17

-// RCS-ID:      $Id$

 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
 // Licence:     wxWindows licence
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
 // Licence:     wxWindows licence
 ///////////////////////////////////////////////////////////////////////////////
 
 /**

+   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.
+    /**
+        Don't show the column headers.
+
+        By default this control shows the column headers, using this class
+        allows to avoid this and show only the data.
+
+        @since 2.9.5
+     */
+    wxTL_NO_HEADER      = 0x0010,
+
+    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
     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 +71,74 @@ public:
     bool IsOk() const;
 };
 
     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;
 
 /**
     Container of multiple items.
  */
 typedef wxVector<wxTreeListItem> wxTreeListItems;
 

+

 /**
     Special wxTreeListItem value meaning "insert before the first item".
 
 /**
     Special wxTreeListItem value meaning "insert before the first item".
 


@@ -51,6 +147,7 @@ typedef wxVector<wxTreeListItem> wxTreeListItems;
  */
 extern const wxTreeListItem wxTLI_FIRST;
 
  */
 extern const wxTreeListItem wxTLI_FIRST;
 

+

 /**
     Special wxTreeListItem value meaning "insert after the last item".
 
 /**
     Special wxTreeListItem value meaning "insert after the last item".
 


@@ -59,7 +156,10 @@ extern const wxTreeListItem wxTLI_FIRST;
  */
 extern const wxTreeListItem wxTLI_LAST;
 
  */
 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
     A control combining wxTreeCtrl and wxListCtrl features.
 
     This is a multi-column tree control optionally supporting images and


@@ -81,6 +181,19 @@ extern const wxTreeListItem wxTLI_LAST;
     the other columns.
 
 
     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.
     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.


@@ -105,7 +218,7 @@ extern const wxTreeListItem wxTLI_LAST;
 
     @beginEventTable{wxTreeListEvent}
     @event{EVT_TREELIST_SELECTION_CHANGED(id, func)}
 
     @beginEventTable{wxTreeListEvent}
     @event{EVT_TREELIST_SELECTION_CHANGED(id, func)}

-        Process @c wxEVT_COMMAND_TREELIST_SELECTION_CHANGED event and notifies
+        Process @c wxEVT_TREELIST_SELECTION_CHANGED event and notifies

         about the selection change in the control. In the single selection case
         the item indicated by the event has been selected and previously
         selected item, if any, was deselected. In multiple selection case, the
         about the selection change in the control. In the single selection case
         the item indicated by the event has been selected and previously
         selected item, if any, was deselected. In multiple selection case, the


@@ -114,24 +227,29 @@ extern const wxTreeListItem wxTLI_LAST;
         could have changed as well, use wxTreeListCtrl::GetSelections() to
         retrieve the new selection if necessary.
     @event{EVT_TREELIST_ITEM_EXPANDING(id, func)}
         could have changed as well, use wxTreeListCtrl::GetSelections() to
         retrieve the new selection if necessary.
     @event{EVT_TREELIST_ITEM_EXPANDING(id, func)}

-        Process @c wxEVT_COMMAND_TREELIST_ITEM_EXPANDING event notifying about
+        Process @c wxEVT_TREELIST_ITEM_EXPANDING event notifying about

         the given branch being expanded. This event is sent before the
         expansion occurs and can be vetoed to prevent it from happening.
     @event{EVT_TREELIST_ITEM_EXPANDED(id, func)}
         the given branch being expanded. This event is sent before the
         expansion occurs and can be vetoed to prevent it from happening.
     @event{EVT_TREELIST_ITEM_EXPANDED(id, func)}

-        Process @c wxEVT_COMMAND_TREELIST_ITEM_EXPANDED event notifying about
+        Process @c wxEVT_TREELIST_ITEM_EXPANDED event notifying about

         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)}
         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_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.
     @event{EVT_TREELIST_ITEM_ACTIVATED(id, func)}
         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.
     @event{EVT_TREELIST_ITEM_ACTIVATED(id, func)}

-        Process @c wxEVT_COMMAND_TREELIST_ITEM_ACTIVATED event notifying about
+        Process @c wxEVT_TREELIST_ITEM_ACTIVATED event notifying about

         the user double clicking the item or activating it from keyboard.
     @event{EVT_TREELIST_ITEM_CONTEXT_MENU(id, func)}
         the user double clicking the item or activating it from keyboard.
     @event{EVT_TREELIST_ITEM_CONTEXT_MENU(id, func)}

-        Process @c wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU event indicating
+        Process @c wxEVT_TREELIST_ITEM_CONTEXT_MENU event indicating

         that the popup menu for the given item should be displayed.
         that the popup menu for the given item should be displayed.

+    @event{EVT_TREELIST_COLUMN_SORTED(id, func)}
+        Process @c wxEVT_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}
     @endEventTable
 
     @library{wxadv}


@@ -243,12 +361,15 @@ public:
         @param width
             The width of the column in pixels or the special
             wxCOL_WIDTH_AUTOSIZE value indicating that the column should adjust
         @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
         @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.
      */
         @return
             Index of the new column or -1 on failure.
      */


@@ -283,6 +404,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.
 
         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);
 
      */
     void SetColumnWidth(unsigned col, int width);
 


@@ -335,6 +459,8 @@ public:
             wxTLI_FIRST or wxTLI_LAST indicating that the item should be either
             inserted before the first child of its parent (if any) or after the
             last one.
             wxTLI_FIRST or wxTLI_LAST indicating that the item should be either
             inserted before the first child of its parent (if any) or after the
             last one.

+        @param text
+            The item text.

         @param imageClosed
             The normal item image, may be NO_IMAGE to not show any image.
         @param imageOpened
         @param imageClosed
             The normal item image, may be NO_IMAGE to not show any image.
         @param imageOpened


@@ -664,8 +790,105 @@ public:
                                wxCheckBoxState state) const;
 
     //@}
                                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.
 
 /**
     Event generated by wxTreeListCtrl.
 


@@ -674,6 +897,8 @@ public:
 class wxTreeListEvent : public wxNotifyEvent
 {
 public:
 class wxTreeListEvent : public wxNotifyEvent
 {
 public:

+    wxTreeListEvent();
+

     /**
         Return the item affected by the event.
 
     /**
         Return the item affected by the event.
 


@@ -685,13 +910,21 @@ public:
     /**
         Return the previous state of the item checkbox.
 
     /**
         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_TREELIST_ITEM_CHECKED

         events only.
 
         Notice that the new state of the item can be retrieved using
         wxTreeListCtrl::GetCheckedState().
      */
     wxCheckBoxState GetOldCheckedState() const;
         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_TREELIST_COLUMN_SORTED
+        event.
+     */
+    unsigned GetColumn() const;

 };
 
 
 };
 
 


@@ -704,4 +937,11 @@ public:
 #define wxTreeListEventHandler(func) \
     wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
 
 #define wxTreeListEventHandler(func) \
     wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
 

-#endif // _WX_TREELIST_H_
+
+wxEventType wxEVT_TREELIST_SELECTION_CHANGED;
+wxEventType wxEVT_TREELIST_ITEM_EXPANDING;
+wxEventType wxEVT_TREELIST_ITEM_EXPANDED;
+wxEventType wxEVT_TREELIST_ITEM_CHECKED;
+wxEventType wxEVT_TREELIST_ITEM_ACTIVATED;
+wxEventType wxEVT_TREELIST_ITEM_CONTEXT_MENU;
+wxEventType wxEVT_TREELIST_COLUMN_SORTED;