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