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         If the font hadn't been explicitly set for the specified @a item with
 521         SetItemFont(), returns an invalid ::wxNullFont font. GetFont() can be
 522         used to retrieve the global tree control font used for the items
 523         without any specific font.
 524     */
 525     virtual wxFont GetItemFont(const wxTreeItemId& item) const;
 526
 527     /**
 528         Gets the specified item image. The value of @a which may be:
 529         - ::wxTreeItemIcon_Normal: to get the normal item image.
 530         - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the
 531             image which is shown when the item is currently selected).
 532         - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes
 533             sense for items which have children - then this image is shown when
 534             the item is expanded and the normal image is shown when it is
 535             collapsed).
 536         - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image
 537             (which is shown when an expanded item is currently selected).
 538     */
 539     virtual int GetItemImage(const wxTreeItemId& item,
 540                              wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 541
 542     /**
 543         Returns the item's parent.
 544     */
 545     virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
 546
 547     /**
 548         Gets the specified item state.
 549     */
 550     int GetItemState(const wxTreeItemId& item) const;
 551
 552     /**
 553         Returns the item label.
 554     */
 555     virtual wxString GetItemText(const wxTreeItemId& item) const;
 556
 557     /**
 558         Returns the colour of the item label.
 559     */
 560     virtual wxColour GetItemTextColour(const wxTreeItemId& item) const;
 561
 562     /**
 563         Returns the last child of the item (or an invalid tree item if this item
 564         has no children).
 565
 566         @see GetFirstChild(), GetNextSibling(), GetLastChild()
 567     */
 568     virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 569
 570     /**
 571         Returns the next child; call GetFirstChild() for the first child. For
 572         this enumeration function you must pass in a 'cookie' parameter which is
 573         opaque for the application but is necessary for the library to make
 574         these functions reentrant (i.e. allow more than one enumeration on one
 575         and the same object simultaneously). The cookie passed to
 576         GetFirstChild() and GetNextChild() should be the same.
 577
 578         Returns an invalid tree item if there are no further children.
 579
 580         @beginWxPerlOnly
 581         In wxPerl this method returns a 2-element list
 582         (item, cookie) instead of modifying its parameters.
 583         @endWxPerlOnly
 584
 585         @see GetFirstChild()
 586     */
 587     virtual wxTreeItemId GetNextChild(const wxTreeItemId& item,
 588                                       wxTreeItemIdValue& cookie) const;
 589
 590     /**
 591         Returns the next sibling of the specified item; call GetPrevSibling()
 592         for the previous sibling.
 593
 594         Returns an invalid tree item if there are no further siblings.
 595
 596         @see GetPrevSibling()
 597     */
 598     virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 599
 600     /**
 601         Returns the next visible item or an invalid item if this item is the
 602         last visible one.
 603
 604         @note The @a item itself must be visible.
 605     */
 606     virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 607
 608     /**
 609         Returns the previous sibling of the specified item; call
 610         GetNextSibling() for the next sibling.
 611
 612         Returns an invalid tree item if there are no further children.
 613
 614         @see GetNextSibling()
 615     */
 616     virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 617
 618     /**
 619         Returns the previous visible item or an invalid item if this item is the
 620         first visible one.
 621
 622         @note The @a item itself must be visible.
 623     */
 624     virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 625
 626     /**
 627         Returns @true if the control will use a quick calculation for the best
 628         size, looking only at the first and last items. The default is @false.
 629
 630         @see SetQuickBestSize()
 631     */
 632     bool GetQuickBestSize() const;
 633
 634     /**
 635         Returns the root item for the tree control.
 636     */
 637     virtual wxTreeItemId GetRootItem() const;
 638
 639     /**
 640         Returns the selection, or an invalid item if there is no selection. This
 641         function only works with the controls without @c wxTR_MULTIPLE style,
 642         use GetSelections() for the controls which do have this style
 643         or, if a single item is wanted, use GetFocusedItem().
 644     */
 645     virtual wxTreeItemId GetSelection() const;
 646
 647     /**
 648         Fills the array of tree items passed in with the currently selected
 649         items. This function can be called only if the control has the @c
 650         wxTR_MULTIPLE style.
 651
 652         Returns the number of selected items.
 653
 654         @beginWxPerlOnly
 655         In wxPerl this method takes no parameters and returns a list of
 656         @c Wx::TreeItemId.
 657         @endWxPerlOnly
 658     */
 659     virtual size_t GetSelections(wxArrayTreeItemIds& selection) const;
 660
 661     /**
 662         Returns the state image list (from which application-defined state
 663         images are taken).
 664     */
 665     wxImageList* GetStateImageList() const;
 666
 667     /**
 668         Calculates which (if any) item is under the given @a point, returning
 669         the tree item id at this point plus extra information @a flags. @a flags
 670         is a bitlist of the following:
 671
 672         - @c wxTREE_HITTEST_ABOVE: Above the client area.
 673         - @c wxTREE_HITTEST_BELOW: Below the client area.
 674         - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item.
 675         - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item.
 676         - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item.
 677         - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an item.
 678         - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
 679         - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item.
 680         - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view
 681           item that is in a user-defined state.
 682         - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
 683         - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
 684
 685         @beginWxPerlOnly
 686         In wxPerl this method only takes the @a point parameter
 687         and returns a 2-element list (item, flags).
 688         @endWxPerlOnly
 689     */
 690     wxTreeItemId HitTest(const wxPoint& point, int& flags) const;
 691
 692
 693     /**
 694         Inserts an item after a given one (@a previous).
 695
 696         The @a image and @a selImage parameters are an index within the normal
 697         image list specifying the image to use for unselected and selected
 698         items, respectively. If @a image -1 and @a selImage is -1, the same
 699         image is used for both selected and unselected items.
 700     */
 701     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 702                             const wxTreeItemId& previous,
 703                             const wxString& text,
 704                             int image = -1,
 705                             int selImage = -1,
 706                             wxTreeItemData* data = NULL);
 707
 708     /**
 709         Inserts an item before one identified
 710         by its position (@a pos). @a pos must be less than or equal to
 711         the number of children.
 712
 713         The @a image and @a selImage parameters are an index within the normal
 714         image list specifying the image to use for unselected and selected
 715         items, respectively. If @a image -1 and @a selImage is -1, the same
 716         image is used for both selected and unselected items.
 717     */
 718     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 719                             size_t pos,
 720                             const wxString& text,
 721                             int image = -1,
 722                             int selImage = -1,
 723                             wxTreeItemData* data = NULL);
 724
 725     /**
 726         Returns @true if the given item is in bold state.
 727
 728         @see SetItemBold()
 729     */
 730     virtual bool IsBold(const wxTreeItemId& item) const;
 731
 732     /**
 733         Returns @true if the control is empty (i.e.\ has no items, even no root
 734         one).
 735     */
 736     bool IsEmpty() const;
 737
 738     /**
 739         Returns @true if the item is expanded (only makes sense if it has
 740         children).
 741     */
 742     virtual bool IsExpanded(const wxTreeItemId& item) const;
 743
 744     /**
 745         Returns @true if the item is selected.
 746     */
 747     virtual bool IsSelected(const wxTreeItemId& item) const;
 748
 749     /**
 750         Returns @true if the item is visible on the screen.
 751     */
 752     virtual bool IsVisible(const wxTreeItemId& item) const;
 753
 754     /**
 755         Returns @true if the item has children.
 756     */
 757     virtual bool ItemHasChildren(const wxTreeItemId& item) const;
 758
 759     /**
 760         Override this function in the derived class to change the sort order of
 761         the items in the tree control. The function should return a negative,
 762         zero or positive value if the first item is less than, equal to or
 763         greater than the second one.
 764
 765         Please note that you @b must use wxRTTI macros wxDECLARE_DYNAMIC_CLASS()
 766         and wxIMPLEMENT_DYNAMIC_CLASS() if you override this function because
 767         otherwise the base class considers that it is not overridden and uses
 768         the default comparison, i.e. sorts the items alphabetically, which
 769         allows it optimize away the calls to the virtual function completely.
 770
 771         @see SortChildren()
 772     */
 773     virtual int OnCompareItems(const wxTreeItemId& item1,
 774                                const wxTreeItemId& item2);
 775
 776     /**
 777         Appends an item as the first child of @a parent, return a new item id.
 778
 779         The @a image and @a selImage parameters are an index within the normal
 780         image list specifying the image to use for unselected and selected
 781         items, respectively. If @a image -1 and @a selImage is -1, the same
 782         image is used for both selected and unselected items.
 783     */
 784     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 785                              const wxString& text,
 786                              int image = -1,
 787                              int selImage = -1,
 788                              wxTreeItemData* data = NULL);
 789
 790     /**
 791         Scrolls the specified item into view.
 792     */
 793     virtual void ScrollTo(const wxTreeItemId& item);
 794
 795     /**
 796         Selects the given item.
 797
 798         In multiple selection controls, can be also used to deselect a
 799         currently selected item if the value of @a select is @false.
 800
 801         Notice that calling this method will generate
 802         @c wxEVT_TREE_SEL_CHANGING and @c wxEVT_TREE_SEL_CHANGED
 803         events and that the change could be vetoed by the former event handler.
 804     */
 805     virtual void SelectItem(const wxTreeItemId& item, bool select = true);
 806
 807     /**
 808         Sets the buttons image list (from which application-defined button
 809         images are taken).
 810
 811         The button images assigned with this method will @b not be deleted by
 812         @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself.
 813         Setting or assigning the button image list enables the display of image
 814         buttons. Once enabled, the only way to disable the display of button
 815         images is to set the button image list to @NULL.
 816
 817         @note This function is only available in the generic version.
 818
 819         @see AssignButtonsImageList().
 820     */
 821     void SetButtonsImageList(wxImageList* imageList);
 822
 823     /**
 824         Sets the normal image list. The image list assigned with this method
 825         will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you
 826         must delete it yourself.
 827
 828         @see AssignImageList().
 829     */
 830     virtual void SetImageList(wxImageList* imageList);
 831
 832     /**
 833         Sets the indentation for the tree control.
 834     */
 835     virtual void SetIndent(unsigned int indent);
 836
 837     /**
 838         Sets the colour of the item's background.
 839     */
 840     virtual void SetItemBackgroundColour(const wxTreeItemId& item,
 841                                          const wxColour& col);
 842
 843     /**
 844         Makes item appear in bold font if @a bold parameter is @true or resets
 845         it to the normal state.
 846
 847         @see IsBold()
 848     */
 849     virtual void SetItemBold(const wxTreeItemId& item, bool bold = true);
 850
 851     /**
 852         Sets the item client data.
 853
 854         Notice that the client data previously associated with the @a item (if
 855         any) is @em not freed by this function and so calling this function
 856         multiple times for the same item will result in memory leaks unless you
 857         delete the old item data pointer yourself.
 858
 859         @beginWxPerlOnly
 860         wxPerl provides the following shortcut method:
 861         - SetPlData(item, data): sets the Perl data
 862           associated with the @c Wx::TreeItemData. It is just the same as
 863           tree->GetItemData(item)->SetData(data).
 864         @endWxPerlOnly
 865     */
 866     virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
 867
 868
 869     /**
 870         Gives the item the visual feedback for Drag'n'Drop actions, which is
 871         useful if something is dragged from the outside onto the tree control
 872         (as opposed to a DnD operation within the tree control, which already
 873         is implemented internally).
 874     */
 875     virtual void SetItemDropHighlight(const wxTreeItemId& item,
 876                                       bool highlight = true);
 877
 878     /**
 879         Sets the item's font. All items in the tree should have the same height
 880         to avoid text clipping, so the fonts height should be the same for all
 881         of them, although font attributes may vary.
 882
 883         @see SetItemBold()
 884     */
 885     virtual void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 886
 887     /**
 888         Force appearance of the button next to the item. This is useful to
 889         allow the user to expand the items which don't have any children now,
 890         but instead adding them only when needed, thus minimizing memory
 891         usage and loading time.
 892     */
 893     virtual void SetItemHasChildren(const wxTreeItemId& item,
 894                                     bool hasChildren = true);
 895
 896     /**
 897         Sets the specified item's image. See GetItemImage() for the description
 898         of the @a which parameter.
 899     */
 900     virtual void SetItemImage(const wxTreeItemId& item, int image,
 901                               wxTreeItemIcon which = wxTreeItemIcon_Normal);
 902
 903     /**
 904         Sets the specified item state. The value of @a state may be:
 905         - @c wxTREE_ITEMSTATE_NONE: to disable the item state (the state image will
 906             be not displayed).
 907         - @c wxTREE_ITEMSTATE_NEXT: to set the next item state.
 908         - @c wxTREE_ITEMSTATE_PREV: to set the previous item state.
 909     */
 910     void SetItemState(const wxTreeItemId& item, int state);
 911
 912     /**
 913         Sets the item label.
 914     */
 915     virtual void SetItemText(const wxTreeItemId& item, const wxString& text);
 916
 917     /**
 918         Sets the colour of the item's text.
 919     */
 920     virtual void SetItemTextColour(const wxTreeItemId& item,
 921                                    const wxColour& col);
 922
 923     /**
 924         If @true is passed, specifies that the control will use a quick
 925         calculation for the best size, looking only at the first and last items.
 926         Otherwise, it will look at all items. The default is @false.
 927
 928         @see GetQuickBestSize()
 929     */
 930     void SetQuickBestSize(bool quickBestSize);
 931
 932     /**
 933         Sets the state image list (from which application-defined state images
 934         are taken). Image list assigned with this method will @b not be deleted
 935         by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it
 936         yourself.
 937
 938         @see AssignStateImageList().
 939     */
 940     virtual void SetStateImageList(wxImageList* imageList);
 941
 942     /**
 943         Sets the mode flags associated with the display of the tree control. The
 944         new mode takes effect immediately.
 945
 946         @note Generic only; MSW ignores changes.
 947     */
 948     void SetWindowStyle(long styles);
 949
 950     /**
 951         Sorts the children of the given item using OnCompareItems().
 952         You should override that method to change the sort order (the default is
 953         ascending case-sensitive alphabetical order).
 954
 955         @see wxTreeItemData, OnCompareItems()
 956     */
 957     virtual void SortChildren(const wxTreeItemId& item);
 958
 959     /**
 960         Toggles the given item between collapsed and expanded states.
 961     */
 962     virtual void Toggle(const wxTreeItemId& item);
 963
 964     /**
 965         Toggles the given item between selected and unselected states. For
 966         multiselection controls only.
 967     */
 968     void ToggleItemSelection(const wxTreeItemId& item);
 969
 970     /**
 971         Removes the selection from the currently selected item (if any).
 972     */
 973     virtual void Unselect();
 974
 975     /**
 976         This function either behaves the same as Unselect() if the control
 977         doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
 978         items if it does have this style.
 979     */
 980     virtual void UnselectAll();
 981
 982     /**
 983         Unselects the given item. This works in multiselection controls only.
 984     */
 985     void UnselectItem(const wxTreeItemId& item);
 986
 987     /**
 988         Select all the immediate children of the given parent.
 989
 990         This function can be used with multiselection controls only.
 991
 992         @since 2.9.1
 993     */
 994     virtual void SelectChildren(const wxTreeItemId& parent);
 995 };
 996
 997
 998
 999 /**
1000     @class wxTreeEvent
1001
1002     A tree event holds information about events associated with wxTreeCtrl
1003     objects.
1004
1005     To process input from a tree control, use these event handler macros to
1006     direct input to member functions that take a wxTreeEvent argument.
1007
1008     @beginEventTable{wxTreeEvent}
1009     @event{EVT_TREE_BEGIN_DRAG(id, func)}
1010         Begin dragging with the left mouse button. If you want to enable
1011         left-dragging you need to intercept this event and explicitly call
1012         wxTreeEvent::Allow(), as it's vetoed by default. Also notice that the
1013         control must have an associated image list (see SetImageList()) to
1014         drag its items under MSW.
1015     @event{EVT_TREE_BEGIN_RDRAG(id, func)}
1016         Begin dragging with the right mouse button. If you want to enable
1017         right-dragging you need to intercept this event and explicitly call
1018         wxTreeEvent::Allow(), as it's vetoed by default.
1019     @event{EVT_TREE_END_DRAG(id, func)}
1020         End dragging with the left or right mouse button.
1021     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
1022         Begin editing a label. This can be prevented by calling Veto().
1023     @event{EVT_TREE_END_LABEL_EDIT(id, func)}
1024         Finish editing a label. This can be prevented by calling Veto().
1025     @event{EVT_TREE_DELETE_ITEM(id, func)}
1026         Delete an item.
1027     @event{EVT_TREE_GET_INFO(id, func)}
1028         Request information from the application.
1029     @event{EVT_TREE_SET_INFO(id, func)}
1030         Information is being supplied.
1031     @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
1032         The item has been activated, i.e. chosen by double clicking it with
1033         mouse or from keyboard.
1034     @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
1035         The item has been collapsed.
1036     @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
1037         The item is being collapsed. This can be prevented by calling Veto().
1038     @event{EVT_TREE_ITEM_EXPANDED(id, func)}
1039         The item has been expanded.
1040     @event{EVT_TREE_ITEM_EXPANDING(id, func)}
1041         The item is being expanded. This can be prevented by calling Veto().
1042     @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
1043         The user has clicked the item with the right mouse button.
1044     @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
1045         The user has clicked the item with the middle mouse button.
1046     @event{EVT_TREE_SEL_CHANGED(id, func)}
1047         Selection has changed.
1048     @event{EVT_TREE_SEL_CHANGING(id, func)}
1049         Selection is changing. This can be prevented by calling Veto().
1050     @event{EVT_TREE_KEY_DOWN(id, func)}
1051         A key has been pressed.
1052     @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
1053         The opportunity to set the item tooltip is being given to the
1054         application (call SetToolTip()). Windows only.
1055     @event{EVT_TREE_ITEM_MENU(id, func)}
1056         The context menu for the selected item has been requested, either by a
1057         right click or by using the menu key.
1058     @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
1059         The state image has been clicked.
1060     @endEventTable
1061
1062     @library{wxcore}
1063     @category{events}
1064
1065     @see wxTreeCtrl
1066 */
1067 class wxTreeEvent : public wxNotifyEvent
1068 {
1069 public:
1070     /**
1071         Constructor, used by wxWidgets itself only.
1072     */
1073     wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree,
1074                 const wxTreeItemId& item = wxTreeItemId());
1075
1076     /**
1077         Returns the item (valid for all events).
1078     */
1079     wxTreeItemId GetItem() const;
1080
1081     /**
1082         Returns the key code if the event is a key event. Use GetKeyEvent() to
1083         get the values of the modifier keys for this event (i.e. Shift or Ctrl).
1084     */
1085     int GetKeyCode() const;
1086
1087     /**
1088         Returns the key event for @c EVT_TREE_KEY_DOWN events.
1089     */
1090     const wxKeyEvent& GetKeyEvent() const;
1091
1092     /**
1093         Returns the label if the event is a begin or end edit label event.
1094     */
1095     const wxString& GetLabel() const;
1096
1097     /**
1098         Returns the old item index (valid for @c EVT_TREE_ITEM_CHANGING and
1099         @c EVT_TREE_ITEM_CHANGED events).
1100     */
1101     wxTreeItemId GetOldItem() const;
1102
1103     /**
1104         Returns the position of the mouse pointer if the event is a drag or
1105         menu-context event.
1106
1107         In both cases the position is in client coordinates - i.e. relative to
1108         the wxTreeCtrl window (so that you can pass it directly to e.g.
1109         wxWindow::PopupMenu()).
1110     */
1111     wxPoint GetPoint() const;
1112
1113     /**
1114         Returns @true if the label edit was cancelled. This should be called
1115         from within an @c EVT_TREE_END_LABEL_EDIT handler.
1116     */
1117     bool IsEditCancelled() const;
1118
1119     /**
1120         Set the tooltip for the item (valid for @c EVT_TREE_ITEM_GETTOOLTIP
1121         events). Windows only.
1122     */
1123     void SetToolTip(const wxString& tooltip);
1124 };
1125
1126
1127 wxEventType wxEVT_TREE_BEGIN_DRAG;
1128 wxEventType wxEVT_TREE_BEGIN_RDRAG;
1129 wxEventType wxEVT_TREE_BEGIN_LABEL_EDIT;
1130 wxEventType wxEVT_TREE_END_LABEL_EDIT;
1131 wxEventType wxEVT_TREE_DELETE_ITEM;
1132 wxEventType wxEVT_TREE_GET_INFO;
1133 wxEventType wxEVT_TREE_SET_INFO;
1134 wxEventType wxEVT_TREE_ITEM_EXPANDED;
1135 wxEventType wxEVT_TREE_ITEM_EXPANDING;
1136 wxEventType wxEVT_TREE_ITEM_COLLAPSED;
1137 wxEventType wxEVT_TREE_ITEM_COLLAPSING;
1138 wxEventType wxEVT_TREE_SEL_CHANGED;
1139 wxEventType wxEVT_TREE_SEL_CHANGING;
1140 wxEventType wxEVT_TREE_KEY_DOWN;
1141 wxEventType wxEVT_TREE_ITEM_ACTIVATED;
1142 wxEventType wxEVT_TREE_ITEM_RIGHT_CLICK;
1143 wxEventType wxEVT_TREE_ITEM_MIDDLE_CLICK;
1144 wxEventType wxEVT_TREE_END_DRAG;
1145 wxEventType wxEVT_TREE_STATE_IMAGE_CLICK;
1146 wxEventType wxEVT_TREE_ITEM_GETTOOLTIP;
1147 wxEventType wxEVT_TREE_ITEM_MENU;
1148