X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8148ae02efb18bb8ad10dfd6a1d8dce66fafbed0..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/treelist.h diff --git a/interface/wx/treelist.h b/interface/wx/treelist.h index 5a70301d0a..21649a5f71 100644 --- a/interface/wx/treelist.h +++ b/interface/wx/treelist.h @@ -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 wxTreeListItems; + /** Special wxTreeListItem value meaning "insert before the first item". @@ -51,6 +139,7 @@ typedef wxVector 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); @@ -665,6 +781,71 @@ public: //@} + /** + 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. @@ -696,6 +877,8 @@ public: //@} }; + + /** Event generated by wxTreeListCtrl. @@ -704,6 +887,8 @@ public: class wxTreeListEvent : public wxNotifyEvent { public: + wxTreeListEvent(); + /** Return the item affected by the event. @@ -715,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; }; @@ -734,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;