X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8148ae02efb18bb8ad10dfd6a1d8dce66fafbed0..6f67e6d2e46f53606af07f8a861901ce44fd18b1:/interface/wx/treelist.h?ds=sidebyside diff --git a/interface/wx/treelist.h b/interface/wx/treelist.h index 5a70301d0a..bace73cb6f 100644 --- a/interface/wx/treelist.h +++ b/interface/wx/treelist.h @@ -38,6 +38,64 @@ public: bool IsOk() const; }; +/** + 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. */ @@ -81,6 +139,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 +193,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 +203,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 +319,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 +362,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 +747,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. @@ -715,13 +862,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; }; @@ -733,5 +888,3 @@ public: */ #define wxTreeListEventHandler(func) \ wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func) - -#endif // _WX_TREELIST_H_