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. In multiple selection controls, can be also used
 816         to deselect a currently selected item if the value of @a select is
 817         @false.
 818     */
 819     virtual void SelectItem(const wxTreeItemId& item, bool select = true);
 820
 821     /**
 822         Sets the buttons image list (from which application-defined button
 823         images are taken).
 824
 825         The button images assigned with this method will @b not be deleted by
 826         @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself.
 827         Setting or assigning the button image list enables the display of image
 828         buttons. Once enabled, the only way to disable the display of button
 829         images is to set the button image list to @NULL.
 830
 831         @note This function is only available in the generic version.
 832
 833         @see AssignButtonsImageList().
 834     */
 835     void SetButtonsImageList(wxImageList* imageList);
 836
 837     /**
 838         Sets the normal image list. The image list assigned with this method
 839         will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you
 840         must delete it yourself.
 841
 842         @see AssignImageList().
 843     */
 844     virtual void SetImageList(wxImageList* imageList);
 845
 846     /**
 847         Sets the indentation for the tree control.
 848     */
 849     virtual void SetIndent(unsigned int indent);
 850
 851     /**
 852         Sets the colour of the item's background.
 853     */
 854     virtual void SetItemBackgroundColour(const wxTreeItemId& item,
 855                                          const wxColour& col);
 856
 857     /**
 858         Makes item appear in bold font if @a bold parameter is @true or resets
 859         it to the normal state.
 860
 861         @see IsBold()
 862     */
 863     virtual void SetItemBold(const wxTreeItemId& item, bool bold = true);
 864
 865     /**
 866         Sets the item client data.
 867
 868         Notice that the client data previously associated with the @a item (if
 869         any) is @em not freed by this function and so calling this function
 870         multiple times for the same item will result in memory leaks unless you
 871         delete the old item data pointer yourself.
 872
 873         @beginWxPythonOnly
 874         - @b SetPyData( @a item, @c obj): Associate the given Python Object with
 875             the wxTreeItemData for the given item Id.
 876         @endWxPythonOnly
 877
 878         @beginWxPerlOnly
 879         wxPerl provides the following shortcut method:
 880         - SetPlData(item, data): sets the Perl data
 881           associated with the @c Wx::TreeItemData. It is just the same as
 882           tree->GetItemData(item)->SetData(data).
 883         @endWxPerlOnly
 884     */
 885     virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
 886
 887
 888     /**
 889         Gives the item the visual feedback for Drag'n'Drop actions, which is
 890         useful if something is dragged from the outside onto the tree control
 891         (as opposed to a DnD operation within the tree control, which already
 892         is implemented internally).
 893     */
 894     virtual void SetItemDropHighlight(const wxTreeItemId& item,
 895                                       bool highlight = true);
 896
 897     /**
 898         Sets the item's font. All items in the tree should have the same height
 899         to avoid text clipping, so the fonts height should be the same for all
 900         of them, although font attributes may vary.
 901
 902         @see SetItemBold()
 903     */
 904     virtual void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 905
 906     /**
 907         Force appearance of the button next to the item. This is useful to
 908         allow the user to expand the items which don't have any children now,
 909         but instead adding them only when needed, thus minimizing memory
 910         usage and loading time.
 911     */
 912     virtual void SetItemHasChildren(const wxTreeItemId& item,
 913                                     bool hasChildren = true);
 914
 915     /**
 916         Sets the specified item's image. See GetItemImage() for the description
 917         of the @a which parameter.
 918     */
 919     virtual void SetItemImage(const wxTreeItemId& item, int image,
 920                               wxTreeItemIcon which = wxTreeItemIcon_Normal);
 921
 922     /**
 923         Sets the specified item state. The value of @a state may be:
 924         - @c wxTREE_ITEMSTATE_NONE: to disable the item state (the state image will
 925             be not displayed).
 926         - @c wxTREE_ITEMSTATE_NEXT: to set the next item state.
 927         - @c wxTREE_ITEMSTATE_PREV: to set the previous item state.
 928     */
 929     void SetItemState(const wxTreeItemId& item, int state);
 930
 931     /**
 932         Sets the item label.
 933     */
 934     virtual void SetItemText(const wxTreeItemId& item, const wxString& text);
 935
 936     /**
 937         Sets the colour of the item's text.
 938     */
 939     virtual void SetItemTextColour(const wxTreeItemId& item,
 940                                    const wxColour& col);
 941
 942     /**
 943         If @true is passed, specifies that the control will use a quick
 944         calculation for the best size, looking only at the first and last items.
 945         Otherwise, it will look at all items. The default is @false.
 946
 947         @see GetQuickBestSize()
 948     */
 949     void SetQuickBestSize(bool quickBestSize);
 950
 951     /**
 952         Sets the state image list (from which application-defined state images
 953         are taken). Image list assigned with this method will @b not be deleted
 954         by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it
 955         yourself.
 956
 957         @see AssignStateImageList().
 958     */
 959     virtual void SetStateImageList(wxImageList* imageList);
 960
 961     /**
 962         Sets the mode flags associated with the display of the tree control. The
 963         new mode takes effect immediately.
 964
 965         @note Generic only; MSW ignores changes.
 966     */
 967     void SetWindowStyle(long styles);
 968
 969     /**
 970         Sorts the children of the given item using OnCompareItems().
 971         You should override that method to change the sort order (the default is
 972         ascending case-sensitive alphabetical order).
 973
 974         @see wxTreeItemData, OnCompareItems()
 975     */
 976     virtual void SortChildren(const wxTreeItemId& item);
 977
 978     /**
 979         Toggles the given item between collapsed and expanded states.
 980     */
 981     virtual void Toggle(const wxTreeItemId& item);
 982
 983     /**
 984         Toggles the given item between selected and unselected states. For
 985         multiselection controls only.
 986     */
 987     void ToggleItemSelection(const wxTreeItemId& item);
 988
 989     /**
 990         Removes the selection from the currently selected item (if any).
 991     */
 992     virtual void Unselect();
 993
 994     /**
 995         This function either behaves the same as Unselect() if the control
 996         doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
 997         items if it does have this style.
 998     */
 999     virtual void UnselectAll();
