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