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         Returns the item label.
 429     */
 430     wxString GetItemText(const wxTreeItemId& item) const;
 431
 432     /**
 433         Returns the colour of the item label.
 434     */
 435     wxColour GetItemTextColour(const wxTreeItemId& item) const;
 436
 437     /**
 438         Returns the last child of the item (or an invalid tree item if this item
 439         has no children).
 440
 441         @see GetFirstChild(), GetNextSibling(), GetLastChild()
 442     */
 443     wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 444
 445     /**
 446         Returns the next child; call GetFirstChild() for the first child. For
 447         this enumeration function you must pass in a 'cookie' parameter which is
 448         opaque for the application but is necessary for the library to make
 449         these functions reentrant (i.e. allow more than one enumeration on one
 450         and the same object simultaneously). The cookie passed to
 451         GetFirstChild() and GetNextChild() should be the same.
 452
 453         Returns an invalid tree item if there are no further children.
 454
 455         @beginWxPythonOnly
 456         In wxPython the returned wxTreeItemId and the new cookie value are both
 457         returned as a tuple containing the two values.
 458         @endWxPythonOnly
 459
 460         @see GetFirstChild()
 461     */
 462     wxTreeItemId GetNextChild(const wxTreeItemId& item,
 463                               wxTreeItemIdValue& cookie) const;
 464
 465     /**
 466         Returns the next sibling of the specified item; call GetPrevSibling()
 467         for the previous sibling.
 468
 469         Returns an invalid tree item if there are no further siblings.
 470
 471         @see GetPrevSibling()
 472     */
 473     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 474
 475     /**
 476         Returns the next visible item or an invalid item if this item is the
 477         last visible one.
 478
 479         @note The @a item itself must be visible.
 480     */
 481     wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 482
 483     /**
 484         Returns the previous sibling of the specified item; call
 485         GetNextSibling() for the next sibling.
 486
 487         Returns an invalid tree item if there are no further children.
 488
 489         @see GetNextSibling()
 490     */
 491     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 492
 493     /**
 494         Returns the previous visible item or an invalid item if this item is the
 495         first visible one.
 496
 497         @note The @a item itself must be visible.
 498     */
 499     wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 500
 501     /**
 502         Returns @true if the control will use a quick calculation for the best
 503         size, looking only at the first and last items. The default is @false.
 504
 505         @see SetQuickBestSize()
 506     */
 507     bool GetQuickBestSize() const;
 508
 509     /**
 510         Returns the root item for the tree control.
 511     */
 512     wxTreeItemId GetRootItem() const;
 513
 514     /**
 515         Returns the selection, or an invalid item if there is no selection. This
 516         function only works with the controls without @c wxTR_MULTIPLE style,
 517         use GetSelections() for the controls which do have this style.
 518     */
 519     wxTreeItemId GetSelection() const;
 520
 521     /**
 522         Fills the array of tree items passed in with the currently selected
 523         items. This function can be called only if the control has the @c
 524         wxTR_MULTIPLE style.
 525
 526         Returns the number of selected items.
 527
 528         @beginWxPythonOnly
 529         The wxPython version of this method accepts no parameters and returns a
 530         Python list of @ref wxTreeItemId "wxTreeItemId"s.
 531         @endWxPythonOnly
 532     */
 533     unsigned int GetSelections(wxArrayTreeItemIds& selection) const;
 534
 535     /**
 536         Returns the state image list (from which application-defined state
 537         images are taken).
 538     */
 539     wxImageList* GetStateImageList() const;
 540
 541     /**
 542         Calculates which (if any) item is under the given @a point, returning
 543         the tree item id at this point plus extra information @a flags. @a flags
 544         is a bitlist of the following:
 545
 546         - @c wxTREE_HITTEST_ABOVE: Above the client area.
 547         - @c wxTREE_HITTEST_BELOW: Below the client area.
 548         - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item.
 549         - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item.
 550         - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item.
 551         - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an
 552             item.
 553         - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with
 554             an item.
 555         - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item.
 556         - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view
 557             item that is in a user-defined state.
 558         - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
 559         - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
 560
 561         @beginWxPythonOnly
 562         In wxPython both the wxTreeItemId and the flags are returned as a tuple.
 563         @endWxPythonOnly
 564     */
 565     wxTreeItemId HitTest(const wxPoint& point, int& flags) const;
 566
 567
 568     /**
 569         Inserts an item after a given one (@a previous).
 570
 571         The @a image and @a selImage parameters are an index within the normal
 572         image list specifying the image to use for unselected and selected
 573         items, respectively. If @a image -1 and @a selImage is -1, the same
 574         image is used for both selected and unselected items.
 575     */
 576     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 577                             const wxTreeItemId& previous,
 578                             const wxString& text,
 579                             int image = -1,
 580                             int selImage = -1,
 581                             wxTreeItemData* data = NULL);
 582
 583     /**
 584         Inserts an item before one identified
 585         by its position (@a before). @a before must be less than the number of
 586         children.
 587
 588         The @a image and @a selImage parameters are an index within the normal
 589         image list specifying the image to use for unselected and selected
 590         items, respectively. If @a image -1 and @a selImage is -1, the same
 591         image is used for both selected and unselected items.
 592
 593         @beginWxPythonOnly
 594         In wxPython, this form of this method is called @c InsertItemBefore().
 595         @endWxPythonOnly
 596     */
 597     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 598                             size_t before,
 599                             const wxString& text,
 600                             int image = -1,
 601                             int selImage = -1,
 602                             wxTreeItemData* data = NULL);
 603
 604     /**
 605         Returns @true if the given item is in bold state.
 606
 607         @see SetItemBold()
 608     */
 609     bool IsBold(const wxTreeItemId& item) const;
 610
 611     /**
 612         Returns @true if the control is empty (i.e. has no items, even no root
 613         one).
 614     */
 615     bool IsEmpty() const;
 616
 617     /**
 618         Returns @true if the item is expanded (only makes sense if it has
 619         children).
 620     */
 621     bool IsExpanded(const wxTreeItemId& item) const;
 622
 623     /**
 624         Returns @true if the item is selected.
 625     */
 626     bool IsSelected(const wxTreeItemId& item) const;
 627
 628     /**
 629         Returns @true if the item is visible on the screen.
 630     */
 631     bool IsVisible(const wxTreeItemId& item) const;
 632
 633     /**
 634         Returns @true if the item has children.
 635     */
 636     bool ItemHasChildren(const wxTreeItemId& item) const;
 637
 638     /**
 639         Override this function in the derived class to change the sort order of
 640         the items in the tree control. The function should return a negative,
 641         zero or positive value if the first item is less than, equal to or
 642         greater than the second one.
 643
 644         Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS()
 645         and IMPLEMENT_DYNAMIC_CLASS() if you override this function because
 646         otherwise the base class considers that it is not overridden and uses
 647         the default comparison, i.e. sorts the items alphabetically, which
 648         allows it optimize away the calls to the virtual function completely.
 649
 650         @see SortChildren()
 651     */
 652     int OnCompareItems(const wxTreeItemId& item1,
 653                        const wxTreeItemId& item2);
 654
 655     /**
 656         Appends an item as the first child of @a parent, return a new item id.
 657
 658         The @a image and @a selImage parameters are an index within the normal
 659         image list specifying the image to use for unselected and selected
 660         items, respectively. If @a image -1 and @a selImage is -1, the same
 661         image is used for both selected and unselected items.
 662     */
 663     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 664                              const wxString& text,
 665                              int image = -1,
 666                              int selImage = -1,
 667                              wxTreeItemData* data = NULL);
 668
 669     /**
 670         Scrolls the specified item into view.
 671     */
 672     void ScrollTo(const wxTreeItemId& item);
 673
 674     /**
 675         Selects the given item. In multiple selection controls, can be also used
 676         to deselect a currently selected item if the value of @a select is
 677         @false.
 678     */
 679     void SelectItem(const wxTreeItemId& item, bool select = true);
 680
 681     /**
 682         Sets the buttons image list (from which application-defined button
 683         images are taken).
 684
 685         The button images assigned with this method will @b not be deleted by
 686         @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself.
 687         Setting or assigning the button image list enables the display of image
 688         buttons. Once enabled, the only way to disable the display of button
 689         images is to set the button image list to @NULL.
 690
 691         @note This function is only available in the generic version.
 692
 693         @see AssignButtonsImageList().
 694     */
 695     void SetButtonsImageList(wxImageList* imageList);
 696
 697     /**
 698         Sets the normal image list. The image list assigned with this method
 699         will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you
 700         must delete it yourself.
 701
 702         @see AssignImageList().
 703     */
 704     void SetImageList(wxImageList* imageList);
 705
 706     /**
 707         Sets the indentation for the tree control.
 708     */
 709     void SetIndent(int indent);
 710
 711     /**
 712         Sets the colour of the item's background.
 713     */
 714     void SetItemBackgroundColour(const wxTreeItemId& item,
 715                                  const wxColour& col);
 716
 717     /**
 718         Makes item appear in bold font if @a bold parameter is @true or resets
 719         it to the normal state.
 720
 721         @see IsBold()
 722     */
 723     void SetItemBold(const wxTreeItemId& item, bool bold = true);
 724
 725     /**
 726         Sets the item client data.
 727
 728         @beginWxPythonOnly
 729         - @b SetPyData( @a item, @c obj): Associate the given Python Object with
 730             the wxTreeItemData for the given item Id.
 731         @endWxPythonOnly
 732
 733     */
 734     void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
 735
 736
 737     /**
 738         Gives the item the visual feedback for Drag'n'Drop actions, which is
 739         useful if something is dragged from the outside onto the tree control
 740         (as opposed to a DnD operation within the tree control, which already
 741         is implemented internally).
 742     */
 743     void SetItemDropHighlight(const wxTreeItemId& item,
 744                               bool highlight = true);
 745
 746     /**
 747         Sets the item's font. All items in the tree should have the same height
 748         to avoid text clipping, so the fonts height should be the same for all
 749         of them, although font attributes may vary.
 750
 751         @see SetItemBold()
 752     */
 753     void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 754
 755     /**
 756         Force appearance of the button next to the item. This is useful to
 757         allow the user to expand the items which don't have any children now,
 758         but instead adding them only when needed, thus minimizing memory
 759         usage and loading time.
 760     */
 761     void SetItemHasChildren(const wxTreeItemId& item,
 762                             bool hasChildren = true);
 763
 764     /**
 765         Sets the specified item's image. See GetItemImage() for the description
 766         of the @a which parameter.
 767     */
 768     void SetItemImage(const wxTreeItemId& item, int image,
 769                       wxTreeItemIcon which = wxTreeItemIcon_Normal);
 770
 771     /**
 772         Sets the selected item image (this function is obsolete, use @ref
 773         SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected )
 774         instead).
 775     */
 776     void SetItemSelectedImage(const wxTreeItemId& item, int selImage);
 777
 778     /**
 779         Sets the item label.
 780     */
 781     void SetItemText(const wxTreeItemId& item, const wxString& text);
 782
 783     /**
 784         Sets the colour of the item's text.
 785     */
 786     void SetItemTextColour(const wxTreeItemId& item,
 787                            const wxColour& col);
 788
 789     /**
 790         If @true is passed, specifies that the control will use a quick
 791         calculation for the best size, looking only at the first and last items.
 792         Otherwise, it will look at all items. The default is @false.
 793
 794         @see GetQuickBestSize()
 795     */
 796     void SetQuickBestSize(bool quickBestSize);
 797
 798     /**
 799         Sets the state image list (from which application-defined state images
 800         are taken). Image list assigned with this method will @b not be deleted
 801         by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it
 802         yourself.
 803
 804         @see AssignStateImageList().
 805     */
 806     void SetStateImageList(wxImageList* imageList);
 807
 808     /**
 809         Sets the mode flags associated with the display of the tree control. The
 810         new mode takes effect immediately.
 811
 812         @note Generic only; MSW ignores changes.
 813     */
 814     void SetWindowStyle(long styles);
 815
 816     /**
 817         Sorts the children of the given item using OnCompareItems().
 818         You should override that method to change the sort order (the default is
 819         ascending case-sensitive alphabetical order).
 820
 821         @see wxTreeItemData, OnCompareItems()
 822     */
 823     void SortChildren(const wxTreeItemId& item);
 824
 825     /**
 826         Toggles the given item between collapsed and expanded states.
 827     */
 828     void Toggle(const wxTreeItemId& item);
 829
 830     /**
 831         Toggles the given item between selected and unselected states. For
 832         multiselection controls only.
 833     */
 834     void ToggleItemSelection(const wxTreeItemId& item);
 835
 836     /**
 837         Removes the selection from the currently selected item (if any).
 838     */
 839     void Unselect();
 840
 841     /**
 842         This function either behaves the same as Unselect() if the control
 843         doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
 844         items if it does have this style.
 845     */
 846     void UnselectAll();
 847
 848     /**
 849         Unselects the given item. This works in multiselection controls only.
 850     */
 851     void UnselectItem(const wxTreeItemId& item);
 852 };
 853
 854
 855
 856 /**
 857     @class wxTreeEvent
 858     @wxheader{treectrl.h}
 859
 860     A tree event holds information about events associated with wxTreeCtrl
 861     objects.
 862
 863     To process input from a tree control, use these event handler macros to
 864     direct input to member functions that take a wxTreeEvent argument.
 865
 866     @beginEventTable{wxTreeEvent}
 867     @event{EVT_TREE_BEGIN_DRAG(id, func)}
 868         Begin dragging with the left mouse button.
 869     @event{EVT_TREE_BEGIN_RDRAG(id, func)}
 870         Begin dragging with the right mouse button.
 871     @event{EVT_TREE_END_DRAG(id, func)}
 872         End dragging with the left or right mouse button.
 873     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
 874         Begin editing a label. This can be prevented by calling Veto().
 875     @event{EVT_TREE_END_LABEL_EDIT(id, func)}
 876         Finish editing a label. This can be prevented by calling Veto().
 877     @event{EVT_TREE_DELETE_ITEM(id, func)}
 878         Delete an item.
 879     @event{EVT_TREE_GET_INFO(id, func)}
 880         Request information from the application.
 881     @event{EVT_TREE_SET_INFO(id, func)}
 882         Information is being supplied.
 883     @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
 884         The item has been activated, i.e. chosen by double clicking it with
 885         mouse or from keyboard.
 886     @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
 887         The item has been collapsed.
 888     @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
 889         The item is being collapsed. This can be prevented by calling Veto().
 890     @event{EVT_TREE_ITEM_EXPANDED(id, func)}
 891         The item has been expanded.
 892     @event{EVT_TREE_ITEM_EXPANDING(id, func)}
 893         The item is being expanded. This can be prevented by calling Veto().
 894     @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
 895         The user has clicked the item with the right mouse button.
 896     @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
 897         The user has clicked the item with the middle mouse button.
 898     @event{EVT_TREE_SEL_CHANGED(id, func)}
 899         Selection has changed.
 900     @event{EVT_TREE_SEL_CHANGING(id, func)}
 901         Selection is changing. This can be prevented by calling Veto().
 902     @event{EVT_TREE_KEY_DOWN(id, func)}
 903         A key has been pressed.
 904     @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
 905         The opportunity to set the item tooltip is being given to the
 906         application (call SetToolTip()). Windows only.
 907     @event{EVT_TREE_ITEM_MENU(id, func)}
 908         The context menu for the selected item has been requested, either by a
 909         right click or by using the menu key.
 910     @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
 911         The state image has been clicked. Windows only.
 912     @endEventTable
 913
 914     @library{wxbase}
 915     @category{events}
 916
 917     @see wxTreeCtrl
 918 */
 919 class wxTreeEvent : public wxNotifyEvent
 920 {
 921 public:
 922     /**
 923         Constructor, used by wxWidgets itself only.
 924     */
 925     wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree);
 926
 927     /**
 928         Returns the item (valid for all events).
 929     */
 930     wxTreeItemId GetItem() const;
 931
 932     /**
 933         Returns the key code if the event is a key event. Use GetKeyEvent() to
 934         get the values of the modifier keys for this event (i.e. Shift or Ctrl).
 935     */
 936     int GetKeyCode() const;
 937
 938     /**
 939         Returns the key event for EVT_TREE_KEY_DOWN() events.
 940     */
 941     const wxKeyEvent GetKeyEvent() const;
 942
 943     /**
 944         Returns the label if the event is a begin or end edit label event.
 945     */
 946     const wxString GetLabel() const;
 947
 948     /**
 949         Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and
 950         EVT_TREE_ITEM_CHANGED() events).
 951     */
 952     wxTreeItemId GetOldItem() const;
 953
 954     /**
 955         Returns the position of the mouse pointer if the event is a drag or
 956         menu-context event.
 957
 958         In both cases the position is in client coordinates - i.e. relative to
 959         the wxTreeCtrl window (so that you can pass it directly to e.g.
 960         wxWindow::PopupMenu()).
 961     */
 962     wxPoint GetPoint() const;
 963
 964     /**
 965         Returns @true if the label edit was cancelled. This should be called
 966         from within an EVT_TREE_END_LABEL_EDIT() handler.
 967     */
 968     bool IsEditCancelled() const;
 969
 970     /**
 971         Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP()
 972         events). Windows only.
 973     */
 974     void SetToolTip(const wxString& tooltip);
 975 };
 976