1000
1001     /**
1002         Unselects the given item. This works in multiselection controls only.
1003     */
1004     void UnselectItem(const wxTreeItemId& item);
1005
1006     /**
1007         Select all the immediate children of the given parent.
1008
1009         This function can be used with multiselection controls only.
1010
1011         @since 2.9.1
1012     */
1013     virtual void SelectChildren(const wxTreeItemId& parent);
1014 };
1015
1016
1017
1018 /**
1019     @class wxTreeEvent
1020
1021     A tree event holds information about events associated with wxTreeCtrl
1022     objects.
1023
1024     To process input from a tree control, use these event handler macros to
1025     direct input to member functions that take a wxTreeEvent argument.
1026
1027     @beginEventTable{wxTreeEvent}
1028     @event{EVT_TREE_BEGIN_DRAG(id, func)}
1029         Begin dragging with the left mouse button. If you want to enable
1030         left-dragging you need to intercept this event and explicitly call
1031         wxTreeEvent::Allow(), as it's vetoed by default. Also notice that the
1032         control must have an associated image list (see SetImageList()) to
1033         drag its items under MSW.
1034     @event{EVT_TREE_BEGIN_RDRAG(id, func)}
1035         Begin dragging with the right mouse button. If you want to enable
1036         right-dragging you need to intercept this event and explicitly call
1037         wxTreeEvent::Allow(), as it's vetoed by default.
1038     @event{EVT_TREE_END_DRAG(id, func)}
1039         End dragging with the left or right mouse button.
1040     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
1041         Begin editing a label. This can be prevented by calling Veto().
1042     @event{EVT_TREE_END_LABEL_EDIT(id, func)}
1043         Finish editing a label. This can be prevented by calling Veto().
1044     @event{EVT_TREE_DELETE_ITEM(id, func)}
1045         Delete an item.
1046     @event{EVT_TREE_GET_INFO(id, func)}
1047         Request information from the application.
1048     @event{EVT_TREE_SET_INFO(id, func)}
1049         Information is being supplied.
1050     @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
1051         The item has been activated, i.e. chosen by double clicking it with
1052         mouse or from keyboard.
1053     @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
1054         The item has been collapsed.
1055     @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
1056         The item is being collapsed. This can be prevented by calling Veto().
1057     @event{EVT_TREE_ITEM_EXPANDED(id, func)}
1058         The item has been expanded.
1059     @event{EVT_TREE_ITEM_EXPANDING(id, func)}
1060         The item is being expanded. This can be prevented by calling Veto().
1061     @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
1062         The user has clicked the item with the right mouse button.
1063     @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
1064         The user has clicked the item with the middle mouse button.
1065     @event{EVT_TREE_SEL_CHANGED(id, func)}
1066         Selection has changed.
1067     @event{EVT_TREE_SEL_CHANGING(id, func)}
1068         Selection is changing. This can be prevented by calling Veto().
1069     @event{EVT_TREE_KEY_DOWN(id, func)}
1070         A key has been pressed.
1071     @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
1072         The opportunity to set the item tooltip is being given to the
1073         application (call SetToolTip()). Windows only.
1074     @event{EVT_TREE_ITEM_MENU(id, func)}
1075         The context menu for the selected item has been requested, either by a
1076         right click or by using the menu key.
1077     @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
1078         The state image has been clicked.
1079     @endEventTable
1080
1081     @library{wxbase}
1082     @category{events}
1083
1084     @see wxTreeCtrl
1085 */
1086 class wxTreeEvent : public wxNotifyEvent
1087 {
1088 public:
1089     /**
1090         Constructor, used by wxWidgets itself only.
1091     */
1092     wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree,
1093                 const wxTreeItemId& item = wxTreeItemId());
1094
1095     /**
1096         Returns the item (valid for all events).
1097     */
1098     wxTreeItemId GetItem() const;
1099
1100     /**
1101         Returns the key code if the event is a key event. Use GetKeyEvent() to
1102         get the values of the modifier keys for this event (i.e. Shift or Ctrl).
1103     */
1104     int GetKeyCode() const;
1105
1106     /**
1107         Returns the key event for @c EVT_TREE_KEY_DOWN events.
1108     */
1109     const wxKeyEvent& GetKeyEvent() const;
1110
1111     /**
1112         Returns the label if the event is a begin or end edit label event.
1113     */
1114     const wxString& GetLabel() const;
1115
1116     /**
1117         Returns the old item index (valid for @c EVT_TREE_ITEM_CHANGING and
1118         @c EVT_TREE_ITEM_CHANGED events).
1119     */
1120     wxTreeItemId GetOldItem() const;
1121
1122     /**
1123         Returns the position of the mouse pointer if the event is a drag or
1124         menu-context event.
1125
1126         In both cases the position is in client coordinates - i.e. relative to
1127         the wxTreeCtrl window (so that you can pass it directly to e.g.
1128         wxWindow::PopupMenu()).
1129     */
1130     wxPoint GetPoint() const;
1131
1132     /**
1133         Returns @true if the label edit was cancelled. This should be called
1134         from within an @c EVT_TREE_END_LABEL_EDIT handler.
1135     */
1136     bool IsEditCancelled() const;
1137
1138     /**
1139         Set the tooltip for the item (valid for @c EVT_TREE_ITEM_GETTOOLTIP
1140         events). Windows only.
1141     */
1142     void SetToolTip(const wxString& tooltip);
1143 };