interface/treectrl.h

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