interface/wx/treectrl.h

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