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