synchronize GTK2 minimum version in docs

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

diff --git a/include/wx/treelist.h b/include/wx/treelist.h
index dee836d209be6ff74ee75b7552962dc7a2e12faa..081ecb09cac644e42e47af38326ca32df1723127 100644 (file)
--- a/include/wx/treelist.h
+++ b/include/wx/treelist.h
@@ -15,6 +15,7 @@
 
 #if wxUSE_TREELISTCTRL
 
 
 #if wxUSE_TREELISTCTRL
 

+#include "wx/compositewin.h"

 #include "wx/containr.h"
 #include "wx/headercol.h"
 #include "wx/itemid.h"
 #include "wx/containr.h"
 #include "wx/headercol.h"
 #include "wx/itemid.h"


@@ -25,8 +26,9 @@
 class WXDLLIMPEXP_FWD_ADV wxDataViewCtrl;
 class WXDLLIMPEXP_FWD_ADV wxDataViewEvent;
 
 class WXDLLIMPEXP_FWD_ADV wxDataViewCtrl;
 class WXDLLIMPEXP_FWD_ADV wxDataViewEvent;
 

-extern WXDLLIMPEXP_DATA_CORE(const char) wxTreeListCtrlNameStr[];
+extern WXDLLIMPEXP_DATA_ADV(const char) wxTreeListCtrlNameStr[];

 
 

+class wxTreeListCtrl;

 class wxTreeListModel;
 class wxTreeListModelNode;
 
 class wxTreeListModel;
 class wxTreeListModelNode;
 


@@ -76,6 +78,33 @@ typedef wxVector<wxTreeListItem> wxTreeListItems;
 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_FIRST;
 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_LAST;
 
 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_FIRST;
 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_LAST;
 

+// ----------------------------------------------------------------------------
+// wxTreeListItemComparator: defines order of wxTreeListCtrl items.
+// ----------------------------------------------------------------------------
+
+class wxTreeListItemComparator
+{
+public:
+    wxTreeListItemComparator() { }
+
+    // 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.
+    virtual int
+    Compare(wxTreeListCtrl* treelist,
+            unsigned column,
+            wxTreeListItem first,
+            wxTreeListItem second) = 0;
+
+    // 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() { }
+
+private:
+    wxDECLARE_NO_COPY_CLASS(wxTreeListItemComparator);
+};
+

 // ----------------------------------------------------------------------------
 // wxTreeListCtrl: a control combining wxTree- and wxListCtrl features.
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 // wxTreeListCtrl: a control combining wxTree- and wxListCtrl features.
 // ----------------------------------------------------------------------------


@@ -88,8 +117,9 @@ extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_LAST;
 // with wxDataViewCtrl directly but doing this makes your unportable to possible
 // future non-wxDataViewCtrl-based implementations of this class.
 
 // with wxDataViewCtrl directly but doing this makes your unportable to possible
 // future non-wxDataViewCtrl-based implementations of this class.
 

-class WXDLLIMPEXP_ADV wxTreeListCtrl : public wxNavigationEnabled<wxWindow>,
-                                       public wxWithImages
+class WXDLLIMPEXP_ADV wxTreeListCtrl
+    : public wxCompositeWindow< wxNavigationEnabled<wxWindow> >,
+      public wxWithImages

 {
 public:
     // Constructors and such
 {
 public:
     // Constructors and such


@@ -320,10 +350,53 @@ public:
                                wxCheckBoxState state) const;
 
 
                                wxCheckBoxState state) const;
 
 

+
+    // Sorting.
+    // --------
+
+    // Sort by the given column, either in ascending (default) or descending
+    // sort order.
+    //
+    // By default, simple alphabetical sorting is done by this column contents
+    // but SetItemComparator() may be called to perform comparison in some
+    // other way.
+    void SetSortColumn(unsigned col, bool ascendingOrder = true);
+
+    // If the control contents is sorted, return true and fill the output
+    // parameters with the column which is currently used for sorting and
+    // whether we sort using ascending or descending order. Otherwise, i.e. if
+    // the control contents is unsorted, simply return false.
+    bool GetSortColumn(unsigned* col, bool* ascendingOrder = NULL);
+
+    // Set the object to use for comparing the items. It will be called when
+    // the control is being sorted because the user clicked on a sortable
+    // column.
+    //
+    // 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 functions.
+    // ----------------------
+
+    // 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 the first function only and only use the
+    // second one if you really need to call wxDataViewCtrl methods on it.
+    wxWindow* GetView() const;
+    wxDataViewCtrl* GetDataView() const { return m_view; }
+

 private:
     // Common part of all ctors.
     void Init();
 
 private:
     // Common part of all ctors.
     void Init();
 

+    // Pure virtual method inherited from wxCompositeWindow.
+    virtual wxWindowList GetCompositeWindowParts() const;
+

     // Implementation of AppendColumn().
     int DoInsertColumn(const wxString& title,
                        int pos,     // May be -1 meaning "append".
     // Implementation of AppendColumn().
     int DoInsertColumn(const wxString& title,
                        int pos,     // May be -1 meaning "append".


@@ -339,10 +412,14 @@ private:
                                 int imageOpened,
                                 wxClientData* data);
 
                                 int imageOpened,
                                 wxClientData* data);
 

-    // Send wxTreeListEvent corresponding to the given wxDataViewEvent.
+    // Send wxTreeListEvent corresponding to the given wxDataViewEvent for an
+    // item (as opposed for column-oriented events).

     //
     // Also updates the original event "skipped" and "vetoed" flags.
     //
     // Also updates the original event "skipped" and "vetoed" flags.

