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