interface/wx/treectrl.h

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