-    void SendEvent(wxEventType evt, wxDataViewEvent& event);
+    void SendItemEvent(wxEventType evt, wxDataViewEvent& event);
+
+    // Send wxTreeListEvent corresponding to the given column wxDataViewEvent.
+    void SendColumnEvent(wxEventType evt, wxDataViewEvent& event);

 
 
     // Called by wxTreeListModel when an item is toggled by the user.
 
 
     // Called by wxTreeListModel when an item is toggled by the user.


@@ -354,6 +431,7 @@ private:
     void OnItemExpanded(wxDataViewEvent& event);
     void OnItemActivated(wxDataViewEvent& event);
     void OnItemContextMenu(wxDataViewEvent& event);
     void OnItemExpanded(wxDataViewEvent& event);
     void OnItemActivated(wxDataViewEvent& event);
     void OnItemContextMenu(wxDataViewEvent& event);

+    void OnColumnSorted(wxDataViewEvent& event);

     void OnSize(wxSizeEvent& event);
 
     wxDECLARE_EVENT_TABLE();
     void OnSize(wxSizeEvent& event);
 
     wxDECLARE_EVENT_TABLE();


@@ -362,6 +440,8 @@ private:
     wxDataViewCtrl* m_view;
     wxTreeListModel* m_model;
 
     wxDataViewCtrl* m_view;
     wxTreeListModel* m_model;
 

+    wxTreeListItemComparator* m_comparator;
+

 
     // It calls our inherited protected wxWithImages::GetImage() method.
     friend class wxTreeListModel;
 
     // It calls our inherited protected wxWithImages::GetImage() method.
     friend class wxTreeListModel;


@@ -373,19 +453,34 @@ private:
 // wxTreeListEvent: event generated by wxTreeListCtrl.
 // ----------------------------------------------------------------------------
 
 // wxTreeListEvent: event generated by wxTreeListCtrl.
 // ----------------------------------------------------------------------------
 

-class wxTreeListEvent : public wxNotifyEvent
+class WXDLLIMPEXP_ADV wxTreeListEvent : public wxNotifyEvent

 {
 public:
 {
 public:

-    // The item affected by the event.
+    // Default ctor is provided for wxRTTI needs only but should never be used.
+    wxTreeListEvent() { Init(); }
+
+    // The item affected by the event. Valid for all events except
+    // column-specific ones such as COLUMN_SORTED.

     wxTreeListItem GetItem() const { return m_item; }
 
     // The previous state of the item checkbox for ITEM_CHECKED events only.
     wxCheckBoxState GetOldCheckedState() const { return m_oldCheckedState; }
 
     wxTreeListItem GetItem() const { return m_item; }
 
     // The previous state of the item checkbox for ITEM_CHECKED events only.
     wxCheckBoxState GetOldCheckedState() const { return m_oldCheckedState; }
 

+    // The index of the column affected by the event. Currently only used by
+    // COLUMN_SORTED event.
+    unsigned GetColumn() const { return m_column; }

 
     virtual wxEvent* Clone() const { return new wxTreeListEvent(*this); }
 
 private:
 
     virtual wxEvent* Clone() const { return new wxTreeListEvent(*this); }
 
 private:

+    // Common part of all ctors.
+    void Init()
+    {
+        m_column = static_cast<unsigned>(-1);
+
+        m_oldCheckedState = wxCHK_UNDETERMINED;
+    }
+

     // Ctor is private, only wxTreeListCtrl can create events of this type.
     wxTreeListEvent(wxEventType evtType,
                     wxTreeListCtrl* treelist,
     // Ctor is private, only wxTreeListCtrl can create events of this type.
     wxTreeListEvent(wxEventType evtType,
                     wxTreeListCtrl* treelist,


@@ -394,6 +489,8 @@ private:
           m_item(item)
     {
         SetEventObject(treelist);
           m_item(item)
     {
         SetEventObject(treelist);

+
+        Init();

     }
 
     // Set the checkbox state before this event for ITEM_CHECKED events.
     }
 
     // Set the checkbox state before this event for ITEM_CHECKED events.


@@ -402,14 +499,22 @@ private:
         m_oldCheckedState = state;
     }
 
         m_oldCheckedState = state;
     }
 

+    // Set the column affected by this event for COLUMN_SORTED events.
+    void SetColumn(unsigned column)
+    {
+        m_column = column;
+    }
+

 
     const wxTreeListItem m_item;
 
     wxCheckBoxState m_oldCheckedState;
 
 
     const wxTreeListItem m_item;
 
     wxCheckBoxState m_oldCheckedState;
 

+    unsigned m_column;
+

     friend class wxTreeListCtrl;
 
     friend class wxTreeListCtrl;
 

-    wxDECLARE_ABSTRACT_CLASS(wxTreeListEvent);
+    wxDECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxTreeListEvent);

 };
 
 // Event types and event table macros.
 };
 
 // Event types and event table macros.


@@ -451,6 +556,10 @@ wxDECLARE_TREELIST_EVENT(ITEM_CONTEXT_MENU);
 #define EVT_TREELIST_ITEM_CONTEXT_MENU(id, fn) \
     wxEVT_TREELIST_GENERIC(ITEM_CONTEXT_MENU, id, fn)
 
 #define EVT_TREELIST_ITEM_CONTEXT_MENU(id, fn) \
     wxEVT_TREELIST_GENERIC(ITEM_CONTEXT_MENU, id, fn)
 

+wxDECLARE_TREELIST_EVENT(COLUMN_SORTED);
+#define EVT_TREELIST_COLUMN_SORTED(id, fn) \
+    wxEVT_TREELIST_GENERIC(COLUMN_SORTED, id, fn)
+

 #undef wxDECLARE_TREELIST_EVENT
 
 #endif // wxUSE_TREELISTCTRL
 #undef wxDECLARE_TREELIST_EVENT
 
 #endif // wxUSE_TREELISTCTRL