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