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