interface/wx/treelist.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        interface/wx/treelist.h
   3 // Purpose:     wxTreeListCtrl class documentation
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-08-17
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     Unique identifier of an item in wxTreeListCtrl.
  13
  14     This is an opaque class which can't be used by the application in any other
  15     way than receiving or passing it to wxTreeListCtrl and checking for
  16     validity.
  17
  18     @see wxTreeListCtrl
  19
  20     @library{wxadv}
  21     @category{ctrl}
  22
  23     @since 2.9.3
  24  */
  25 class wxTreeListItem
  26 {
  27 public:
  28     /**
  29         Only the default constructor is publicly accessible.
  30
  31         Default constructing a wxTreeListItem creates an invalid item.
  32      */
  33     wxTreeListItem();
  34
  35     /**
  36         Return true if the item is valid.
  37      */
  38     bool IsOk() const;
  39 };
  40
  41 /**
  42     Class defining sort order for the items in wxTreeListCtrl.
  43
  44     @see wxTreeListCtrl
  45
  46     @library{wxadv}
  47     @category{ctrl}
  48
  49     @since 2.9.3
  50  */
  51 class wxTreeListItemComparator
  52 {
  53 public:
  54     /**
  55         Default constructor.
  56
  57         Notice that this class is not copyable, comparators are not passed by
  58         value.
  59      */
  60     wxTreeListItemComparator();
  61
  62     /**
  63         Pure virtual function which must be overridden to define sort order.
  64
  65         The comparison function should return negative, null or positive value
  66         depending on whether the first item is less than, equal to or greater
  67         than the second one. The items should be compared using their values
  68         for the given column.
  69
  70         @param treelist
  71             The control whose contents is being sorted.
  72         @param column
  73             The column of this control used for sorting.
  74         @param first
  75             First item to compare.
  76         @param second
  77             Second item to compare.
  78         @return
  79             A negative value if the first item is less than (i.e. should appear
  80             above) the second one, zero if the two items are equal or a
  81             positive value if the first item is greater than (i.e. should
  82             appear below) the second one.
  83      */
  84     virtual int
  85     Compare(wxTreeListCtrl* treelist,
  86             unsigned column,
  87             wxTreeListItem first,
  88             wxTreeListItem second) = 0;
  89
  90     /**
  91         Trivial but virtual destructor.
  92
  93         Although this class is not used polymorphically by wxWidgets itself,
  94         provide virtual dtor in case it's used like this in the user code.
  95      */
  96     virtual ~wxTreeListItemComparator();
  97 };
  98
  99 /**
 100     Container of multiple items.
 101  */
 102 typedef wxVector<wxTreeListItem> wxTreeListItems;
 103
 104 /**
 105     Special wxTreeListItem value meaning "insert before the first item".
 106
 107     This value can be passed to wxTreeListCtrl::InsertItem() to achieve the
 108     same effect as calling wxTreeListCtrl::PrependItem().
 109  */
 110 extern const wxTreeListItem wxTLI_FIRST;
 111
 112 /**
 113     Special wxTreeListItem value meaning "insert after the last item".
 114
 115     This value can be passed to wxTreeListCtrl::InsertItem() to achieve the
 116     same effect as calling wxTreeListCtrl::AppendItem().
 117  */
 118 extern const wxTreeListItem wxTLI_LAST;
 119
 120 /**
 121     A control combining wxTreeCtrl and wxListCtrl features.
 122
 123     This is a multi-column tree control optionally supporting images and
 124     checkboxes for the items in the first column.
 125
 126     It is currently implemented using wxDataViewCtrl internally but provides a
 127     much simpler interface for the common use case it addresses. Thus, one of
 128     the design principles for this control is simplicity and intentionally
 129     doesn't provide all the features of wxDataViewCtrl. Most importantly, this
 130     class stores all its data internally and doesn't require you to define a
 131     custom model for it.
 132
 133     Instead, this controls works like wxTreeCtrl or non-virtual wxListCtrl and
 134     allows you to simply add items to it using wxTreeListCtrl::AppendItem() and
 135     related methods. Typically, you start by setting up the columns (you must
 136     have at least one) by calling wxTreeListCtrl::AppendColumn() and then add
 137     the items. While only the text of the first column can be specified when
 138     adding them, you can use wxTreeListCtrl::SetItemText() to set the text of
 139     the other columns.
 140
 141
 142     Unlike wxTreeCtrl or wxListCtrl this control can sort its items on its own.
 143     To allow user to sort the control contents by clicking on some column you
 144     should use wxCOL_SORTABLE flag when adding that column to the control. When
 145     a column with this flag is clicked, the control resorts itself using the
 146     values in this column. By default the sort is done using alphabetical order
 147     comparison of the items text, which is not always correct (e.g. this
 148     doesn't work for the numeric columns). To change this you may use
 149     SetItemComparator() method to provide a custom comparator, i.e. simply an
 150     object that implements comparison between the two items. The treelist
 151     sample shows an example of doing this. And if you need to sort the control
 152     programmatically, you can call SetSortColumn() method.
 153
 154
 155     Here are the styles supported by this control. Notice that using
 156     wxTL_USER_3STATE implies wxTL_3STATE and wxTL_3STATE in turn implies
 157     wxTL_CHECKBOX.
 158
 159     @beginStyleTable
 160     @style{wxTL_SINGLE}
 161         Single selection, this is the default.
 162     @style{wxTL_MULTIPLE}
 163         Allow multiple selection, see GetSelections().
 164     @style{wxTL_CHECKBOX}
 165         Show the usual, 2 state, checkboxes for the items in the first column.
 166     @style{wxTL_3STATE}
 167         Show the checkboxes that can possibly be set by the program, but not
 168         the user, to a third, undetermined, state, for the items in the first
 169         column. Implies wxTL_CHECKBOX.
 170     @style{wxTL_USER_3STATE}
 171         Same as wxTL_3STATE but the user can also set the checkboxes to the
 172         undetermined state. Implies wxTL_3STATE.
 173     @style{wxTL_DEFAULT_STYLE}
 174         Style used by the control by default, just wxTL_SINGLE currently.
 175     @endStyleTable
 176
 177     @beginEventTable{wxTreeListEvent}
 178     @event{EVT_TREELIST_SELECTION_CHANGED(id, func)}
 179         Process @c wxEVT_COMMAND_TREELIST_SELECTION_CHANGED event and notifies
 180         about the selection change in the control. In the single selection case
 181         the item indicated by the event has been selected and previously
 182         selected item, if any, was deselected. In multiple selection case, the
 183         selection of this item has just changed (it may have been either
 184         selected or deselected) but notice that the selection of other items
 185         could have changed as well, use wxTreeListCtrl::GetSelections() to
 186         retrieve the new selection if necessary.
 187     @event{EVT_TREELIST_ITEM_EXPANDING(id, func)}
 188         Process @c wxEVT_COMMAND_TREELIST_ITEM_EXPANDING event notifying about
 189         the given branch being expanded. This event is sent before the
 190         expansion occurs and can be vetoed to prevent it from happening.
 191     @event{EVT_TREELIST_ITEM_EXPANDED(id, func)}
 192         Process @c wxEVT_COMMAND_TREELIST_ITEM_EXPANDED event notifying about
 193         the expansion of the given branch. This event is sent after the
 194         expansion occurs and can't be vetoed.
 195     @event{EVT_TREELIST_ITEM_CHECKED(id, func)}
 196         Process @c wxEVT_COMMAND_TREELIST_ITEM_CHeCKED event notifying about
 197         the user checking or unchecking the item. You can use
 198         wxTreeListCtrl::GetCheckedState() to retrieve the new item state and
 199         wxTreeListEvent::GetOldCheckedState() to get the previous one.
 200     @event{EVT_TREELIST_ITEM_ACTIVATED(id, func)}
 201         Process @c wxEVT_COMMAND_TREELIST_ITEM_ACTIVATED event notifying about
 202         the user double clicking the item or activating it from keyboard.
 203     @event{EVT_TREELIST_ITEM_CONTEXT_MENU(id, func)}
 204         Process @c wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU event indicating
 205         that the popup menu for the given item should be displayed.
 206     @event{EVT_TREELIST_COLUMN_SORTED(id, func)}
 207         Process @c wxEVT_COMMAND_TREELIST_COLUMN_SORTED event indicating that
 208         the control contents has just been resorted using the specified column.
 209         The event doesn't carry the sort direction, use GetSortColumn() method
 210         if you need to know it.
 211     @endEventTable
 212
 213     @library{wxadv}
 214     @category{ctrl}
 215
 216     @since 2.9.3
 217
 218     @see wxTreeCtrl, wxDataViewCtrl
 219  */
 220 class wxTreeListCtrl : public wxWindow
 221 {
 222 public:
 223     /**
 224         Default constructor, call Create() later.
 225
 226         This constructor is used during two-part construction process when it
 227         is impossible or undesirable to create the window when constructing the
 228         object.
 229      */
 230     wxTreeListCtrl();
 231
 232     /**
 233         Full constructing, creating the object and its window.
 234
 235         See Create() for the parameters description.
 236      */
 237     wxTreeListCtrl(wxWindow* parent,
 238                    wxWindowID id,
 239                    const wxPoint& pos = wxDefaultPosition,
 240                    const wxSize& size = wxDefaultSize,
 241                    long style = wxTL_DEFAULT_STYLE,
 242                    const wxString& name = wxTreeListCtrlNameStr);
 243
 244     /**
 245         Create the control window.
 246
 247         Can be only called for the objects created using the default
 248         constructor and exactly once.
 249
 250         @param parent
 251             The parent window, must be non-NULL.
 252         @param id
 253             The window identifier, may be ::wxID_ANY.
 254         @param pos
 255             The initial window position, usually unused.
 256         @param size
 257             The initial window size, usually unused.
 258         @param style
 259             The window style, see their description in the class documentation.
 260         @param name
 261             The name of the window.
 262      */
 263     bool Create(wxWindow* parent,
 264                 wxWindowID id,
 265                 const wxPoint& pos = wxDefaultPosition,
 266                 const wxSize& size = wxDefaultSize,
 267                 long style = wxTL_DEFAULT_STYLE,
 268                 const wxString& name = wxTreeListCtrlNameStr);
 269
 270
 271     /**
 272         Image list methods.
 273
 274         Like wxTreeCtrl and wxListCtrl this class uses wxImageList so if you
 275         intend to use item icons with it, you must construct wxImageList
 276         containing them first and then specify the indices of the icons in this
 277         image list when adding the items later.
 278      */
 279     //@{
 280
 281     /// A constant indicating that no image should be used for an item.
 282     static const int NO_IMAGE = -1;
 283
 284     /**
 285         Sets the image list and gives its ownership to the control.
 286
 287         The image list assigned with this method will be automatically deleted
 288         by wxTreeCtrl as appropriate (i.e. it takes ownership of the list).
 289
 290         @see SetImageList().
 291     */
 292     void AssignImageList(wxImageList* imageList);
 293
 294     /**
 295         Sets the image list.
 296
 297         The image list assigned with this method will @b not be deleted by the
 298         control itself and you will need to delete it yourself, use
 299         AssignImageList() to give the image list ownership to the control.
 300
 301         @param imageList
 302             Image list to use, may be @NULL to not show any images any more.
 303     */
 304     void SetImageList(wxImageList* imageList);
 305
 306     //@}
 307
 308
 309     /**
 310         Column methods.
 311      */
 312     //@{
 313
 314     /**
 315         Add a column with the given title and attributes.
 316
 317         @param title
 318             The column label.
 319         @param width
 320             The width of the column in pixels or the special
 321             wxCOL_WIDTH_AUTOSIZE value indicating that the column should adjust
 322             to its contents. Notice that the first column is special and will
 323             be always resized to fill all the space not taken by the other
 324             columns, i.e. the width specified here is ignored for it.
 325         @param align
 326             Alignment of both the column header and its items.
 327         @param flags
 328             Column flags, currently can include wxCOL_RESIZABLE to allow the
 329             user to resize the column and wxCOL_SORTABLE to allow the user to
 330             resort the control contents by clicking on this column.
 331         @return
 332             Index of the new column or -1 on failure.
 333      */
 334     int AppendColumn(const wxString& title,
 335                      int width = wxCOL_WIDTH_AUTOSIZE,
 336                      wxAlignment align = wxALIGN_LEFT,
 337                      int flags = wxCOL_RESIZABLE);
 338
 339     /// Return the total number of columns.
 340     unsigned GetColumnCount() const;
 341
 342     /**
 343         Delete the column with the given index.
 344
 345         @param col
 346             Column index in 0 to GetColumnCount() (exclusive) range.
 347         @return
 348             True if the column was deleted, false if index is invalid or
 349             deleting the column failed for some other reason.
 350      */
 351     bool DeleteColumn(unsigned col);
 352
 353     /**
 354         Delete all columns.
 355
 356         @see DeleteAllItems()
 357      */
 358     void ClearColumns();
 359
 360     /**
 361         Change the width of the given column.
 362
 363         Set column width to either the given value in pixels or to the value
 364         large enough to fit all of the items if width is wxCOL_WIDTH_AUTOSIZE.
 365
 366         Notice that setting the width of the first column is ignored as this
 367         column is always resized to fill the space left by the other columns.
 368      */
 369     void SetColumnWidth(unsigned col, int width);
 370
 371     /// Get the current width of the given column in pixels.
 372     int GetColumnWidth(unsigned col) const;
 373
 374     /**
 375         Get the width appropriate for showing the given text.
 376
 377         This is typically used as second argument for AppendColumn() or with
 378         SetColumnWidth().
 379      */
 380     int WidthFor(const wxString& text) const;
 381
 382     //@}
 383
 384
 385     /**
 386         Adding and removing items.
 387
 388         When adding items, the parent and text of the first column of the new item
 389         must always be specified, the rest is optional.
 390
 391         Each item can have two images: one used for closed state and another
 392         for opened one. Only the first one is ever used for the items that
 393         don't have children. And both are not set by default.
 394
 395         It is also possible to associate arbitrary client data pointer with the
 396         new item. It will be deleted by the control when the item is deleted
 397         (either by an explicit DeleteItem() call or because the entire control
 398         is destroyed).
 399      */
 400     //@{
 401
 402     /// Same as InsertItem() with wxTLI_LAST.
 403     wxTreeListItem AppendItem(wxTreeListItem parent,
 404                               const wxString& text,
 405                               int imageClosed = NO_IMAGE,
 406                               int imageOpened = NO_IMAGE,
 407                               wxClientData* data = NULL);
 408
 409     /**
 410         Insert a new item into the tree.
 411
 412         @param parent
 413             The item parent. Must be valid, may be GetRootItem().
 414         @param previous
 415             The previous item that this one should be inserted immediately
 416             after. It must be valid but may be one of the special values
 417             wxTLI_FIRST or wxTLI_LAST indicating that the item should be either
 418             inserted before the first child of its parent (if any) or after the
 419             last one.
 420         @param imageClosed
 421             The normal item image, may be NO_IMAGE to not show any image.
 422         @param imageOpened
 423             The item image shown when it's in the expanded state.
 424         @param data
 425             Optional client data pointer that can be later retrieved using
 426             GetItemData() and will be deleted by the tree when the item itself
 427             is deleted.
 428      */
 429     wxTreeListItem InsertItem(wxTreeListItem parent,
 430                               wxTreeListItem previous,
 431                               const wxString& text,
 432                               int imageClosed = NO_IMAGE,
 433                               int imageOpened = NO_IMAGE,
 434                               wxClientData* data = NULL);
 435
 436     /// Same as InsertItem() with wxTLI_FIRST.
 437     wxTreeListItem PrependItem(wxTreeListItem parent,
 438                                const wxString& text,
 439                                int imageClosed = NO_IMAGE,
 440                                int imageOpened = NO_IMAGE,
 441                                wxClientData* data = NULL);
 442
 443     /// Delete the specified item.
 444     void DeleteItem(wxTreeListItem item);
 445
 446     /// Delete all tree items.
 447     void DeleteAllItems();
 448
 449     //@}
 450
 451
 452     /**
 453         Methods for the tree navigation.
 454
 455         The tree has an invisible root item which is the hidden parent of all
 456         top-level items in the tree. Starting from it it is possible to iterate
 457         over all tree items using GetNextItem().
 458
 459         It is also possible to iterate over just the children of the given item
 460         by using GetFirstChild() to get the first of them and then calling
 461         GetNextSibling() to retrieve all the others.
 462      */
 463     //@{
 464
 465     /// Return the (never shown) root item.
 466     wxTreeListItem GetRootItem() const;
 467
 468     /**
 469         Return the parent of the given item.
 470
 471         All the tree items visible in the tree have valid parent items, only
 472         the never shown root item has no parent.
 473      */
 474     wxTreeListItem GetItemParent(wxTreeListItem item) const;
 475
 476     /**
 477         Return the first child of the given item.
 478
 479         Item may be the root item.
 480
 481         Return value may be invalid if the item doesn't have any children.
 482      */
 483     wxTreeListItem GetFirstChild(wxTreeListItem item) const;
 484
 485     /**
 486         Return the next sibling of the given item.
 487
 488         Return value may be invalid if there are no more siblings.
 489      */
 490     wxTreeListItem GetNextSibling(wxTreeListItem item) const;
 491
 492     /**
 493         Return the first item in the tree.
 494
 495         This is the first child of the root item.
 496
 497         @see GetNextItem()
 498      */
 499     wxTreeListItem GetFirstItem() const;
 500
 501     /**
 502         Get item after the given one in the depth-first tree-traversal order.
 503
 504         Calling this function starting with the result of GetFirstItem() allows
 505         iterating over all items in the tree.
 506
 507         The iteration stops when this function returns an invalid item, i.e.
 508         @code
 509             for ( wxTreeListItem item = tree->GetFirstItem();
 510                   item.IsOk();
 511                   item = tree->GetNextItem(item) )
 512             {
 513                 ... Do something with every tree item ...
 514             }
 515         @endcode
 516      */
 517     wxTreeListItem GetNextItem(wxTreeListItem item) const;
 518
 519     //@}
 520
 521
 522     /**
 523         Items attributes
 524      */
 525     //@{
 526
 527     /**
 528         Return the text of the given item.
 529
 530         By default, returns the text of the first column but any other one can
 531         be specified using @a col argument.
 532      */
 533     const wxString& GetItemText(wxTreeListItem item, unsigned col = 0) const;
 534
 535     /**
 536         Set the text of the specified column of the given item.
 537      */
 538     void SetItemText(wxTreeListItem item, unsigned col, const wxString& text);
 539
 540     /**
 541         Set the text of the first column of the given item.
 542      */
 543     void SetItemText(wxTreeListItem item, const wxString& text);
 544
 545     /**
 546         Set the images for the given item.
 547
 548         See InsertItem() for the images parameters descriptions.
 549      */
 550     void SetItemImage(wxTreeListItem item, int closed, int opened = NO_IMAGE);
 551
 552     /**
 553         Get the data associated with the given item.
 554
 555         The returned pointer may be @NULL.
 556
 557         It must not be deleted by the caller as this will be done by the
 558         control itself.
 559      */
 560     wxClientData* GetItemData(wxTreeListItem item) const;
 561
 562     /**
 563         Set the data associated with the given item.
 564
 565         Previous client data, if any, is deleted when this function is called
 566         so it may be used to delete the current item data object and reset it
 567         by passing @NULL as @a data argument.
 568      */
 569     void SetItemData(wxTreeListItem item, wxClientData* data);
 570
 571     //@}
 572
 573
 574     /**
 575         Expanding and collapsing tree branches.
 576
 577         Notice that calling neither Expand() nor Collapse() method generates
 578         any events.
 579      */
 580     //@{
 581
 582     /**
 583         Expand the given tree branch.
 584      */
 585     void Expand(wxTreeListItem item);
 586
 587     /**
 588         Collapse the given tree branch.
 589      */
 590     void Collapse(wxTreeListItem item);
 591
 592     /**
 593         Return whether the given item is expanded.
 594      */
 595     bool IsExpanded(wxTreeListItem item) const;
 596
 597     //@}
 598
 599
 600     /**
 601         Selection methods.
 602
 603         The behaviour of the control is different in single selection mode (the
 604         default) and multi-selection mode (if @c wxTL_MULTIPLE was specified
 605         when creating it). Not all methods can be used in both modes and some
 606         of those that can don't behave in the same way in two cases.
 607      */
 608     //@{
 609
 610     /**
 611         Return the currently selected item.
 612
 613         This method can't be used with multi-selection controls, use
 614         GetSelections() instead.
 615
 616         The return value may be invalid if no item has been selected yet. Once
 617         an item in a single selection control was selected, it will keep a
 618         valid selection.
 619      */
 620     wxTreeListItem GetSelection() const;
 621
 622     /**
 623         Fill in the provided array with all the selected items.
 624
 625         This method can be used in both single and multi-selection case.
 626
 627         The previous array contents is destroyed.
 628
 629         Returns the number of selected items.
 630      */
 631     unsigned GetSelections(wxTreeListItems& selections) const;
 632
 633     /**
 634         Select the given item.
 635
 636         In single selection mode, deselects any other selected items, in
 637         multi-selection case it adds to the selection.
 638      */
 639     void Select(wxTreeListItem item);
 640
 641     /**
 642         Deselect the given item.
 643
 644         This method can be used in multiple selection mode only.
 645      */
 646     void Unselect(wxTreeListItem item);
 647
 648     /**
 649         Return true if the item is selected.
 650
 651         This method can be used in both single and multiple selection modes.
 652      */
 653     bool IsSelected(wxTreeListItem item) const;
 654
 655     /**
 656         Select all the control items.
 657
 658         Can be only used in multi-selection mode.
 659      */
 660     void SelectAll();
 661
 662     /**
 663         Deselect all the control items.
 664
 665         Can be only used in multi-selection mode.
 666      */
 667     void UnselectAll();
 668
 669     //@}
 670
 671
 672     /**
 673         Checkbox handling
 674
 675         Methods in this section can only be used with the controls created with
 676         wxTL_CHECKBOX style.
 677      */
 678     //@{
 679
 680     /**
 681         Change the item checked state.
 682
 683         @param item
 684             Valid non-root tree item.
 685         @param state
 686             One of wxCHK_CHECKED, wxCHK_UNCHECKED or, for the controls with
 687             wxTL_3STATE or wxTL_USER_3STATE styles, wxCHK_UNDETERMINED.
 688      */
 689     void CheckItem(wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED);
 690
 691     /**
 692         Change the checked state of the given item and all its children.
 693
 694         This is the same as CheckItem() but checks or unchecks not only this
 695         item itself but all its children recursively as well.
 696      */
 697     void CheckItemRecursively(wxTreeListItem item,
 698                               wxCheckBoxState state = wxCHK_CHECKED);
 699
 700     /**
 701         Uncheck the given item.
 702
 703         This is synonymous with CheckItem(wxCHK_UNCHECKED).
 704      */
 705     void UncheckItem(wxTreeListItem item);
 706
 707     /**
 708         Update the state of the parent item to reflect the checked state of its
 709         children.
 710
 711         This method updates the parent of this item recursively: if this item
 712         and all its siblings are checked, the parent will become checked as
 713         well. If this item and all its siblings are unchecked, the parent will
 714         be unchecked. And if the siblings of this item are not all in the same
 715         state, the parent will be switched to indeterminate state. And then the
 716         same logic will be applied to the parents parent and so on recursively.
 717
 718         This is typically called when the state of the given item has changed
 719         from EVT_TREELIST_ITEM_CHECKED() handler in the controls which have
 720         wxTL_3STATE flag. Notice that without this flag this function can't
 721         work as it would be unable to set the state of a parent with both
 722         checked and unchecked items so it's only allowed to call it when this
 723         flag is set.
 724      */
 725     void UpdateItemParentStateRecursively(wxTreeListItem item);
 726
 727     /**
 728         Return the checked state of the item.
 729
 730         The return value can be wxCHK_CHECKED, wxCHK_UNCHECKED or
 731         wxCHK_UNDETERMINED.
 732      */
 733     wxCheckBoxState GetCheckedState(wxTreeListItem item) const;
 734
 735     /**
 736         Return true if all children of the given item are in the specified
 737         state.
 738
 739         This is especially useful for the controls with @c wxTL_3STATE style to
 740         allow to decide whether the parent effective state should be the same
 741         @a state, if all its children are in it, or ::wxCHK_UNDETERMINED.
 742
 743         @see UpdateItemParentStateRecursively()
 744      */
 745     bool AreAllChildrenInState(wxTreeListItem item,
 746                                wxCheckBoxState state) const;
 747
 748     //@}
 749
 750     /**
 751         Sorting.
 752
 753         If some control columns were added with wxCOL_SORTABLE flag, clicking
 754         on them will automatically resort the control using the custom
 755         comparator set by SetItemComparator() or by doing alphabetical
 756         comparison by default.
 757
 758         In any case, i.e. even if the user can't sort the control by clicking
 759         on its header, you may call SetSortColumn() to sort it programmatically
 760         and call GetSortColumn() to determine whether it's sorted now and, if
 761         so, by which column and in which order.
 762      */
 763     //@{
 764
 765     /**
 766         Set the column to use for sorting and the order in which to sort.
 767
 768         Calling this method resorts the control contents using the values of
 769         the items in the specified column. Sorting uses custom comparator set
 770         with SetItemComparator() or alphabetical comparison of items texts if
 771         none was specified.
 772
 773         Notice that currently there is no way to reset sort order.
 774
 775         @param col
 776             A valid column index.
 777         @param ascendingOrder
 778             Indicates whether the items should be sorted in ascending (A to Z)
 779             or descending (Z to A) order.
 780      */
 781     void SetSortColumn(unsigned col, bool ascendingOrder = true);
 782
 783     /**
 784         Return the column currently used for sorting, if any.
 785
 786         If the control is currently unsorted, the function simply returns
 787         @false and doesn't modify any of its output parameters.
 788
 789         @param col
 790             Receives the index of the column used for sorting if non-@NULL.
 791         @param ascendingOrder
 792             Receives @true or @false depending on whether the items are sorted
 793             in ascending or descending order.
 794         @return
 795             @true if the control is sorted or @false if it isn't sorted at all.
 796      */
 797     bool GetSortColumn(unsigned* col, bool* ascendingOrder = NULL);
 798
 799     /**
 800         Set the object to use for comparing the items.
 801
 802         This object will be used when the control is being sorted because the
 803         user clicked on a sortable column or SetSortColumn() was called.
 804
 805         The provided pointer is stored by the control so the object it points
 806         to must have a life-time equal or greater to that of the control
 807         itself. In addition, the pointer can be @NULL to stop using custom
 808         comparator and revert to the default alphabetical comparison.
 809      */
 810     void SetItemComparator(wxTreeListItemComparator* comparator);
 811
 812     //@}
 813
 814
 815     /**
 816         View window.
 817
 818         This control itself is entirely covered by the "view window" which is
 819         currently a wxDataViewCtrl but if you want to avoid relying on this to
 820         allow your code to work with later versions which might not be
 821         wxDataViewCtrl-based, use GetView() function only and only use
 822         GetDataView() if you really need to call wxDataViewCtrl methods on it.
 823      */
 824     //@{
 825
 826     /**
 827         Return the view part of this control as a wxWindow.
 828
 829         This method always returns non-@NULL pointer once the window was
 830         created.
 831      */
 832     wxWindow* GetView() const;
 833
 834     /**
 835         Return the view part of this control as wxDataViewCtrl.
 836
 837         This method may return @NULL in the future, non wxDataViewCtrl-based,
 838         versions of this class, use GetView() unless you really need to use
 839         wxDataViewCtrl methods on the returned object.
 840      */
 841     wxDataViewCtrl* GetDataView() const;
 842
 843     //@}
 844 };
 845
 846 /**
 847     Event generated by wxTreeListCtrl.
 848
 849     @since 2.9.3
 850  */
 851 class wxTreeListEvent : public wxNotifyEvent
 852 {
 853 public:
 854     /**
 855         Return the item affected by the event.
 856
 857         This is the item being selected, expanded, checked or activated
 858         (depending on the event type).
 859      */
 860     wxTreeListItem GetItem() const;
 861
 862     /**
 863         Return the previous state of the item checkbox.
 864
 865         This method can be used with @c wxEVT_COMMAND_TREELIST_ITEM_CHeCKED
 866         events only.
 867
 868         Notice that the new state of the item can be retrieved using
 869         wxTreeListCtrl::GetCheckedState().
 870      */
 871     wxCheckBoxState GetOldCheckedState() const;
 872
 873     /**
 874         Return the column affected by the event.
 875
 876         This is currently only used with @c wxEVT_COMMAND_TREELIST_COLUMN_SORTED
 877         event.
 878      */
 879     unsigned GetColumn() const;
 880 };
 881
 882
 883 /**
 884     Type of wxTreeListEvent event handlers.
 885
 886     This macro should be used with wxEvtHandler::Connect() when connecting to
 887     wxTreeListCtrl events.
 888  */
 889 #define wxTreeListEventHandler(func) \
 890     wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
 891
 892 #endif // _WX_TREELIST_H_