interface/treectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treectrl.h
   3 // Purpose:     interface of wxTreeItemData
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxTreeCtrl
  12     @wxheader{treectrl.h}
  13
  14     A tree control presents information as a hierarchy, with items that may be
  15     expanded to show further items. Items in a tree control are referenced by
  16     wxTreeItemId handles, which may be tested for validity by calling
  17     wxTreeItemId::IsOk().
  18
  19     A similar control with a fully native implemtation for GTK+ and OS X
  20     as well is wxDataViewTreeCtrl.
  21
  22     To intercept events from a tree control, use the event table macros
  23     described in wxTreeEvent.
  24
  25     @beginStyleTable
  26     @style{wxTR_EDIT_LABELS}
  27         Use this style if you wish the user to be able to edit labels in the
  28         tree control.
  29     @style{wxTR_NO_BUTTONS}
  30         For convenience to document that no buttons are to be drawn.
  31     @style{wxTR_HAS_BUTTONS}
  32         Use this style to show + and - buttons to the left of parent items.
  33     @style{wxTR_NO_LINES}
  34         Use this style to hide vertical level connectors.
  35     @style{wxTR_FULL_ROW_HIGHLIGHT}
  36         Use this style to have the background colour and the selection highlight
  37         extend over the entire horizontal row of the tree control window. (This
  38         flag is ignored under Windows unless you specify @c wxTR_NO_LINES as
  39         well.)
  40     @style{wxTR_LINES_AT_ROOT}
  41         Use this style to show lines between root nodes. Only applicable if @c
  42         wxTR_HIDE_ROOT is set and @c wxTR_NO_LINES is not set.
  43     @style{wxTR_HIDE_ROOT}
  44         Use this style to suppress the display of the root node, effectively
  45         causing the first-level nodes to appear as a series of root nodes.
  46     @style{wxTR_ROW_LINES}
  47         Use this style to draw a contrasting border between displayed rows.
  48     @style{wxTR_HAS_VARIABLE_ROW_HEIGHT}
  49         Use this style to cause row heights to be just big enough to fit the
  50         content. If not set, all rows use the largest row height. The default is
  51         that this flag is unset. Generic only.
  52     @style{wxTR_SINGLE}
  53         For convenience to document that only one item may be selected at a
  54         time. Selecting another item causes the current selection, if any, to be
  55         deselected. This is the default.
  56     @style{wxTR_MULTIPLE}
  57         Use this style to allow a range of items to be selected. If a second
  58         range is selected, the current range, if any, is deselected.
  59     @style{wxTR_DEFAULT_STYLE}
  60         The set of flags that are closest to the defaults for the native control
  61         for a particular toolkit.
  62     @endStyleTable
  63
  64     See also @ref overview_windowstyles.
  65
  66     @b Win32 @b notes:
  67
  68     wxTreeCtrl class uses the standard common treeview control under Win32
  69     implemented in the system library comctl32.dll. Some versions of this
  70     library are known to have bugs with handling the tree control colours: the
  71     usual symptom is that the expanded items leave black (or otherwise
  72     incorrectly coloured) background behind them, especially for the controls
  73     using non-default background colour. The recommended solution is to upgrade
  74     the comctl32.dll to a newer version: see
  75     http://www.microsoft.com/downloads/details.aspx?familyid=cb2cf3a2-8025-4e8f-8511-9b476a8d35d2
  76
  77     @library{wxcore}
  78     @category{ctrl}
  79     <!-- @appearance{treectrl.png} -->
  80
  81     @see wxDataViewTreeCtrl, wxTreeEvent, wxTreeItemData, @ref overview_treectrl, wxListBox,
  82          wxListCtrl, wxImageList
  83 */
  84 class wxTreeCtrl : public wxControl
  85 {
  86 public:
  87     /**
  88         Default Constructor.
  89     */
  90     wxTreeCtrl();
  91
  92     /**
  93         Constructor, creating and showing a tree control.
  94
  95         @param parent
  96             Parent window. Must not be @NULL.
  97         @param id
  98             Window identifier. The value @c wxID_ANY indicates a default value.
  99         @param pos
 100             Window position.
 101         @param size
 102             Window size. If wxDefaultSize is specified then the window is sized
 103             appropriately.
 104         @param style
 105             Window style. See wxTreeCtrl.
 106         @param validator
 107             Window validator.
 108         @param name
 109             Window name.
 110
 111         @see Create(), wxValidator
 112     */
 113     wxTreeCtrl(wxWindow* parent, wxWindowID id,
 114                const wxPoint& pos = wxDefaultPosition,
 115                const wxSize& size = wxDefaultSize,
 116                long style = wxTR_HAS_BUTTONS,
 117                const wxValidator& validator = wxDefaultValidator,
 118                const wxString& name = "treeCtrl");
 119
 120
 121     /**
 122         Destructor, destroying the tree control.
 123     */
 124     ~wxTreeCtrl();
 125
 126     /**
 127         Adds the root node to the tree, returning the new item.
 128
 129         The @a image and @a selImage parameters are an index within the normal
 130         image list specifying the image to use for unselected and selected
 131         items, respectively. If @a image -1 and @a selImage is -1, the same
 132         image is used for both selected and unselected items.
 133     */
 134     wxTreeItemId AddRoot(const wxString& text, int image = -1,
 135                          int selImage = -1,
 136                          wxTreeItemData* data = NULL);
 137
 138     /**
 139         Appends an item to the end of the branch identified by @a parent, return
 140         a new item id.
 141
 142         The @a image and @a selImage parameters are an index within the normal
 143         image list specifying the image to use for unselected and selected
 144         items, respectively. If @a image -1 and @a selImage is -1, the same
 145         image is used for both selected and unselected items.
 146     */
 147     wxTreeItemId AppendItem(const wxTreeItemId& parent,
 148                             const wxString& text,
 149                             int image = -1,
 150                             int selImage = -1,
 151                             wxTreeItemData* data = NULL);
 152
 153     /**
 154         Sets the buttons image list. The button images assigned with this method
 155         will be automatically deleted by wxTreeCtrl as appropriate (i.e. it
 156         takes ownership of the list).
 157
 158         Setting or assigning the button image list enables the display of image
 159         buttons. Once enabled, the only way to disable the display of button
 160         images is to set the button image list to @NULL.
 161
 162         This function is only available in the generic version.
 163
 164         @see SetButtonsImageList().
 165     */
 166     void AssignButtonsImageList(wxImageList* imageList);
 167
 168     /**
 169         Sets the normal image list. The image list assigned with this method
 170         will be automatically deleted by wxTreeCtrl as appropriate (i.e. it
 171         takes ownership of the list).
 172
 173         @see SetImageList().
 174     */
 175     void AssignImageList(wxImageList* imageList);
 176
 177     /**
 178         Sets the state image list. Image list assigned with this method will be
 179         automatically deleted by wxTreeCtrl as appropriate (i.e. it takes
 180         ownership of the list).
 181
 182         @see SetStateImageList().
 183     */
 184     void AssignStateImageList(wxImageList* imageList);
 185
 186     /**
 187         Collapses the given item.
 188     */
 189     void Collapse(const wxTreeItemId& item);
 190
 191     /**
 192         Collapses the root item.
 193
 194         @see ExpandAll()
 195     */
 196     void CollapseAll();
 197
 198     /**
 199         Collapses this item and all of its children, recursively.
 200
 201         @see ExpandAllChildren()
 202     */
 203     void CollapseAllChildren(const wxTreeItemId& item);
 204
 205     /**
 206         Collapses the given item and removes all children.
 207     */
 208     void CollapseAndReset(const wxTreeItemId& item);
 209
 210     /**
 211         Creates the tree control. See wxTreeCtrl::wxTreeCtrl() for further
 212         details.
 213     */
 214     bool Create(wxWindow* parent, wxWindowID id,
 215                 const wxPoint& pos = wxDefaultPosition,
 216                 const wxSize& size = wxDefaultSize,
 217                 long style = wxTR_HAS_BUTTONS,
 218                 const wxValidator& validator = wxDefaultValidator,
 219                 const wxString& name = "treeCtrl");
 220
 221     /**
 222         Deletes the specified item. A EVT_TREE_DELETE_ITEM() event will be
 223         generated.
 224
 225         This function may cause a subsequent call to GetNextChild() to fail.
 226     */
 227     void Delete(const wxTreeItemId& item);
 228
 229     /**
 230         Deletes all items in the control. Note that this may not generate
 231         EVT_TREE_DELETE_ITEM() events under some Windows versions although
 232         normally such event is generated for each removed item.
 233     */
 234     void DeleteAllItems();
 235
 236     /**
 237         Deletes all children of the given item (but not the item itself). Note
 238         that this will @b not generate any events unlike Delete() method.
 239
 240         If you have called SetItemHasChildren(), you may need to call it again
 241         since DeleteChildren() does not automatically clear the setting.
 242     */
 243     void DeleteChildren(const wxTreeItemId& item);
 244
 245     /**
 246         Starts editing the label of the given @a item. This function generates a
 247         EVT_TREE_BEGIN_LABEL_EDIT() event which can be vetoed so that no text
 248         control will appear for in-place editing.
 249
 250         If the user changed the label (i.e. s/he does not press ESC or leave the
 251         text control without changes, a EVT_TREE_END_LABEL_EDIT() event will be
 252         sent which can be vetoed as well.
 253
 254         @see EndEditLabel(), wxTreeEvent
 255     */
 256     void EditLabel(const wxTreeItemId& item);
 257
 258     /**
 259         Ends label editing. If @a cancelEdit is @true, the edit will be
 260         cancelled.
 261
 262         @note
 263             This function is currently supported under Windows only.
 264
 265         @see EditLabel()
 266     */
 267     void EndEditLabel(bool cancelEdit);
 268
 269     /**
 270         Scrolls and/or expands items to ensure that the given item is visible.
 271     */
 272     void EnsureVisible(const wxTreeItemId& item);
 273
 274     /**
 275         Expands the given item.
 276     */
 277     void Expand(const wxTreeItemId& item);
 278
 279     /**
 280         Expands all items in the tree.
 281     */
 282     void ExpandAll();
 283
 284     /**
 285         Expands the given item and all its children recursively.
 286     */
 287     void ExpandAllChildren(const wxTreeItemId& item);
 288
 289     /**
 290         Retrieves the rectangle bounding the @a item. If @a textOnly is @true,
 291         only the rectangle around the item's label will be returned, otherwise
 292         the item's image is also taken into account.
 293
 294         The return value is @true if the rectangle was successfully retrieved or
 295         @c @false if it was not (in this case @a rect is not changed) -- for
 296         example, if the item is currently invisible.
 297
 298         Notice that the rectangle coordinates are logical, not physical ones.
 299         So, for example, the x coordinate may be negative if the tree has a
 300         horizontal scrollbar and its position is not 0.
 301
 302         @beginWxPythonOnly
 303         The wxPython version of this method requires only the @a item and @a
 304         textOnly parameters. The return value is either a wxRect object or @c
 305         None.
 306         @endWxPythonOnly
 307     */
 308     bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect,
 309                          bool textOnly = false) const;
 310
 311     /**
 312         Returns the buttons image list (from which application-defined button
 313         images are taken).
 314
 315         This function is only available in the generic version.
 316     */
 317     wxImageList* GetButtonsImageList() const;
 318
 319     /**
 320         Returns the number of items in the branch. If @a recursively is @true,
 321         returns the total number of descendants, otherwise only one level of
 322         children is counted.
 323     */
 324     unsigned int GetChildrenCount(const wxTreeItemId& item,
 325                                   bool recursively = true) const;
 326
 327     /**
 328         Returns the number of items in the control.
 329     */
 330     unsigned int GetCount() const;
 331
 332     /**
 333         Returns the edit control being currently used to edit a label. Returns
 334         @NULL if no label is being edited.
 335
 336         @note This is currently only implemented for wxMSW.
 337     */
 338     wxTextCtrl* GetEditControl() const;
 339
 340     /**
 341         Returns the first child; call GetNextChild() for the next child.
 342
 343         For this enumeration function you must pass in a 'cookie' parameter
 344         which is opaque for the application but is necessary for the library to
 345         make these functions reentrant (i.e. allow more than one enumeration on
 346         one and the same object simultaneously). The cookie passed to
 347         GetFirstChild() and GetNextChild() should be the same variable.
 348
 349         Returns an invalid tree item (i.e. wxTreeItemId::IsOk() returns @false)
 350         if there are no further children.
 351
 352         @beginWxPythonOnly
 353         In wxPython the returned wxTreeItemId and the new cookie value are both
 354         returned as a tuple containing the two values.
 355         @endWxPythonOnly
 356
 357         @see GetNextChild(), GetNextSibling()
 358     */
 359     wxTreeItemId GetFirstChild(const wxTreeItemId& item,
 360                                wxTreeItemIdValue& cookie) const;
 361
 362     /**
 363         Returns the first visible item.
 364     */
 365     wxTreeItemId GetFirstVisibleItem() const;
 366
 367     /**
 368         Returns the normal image list.
 369     */
 370     wxImageList* GetImageList() const;
 371
 372     /**
 373         Returns the current tree control indentation.
 374     */
 375     int GetIndent() const;
 376
 377     /**
 378         Returns the background colour of the item.
 379     */
 380     wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
 381
 382     /**
 383         Returns the tree item data associated with the item.
 384
 385         @see wxTreeItemData
 386
 387         @beginWxPythonOnly
 388         wxPython provides the following shortcut method:
 389         @li GetPyData(item): Returns the Python Object associated with the
 390             wxTreeItemData for the given item Id.
 391         @endWxPythonOnly
 392     */
 393     wxTreeItemData* GetItemData(const wxTreeItemId& item) const;
 394
 395     /**
 396         Returns the font of the item label.
 397     */
 398     wxFont GetItemFont(const wxTreeItemId& item) const;
 399
 400     /**
 401         Gets the specified item image. The value of @a which may be:
 402         - ::wxTreeItemIcon_Normal: to get the normal item image.
 403         - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the
 404             image which is shown when the item is currently selected).
 405         - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes
 406             sense for items which have children - then this image is shown when
 407             the item is expanded and the normal image is shown when it is
 408             collapsed).
 409         - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image
 410             (which is shown when an expanded item is currently selected).
 411     */
 412     int GetItemImage(const wxTreeItemId& item,
 413                      wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 414
 415     /**
 416         Returns the item's parent.
 417     */
 418     wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
 419
 420     /**
 421         Gets the selected item image (this function is obsolete, use @ref
 422         GetItemImage() "GetItemImage"( @a item, ::wxTreeItemIcon_Selected)
 423         instead).
 424     */
 425     int GetItemSelectedImage(const wxTreeItemId& item) const;
 426
 427     /**
 428         Gets the specified item state.
 429     */
 430     int GetItemState(const wxTreeItemId& item) const;
 431
 432     /**
 433         Returns the item label.
 434     */
 435     wxString GetItemText(const wxTreeItemId& item) const;
 436
 437     /**
 438         Returns the colour of the item label.
 439     */
 440     wxColour GetItemTextColour(const wxTreeItemId& item) const;
 441
 442     /**
 443         Returns the last child of the item (or an invalid tree item if this item
 444         has no children).
 445
 446         @see GetFirstChild(), GetNextSibling(), GetLastChild()
 447     */
 448     wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 449
 450     /**
 451         Returns the next child; call GetFirstChild() for the first child. For
 452         this enumeration function you must pass in a 'cookie' parameter which is
 453         opaque for the application but is necessary for the library to make
 454         these functions reentrant (i.e. allow more than one enumeration on one
 455         and the same object simultaneously). The cookie passed to
 456         GetFirstChild() and GetNextChild() should be the same.
 457
 458         Returns an invalid tree item if there are no further children.
 459
 460         @beginWxPythonOnly
 461         In wxPython the returned wxTreeItemId and the new cookie value are both
 462         returned as a tuple containing the two values.
 463         @endWxPythonOnly
 464
 465         @see GetFirstChild()
 466     */
 467     wxTreeItemId GetNextChild(const wxTreeItemId& item,
 468                               wxTreeItemIdValue& cookie) const;
 469
 470     /**
 471         Returns the next sibling of the specified item; call GetPrevSibling()
 472         for the previous sibling.
 473
 474         Returns an invalid tree item if there are no further siblings.
 475
 476         @see GetPrevSibling()
 477     */
 478     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 479
 480     /**
 481         Returns the next visible item or an invalid item if this item is the
 482         last visible one.
 483
 484         @note The @a item itself must be visible.
 485     */
 486     wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 487
 488     /**
 489         Returns the previous sibling of the specified item; call
 490         GetNextSibling() for the next sibling.
 491
 492         Returns an invalid tree item if there are no further children.
 493
 494         @see GetNextSibling()
 495     */
 496     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 497
 498     /**
 499         Returns the previous visible item or an invalid item if this item is the
 500         first visible one.
 501
 502         @note The @a item itself must be visible.
 503     */
 504     wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 505
 506     /**
 507         Returns @true if the control will use a quick calculation for the best
 508         size, looking only at the first and last items. The default is @false.
 509
 510         @see SetQuickBestSize()
 511     */
 512     bool GetQuickBestSize() const;
 513
 514     /**
 515         Returns the root item for the tree control.
 516     */
 517     wxTreeItemId GetRootItem() const;
 518
 519     /**
 520         Returns the selection, or an invalid item if there is no selection. This
 521         function only works with the controls without @c wxTR_MULTIPLE style,
 522         use GetSelections() for the controls which do have this style.
 523     */
 524     wxTreeItemId GetSelection() const;
 525
 526     /**
 527         Fills the array of tree items passed in with the currently selected
 528         items. This function can be called only if the control has the @c
 529         wxTR_MULTIPLE style.
 530
 531         Returns the number of selected items.
 532
 533         @beginWxPythonOnly
 534         The wxPython version of this method accepts no parameters and returns a
 535         Python list of @ref wxTreeItemId "wxTreeItemId"s.
 536         @endWxPythonOnly
 537     */
 538     unsigned int GetSelections(wxArrayTreeItemIds& selection) const;
 539
 540     /**
 541         Returns the state image list (from which application-defined state
 542         images are taken).
 543     */
 544     wxImageList* GetStateImageList() const;
 545
 546     /**
 547         Calculates which (if any) item is under the given @a point, returning
 548         the tree item id at this point plus extra information @a flags. @a flags
 549         is a bitlist of the following:
 550
 551         - @c wxTREE_HITTEST_ABOVE: Above the client area.
 552         - @c wxTREE_HITTEST_BELOW: Below the client area.
 553         - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item.
 554         - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item.
 555         - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item.
 556         - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an
 557             item.
 558         - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with
 559             an item.
 560         - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item.
 561         - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view
 562             item that is in a user-defined state.
 563         - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
 564         - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
 565
 566         @beginWxPythonOnly
 567         In wxPython both the wxTreeItemId and the flags are returned as a tuple.
 568         @endWxPythonOnly
 569     */
 570     wxTreeItemId HitTest(const wxPoint& point, int& flags) const;
 571
 572
 573     /**
 574         Inserts an item after a given one (@a previous).
 575
 576         The @a image and @a selImage parameters are an index within the normal
 577         image list specifying the image to use for unselected and selected
 578         items, respectively. If @a image -1 and @a selImage is -1, the same
 579         image is used for both selected and unselected items.
 580     */
 581     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 582                             const wxTreeItemId& previous,
 583                             const wxString& text,
 584                             int image = -1,
 585                             int selImage = -1,
 586                             wxTreeItemData* data = NULL);
 587
 588     /**
 589         Inserts an item before one identified
 590         by its position (@a before). @a before must be less than the number of
 591         children.
 592
 593         The @a image and @a selImage parameters are an index within the normal
 594         image list specifying the image to use for unselected and selected
 595         items, respectively. If @a image -1 and @a selImage is -1, the same
 596         image is used for both selected and unselected items.
 597
 598         @beginWxPythonOnly
 599         In wxPython, this form of this method is called @c InsertItemBefore().
 600         @endWxPythonOnly
 601     */
 602     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 603                             size_t before,
 604                             const wxString& text,
 605                             int image = -1,
 606                             int selImage = -1,
 607                             wxTreeItemData* data = NULL);
 608
 609     /**
 610         Returns @true if the given item is in bold state.
 611
 612         @see SetItemBold()
 613     */
 614     bool IsBold(const wxTreeItemId& item) const;
 615
 616     /**
 617         Returns @true if the control is empty (i.e. has no items, even no root
 618         one).
 619     */
 620     bool IsEmpty() const;
 621
 622     /**
 623         Returns @true if the item is expanded (only makes sense if it has
 624         children).
 625     */
 626     bool IsExpanded(const wxTreeItemId& item) const;
 627
 628     /**
 629         Returns @true if the item is selected.
 630     */
 631     bool IsSelected(const wxTreeItemId& item) const;
 632
 633     /**
 634         Returns @true if the item is visible on the screen.
 635     */
 636     bool IsVisible(const wxTreeItemId& item) const;
 637
 638     /**
 639         Returns @true if the item has children.
 640     */
 641     bool ItemHasChildren(const wxTreeItemId& item) const;
 642
 643     /**
 644         Override this function in the derived class to change the sort order of
 645         the items in the tree control. The function should return a negative,
 646         zero or positive value if the first item is less than, equal to or
 647         greater than the second one.
 648
 649         Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS()
 650         and IMPLEMENT_DYNAMIC_CLASS() if you override this function because
 651         otherwise the base class considers that it is not overridden and uses
 652         the default comparison, i.e. sorts the items alphabetically, which
 653         allows it optimize away the calls to the virtual function completely.
 654
 655         @see SortChildren()
 656     */
 657     int OnCompareItems(const wxTreeItemId& item1,
 658                        const wxTreeItemId& item2);
 659
 660     /**
 661         Appends an item as the first child of @a parent, return a new item id.
 662
 663         The @a image and @a selImage parameters are an index within the normal
 664         image list specifying the image to use for unselected and selected
 665         items, respectively. If @a image -1 and @a selImage is -1, the same
 666         image is used for both selected and unselected items.
 667     */
 668     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 669                              const wxString& text,
 670                              int image = -1,
 671                              int selImage = -1,
 672                              wxTreeItemData* data = NULL);
 673
 674     /**
 675         Scrolls the specified item into view.
 676     */
 677     void ScrollTo(const wxTreeItemId& item);
 678
 679     /**
 680         Selects the given item. In multiple selection controls, can be also used
 681         to deselect a currently selected item if the value of @a select is
 682         @false.
 683     */
 684     void SelectItem(const wxTreeItemId& item, bool select = true);
 685
 686     /**
 687         Sets the buttons image list (from which application-defined button
 688         images are taken).
 689
 690         The button images assigned with this method will @b not be deleted by
 691         @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself.
 692         Setting or assigning the button image list enables the display of image
 693         buttons. Once enabled, the only way to disable the display of button
 694         images is to set the button image list to @NULL.
 695
 696         @note This function is only available in the generic version.
 697
 698         @see AssignButtonsImageList().
 699     */
 700     void SetButtonsImageList(wxImageList* imageList);
 701
 702     /**
 703         Sets the normal image list. The image list assigned with this method
 704         will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you
 705         must delete it yourself.
 706
 707         @see AssignImageList().
 708     */
 709     void SetImageList(wxImageList* imageList);
 710
 711     /**
 712         Sets the indentation for the tree control.
 713     */
 714     void SetIndent(int indent);
 715
 716     /**
 717         Sets the colour of the item's background.
 718     */
 719     void SetItemBackgroundColour(const wxTreeItemId& item,
 720                                  const wxColour& col);
 721
 722     /**
 723         Makes item appear in bold font if @a bold parameter is @true or resets
 724         it to the normal state.
 725
 726         @see IsBold()
 727     */
 728     void SetItemBold(const wxTreeItemId& item, bool bold = true);
 729
 730     /**
 731         Sets the item client data.
 732
 733         @beginWxPythonOnly
 734         - @b SetPyData( @a item, @c obj): Associate the given Python Object with
 735             the wxTreeItemData for the given item Id.
 736         @endWxPythonOnly
 737
 738     */
 739     void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
 740
 741
 742     /**
 743         Gives the item the visual feedback for Drag'n'Drop actions, which is
 744         useful if something is dragged from the outside onto the tree control
 745         (as opposed to a DnD operation within the tree control, which already
 746         is implemented internally).
 747     */
 748     void SetItemDropHighlight(const wxTreeItemId& item,
 749                               bool highlight = true);
 750
 751     /**
 752         Sets the item's font. All items in the tree should have the same height
 753         to avoid text clipping, so the fonts height should be the same for all
 754         of them, although font attributes may vary.
 755
 756         @see SetItemBold()
 757     */
 758     void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 759
 760     /**
 761         Force appearance of the button next to the item. This is useful to
 762         allow the user to expand the items which don't have any children now,
 763         but instead adding them only when needed, thus minimizing memory
 764         usage and loading time.
 765     */
 766     void SetItemHasChildren(const wxTreeItemId& item,
 767                             bool hasChildren = true);
 768
 769     /**
 770         Sets the specified item's image. See GetItemImage() for the description
 771         of the @a which parameter.
 772     */
 773     void SetItemImage(const wxTreeItemId& item, int image,
 774                       wxTreeItemIcon which = wxTreeItemIcon_Normal);
 775
 776     /**
 777         Sets the selected item image (this function is obsolete, use @ref
 778         SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected )
 779         instead).
 780     */
 781     void SetItemSelectedImage(const wxTreeItemId& item, int selImage);
 782
 783     /**
 784         Sets the specified item state. The value of @a state may be:
 785         - wxTREE_ITEMSTATE_NONE: to disable the item state (the state image will
 786           be not displayed).
 787         - wxTREE_ITEMSTATE_NEXT: to set the next item state.
 788         - wxTREE_ITEMSTATE_PREV: to set the previous item statem.
 789     */
 790     void SetItemState(const wxTreeItemId& item, int state);
 791
 792     /**
 793         Sets the item label.
 794     */
 795     void SetItemText(const wxTreeItemId& item, const wxString& text);
 796
 797     /**
 798         Sets the colour of the item's text.
 799     */
 800     void SetItemTextColour(const wxTreeItemId& item,
 801                            const wxColour& col);
 802
 803     /**
 804         If @true is passed, specifies that the control will use a quick
 805         calculation for the best size, looking only at the first and last items.
 806         Otherwise, it will look at all items. The default is @false.
 807
 808         @see GetQuickBestSize()
 809     */
 810     void SetQuickBestSize(bool quickBestSize);
 811
 812     /**
 813         Sets the state image list (from which application-defined state images
 814         are taken). Image list assigned with this method will @b not be deleted
 815         by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it
 816         yourself.
 817
 818         @see AssignStateImageList().
 819     */
 820     void SetStateImageList(wxImageList* imageList);
 821
 822     /**
 823         Sets the mode flags associated with the display of the tree control. The
 824         new mode takes effect immediately.
 825
 826         @note Generic only; MSW ignores changes.
 827     */
 828     void SetWindowStyle(long styles);
 829
 830     /**
 831         Sorts the children of the given item using OnCompareItems().
 832         You should override that method to change the sort order (the default is
 833         ascending case-sensitive alphabetical order).
 834
 835         @see wxTreeItemData, OnCompareItems()
 836     */
 837     void SortChildren(const wxTreeItemId& item);
 838
 839     /**
 840         Toggles the given item between collapsed and expanded states.
 841     */
 842     void Toggle(const wxTreeItemId& item);
 843
 844     /**
 845         Toggles the given item between selected and unselected states. For
 846         multiselection controls only.
 847     */
 848     void ToggleItemSelection(const wxTreeItemId& item);
 849
 850     /**
 851         Removes the selection from the currently selected item (if any).
 852     */
 853     void Unselect();
 854
 855     /**
 856         This function either behaves the same as Unselect() if the control
 857         doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
 858         items if it does have this style.
 859     */
 860     void UnselectAll();
 861
 862     /**
 863         Unselects the given item. This works in multiselection controls only.
 864     */
 865     void UnselectItem(const wxTreeItemId& item);
 866 };
 867
 868
 869
 870 /**
 871     @class wxTreeEvent
 872     @wxheader{treectrl.h}
 873
 874     A tree event holds information about events associated with wxTreeCtrl
 875     objects.
 876
 877     To process input from a tree control, use these event handler macros to
 878     direct input to member functions that take a wxTreeEvent argument.
 879
 880     @beginEventTable{wxTreeEvent}
 881     @event{EVT_TREE_BEGIN_DRAG(id, func)}
 882         Begin dragging with the left mouse button.
 883     @event{EVT_TREE_BEGIN_RDRAG(id, func)}
 884         Begin dragging with the right mouse button.
 885     @event{EVT_TREE_END_DRAG(id, func)}
 886         End dragging with the left or right mouse button.
 887     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
 888         Begin editing a label. This can be prevented by calling Veto().
 889     @event{EVT_TREE_END_LABEL_EDIT(id, func)}
 890         Finish editing a label. This can be prevented by calling Veto().
 891     @event{EVT_TREE_DELETE_ITEM(id, func)}
 892         Delete an item.
 893     @event{EVT_TREE_GET_INFO(id, func)}
 894         Request information from the application.
 895     @event{EVT_TREE_SET_INFO(id, func)}
 896         Information is being supplied.
 897     @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
 898         The item has been activated, i.e. chosen by double clicking it with
 899         mouse or from keyboard.
 900     @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
 901         The item has been collapsed.
 902     @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
 903         The item is being collapsed. This can be prevented by calling Veto().
 904     @event{EVT_TREE_ITEM_EXPANDED(id, func)}
 905         The item has been expanded.
 906     @event{EVT_TREE_ITEM_EXPANDING(id, func)}
 907         The item is being expanded. This can be prevented by calling Veto().
 908     @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
 909         The user has clicked the item with the right mouse button.
 910     @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
 911         The user has clicked the item with the middle mouse button.
 912     @event{EVT_TREE_SEL_CHANGED(id, func)}
 913         Selection has changed.
 914     @event{EVT_TREE_SEL_CHANGING(id, func)}
 915         Selection is changing. This can be prevented by calling Veto().
 916     @event{EVT_TREE_KEY_DOWN(id, func)}
 917         A key has been pressed.
 918     @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
 919         The opportunity to set the item tooltip is being given to the
 920         application (call SetToolTip()). Windows only.
 921     @event{EVT_TREE_ITEM_MENU(id, func)}
 922         The context menu for the selected item has been requested, either by a
 923         right click or by using the menu key.
 924     @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
 925         The state image has been clicked. Windows only.
 926     @endEventTable
 927
 928     @library{wxbase}
 929     @category{events}
 930
 931     @see wxTreeCtrl
 932 */
 933 class wxTreeEvent : public wxNotifyEvent
 934 {
 935 public:
 936     /**
 937         Constructor, used by wxWidgets itself only.
 938     */
 939     wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree);
 940
 941     /**
 942         Returns the item (valid for all events).
 943     */
 944     wxTreeItemId GetItem() const;
 945
 946     /**
 947         Returns the key code if the event is a key event. Use GetKeyEvent() to
 948         get the values of the modifier keys for this event (i.e. Shift or Ctrl).
 949     */
 950     int GetKeyCode() const;
 951
 952     /**
 953         Returns the key event for EVT_TREE_KEY_DOWN() events.
 954     */
 955     const wxKeyEvent GetKeyEvent() const;
 956
 957     /**
 958         Returns the label if the event is a begin or end edit label event.
 959     */
 960     const wxString GetLabel() const;
 961
 962     /**
 963         Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and
 964         EVT_TREE_ITEM_CHANGED() events).
 965     */
 966     wxTreeItemId GetOldItem() const;
 967
 968     /**
 969         Returns the position of the mouse pointer if the event is a drag or
 970         menu-context event.
 971
 972         In both cases the position is in client coordinates - i.e. relative to
 973         the wxTreeCtrl window (so that you can pass it directly to e.g.
 974         wxWindow::PopupMenu()).
 975     */
 976     wxPoint GetPoint() const;
 977
 978     /**
 979         Returns @true if the label edit was cancelled. This should be called
 980         from within an EVT_TREE_END_LABEL_EDIT() handler.
 981     */
 982     bool IsEditCancelled() const;
 983
 984     /**
 985         Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP()
 986         events). Windows only.
 987     */
 988     void SetToolTip(const wxString& tooltip);
 989 };