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