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