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