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