1///////////////////////////////////////////////////////////////////////////// 2// Name: wx/os2/treectrl.h 3// Purpose: wxTreeCtrl class 4// Author: David Webster 5// Modified by: 6// Created: 01/23/03 7// RCS-ID: $Id: treectrl.h 38416 2006-03-28 13:11:20Z ABX $ 8// Copyright: (c) David Webster 9// Licence: wxWindows licence 10///////////////////////////////////////////////////////////////////////////// 11 12#ifndef _WX_TREECTRL_H_ 13#define _WX_TREECTRL_H_ 14 15// ---------------------------------------------------------------------------- 16// headers 17// ---------------------------------------------------------------------------- 18 19#if wxUSE_TREECTRL 20 21#include "wx/textctrl.h" 22#include "wx/dynarray.h" 23#include "wx/treebase.h" 24#include "wx/hashmap.h" 25 26// the type for "untyped" data 27typedef long wxDataType; 28 29// fwd decl 30class WXDLLEXPORT wxImageList; 31class WXDLLEXPORT wxDragImage; 32struct WXDLLEXPORT wxTreeViewItem; 33 34// a callback function used for sorting tree items, it should return -1 if the 35// first item precedes the second, +1 if the second precedes the first or 0 if 36// they're equivalent 37class wxTreeItemData; 38 39#if WXWIN_COMPATIBILITY_2_6 40 // flags for deprecated InsertItem() variant 41 #define wxTREE_INSERT_FIRST 0xFFFF0001 42 #define wxTREE_INSERT_LAST 0xFFFF0002 43#endif 44 45// hash storing attributes for our items 46WX_DECLARE_EXPORTED_VOIDPTR_HASH_MAP(wxTreeItemAttr *, wxMapTreeAttr); 47 48// ---------------------------------------------------------------------------- 49// wxTreeCtrl 50// ---------------------------------------------------------------------------- 51class WXDLLEXPORT wxTreeCtrl : public wxControl 52{ 53public: 54 // creation 55 // -------- 56 wxTreeCtrl() { Init(); } 57 58 wxTreeCtrl( wxWindow* pParent 59 ,wxWindowID vId = wxID_ANY 60 ,const wxPoint& rPos = wxDefaultPosition 61 ,const wxSize& rSize = wxDefaultSize 62 ,long lStyle = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT 63 ,const wxValidator& rValidator = wxDefaultValidator 64 ,const wxString& rsName = wxTreeCtrlNameStr 65 ) 66 { 67 Create( pParent 68 ,vId 69 ,rPos 70 ,rSize 71 ,lStyle 72 ,rValidator 73 ,rsName 74 ); 75 } 76 virtual ~wxTreeCtrl(); 77 78 bool Create( wxWindow* pParent 79 ,wxWindowID vId = wxID_ANY 80 ,const wxPoint& rPos = wxDefaultPosition 81 ,const wxSize& rSize = wxDefaultSize 82 ,long lStyle = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT 83 ,const wxValidator& rValidator = wxDefaultValidator 84 ,const wxString& rsName = wxTreeCtrlNameStr 85 ); 86 87 // 88 // Accessors 89 // --------- 90 // 91 92 // 93 // Get the total number of items in the control 94 // 95 virtual unsigned int GetCount(void) const; 96 97 // 98 // Indent is the number of pixels the children are indented relative to 99 // the parents position. SetIndent() also redraws the control 100 // immediately. 101 // 102 unsigned int GetIndent(void) const; 103 void SetIndent(unsigned int uIndent); 104 105 // 106 // Spacing is the number of pixels between the start and the Text 107 // 108 unsigned int GetSpacing(void) const { return 18; } // return wxGTK default 109 void SetSpacing(unsigned int uSpacing) { } 110 111 // 112 // Image list: these functions allow to associate an image list with 113 // the control and retrieve it. Note that the control does _not_ delete 114 // the associated image list when it's deleted in order to allow image 115 // lists to be shared between different controls. 116 // 117 // OS/2 doesn't really use imagelists as MSW does, but since the MSW 118 // control is the basis for this one, until I decide how to get rid of 119 // the need for them they are here for now. 120 // 121 wxImageList* GetImageList(void) const; 122 wxImageList* GetStateImageList(void) const; 123 124 void AssignImageList(wxImageList* pImageList); 125 void AssignStateImageList(wxImageList* pImageList); 126 void SetImageList(wxImageList* pImageList); 127 void SetStateImageList(wxImageList* pImageList); 128 129 // 130 // Functions to work with tree ctrl items. Unfortunately, they can _not_ be 131 // member functions of wxTreeItem because they must know the tree the item 132 // belongs to for Windows implementation and storing the pointer to 133 // wxTreeCtrl in each wxTreeItem is just too much waste. 134 135 // 136 // Item's label 137 // 138 wxString GetItemText(const wxTreeItemId& rItem) const; 139 void SetItemText( const wxTreeItemId& rItem 140 ,const wxString& rsText 141 ); 142 143 // 144 // One of the images associated with the item (normal by default) 145 // 146 int GetItemImage( const wxTreeItemId& rItem 147 ,wxTreeItemIcon vWhich = wxTreeItemIcon_Normal 148 ) const; 149 void SetItemImage( const wxTreeItemId& rItem 150 ,int nImage 151 ,wxTreeItemIcon vWhich = wxTreeItemIcon_Normal 152 ); 153 154 // 155 // Data associated with the item 156 // 157 wxTreeItemData* GetItemData(const wxTreeItemId& rItem) const; 158 void SetItemData( const wxTreeItemId& rItem 159 ,wxTreeItemData* pData 160 ); 161 162 // 163 // Item's text colour 164 // 165 wxColour GetItemTextColour(const wxTreeItemId& rItem) const; 166 void SetItemTextColour( const wxTreeItemId& rItem 167 ,const wxColour& rColor 168 ); 169 170 // 171 // Item's background colour 172 // 173 wxColour GetItemBackgroundColour(const wxTreeItemId& rItem) const; 174 void SetItemBackgroundColour( const wxTreeItemId& rItem 175 ,const wxColour& rColour 176 ); 177 178 // 179 // Item's font 180 // 181 wxFont GetItemFont(const wxTreeItemId& rItem) const; 182 void SetItemFont( const wxTreeItemId& rItem 183 ,const wxFont& rFont 184 ); 185 186 // 187 // Force appearance of [+] button near the item. This is useful to 188 // allow the user to expand the items which don't have any children now 189 // - but instead add them only when needed, thus minimizing memory 190 // usage and loading time. 191 // 192 void SetItemHasChildren( const wxTreeItemId& rItem 193 ,bool bHas = true 194 ); 195 196 // 197 // The item will be shown in bold 198 // 199 void SetItemBold( const wxTreeItemId& rItem 200 ,bool bBold = true 201 ); 202 203 // 204 // The item will be shown with a drop highlight 205 // 206 void SetItemDropHighlight( const wxTreeItemId& rItem 207 ,bool bHighlight = true 208 ); 209 210 // 211 // Item status inquiries 212 // --------------------- 213 // 214 215 // 216 // Is the item visible (it might be outside the view or not expanded)? 217 // 218 bool IsVisible(const wxTreeItemId& rItem) const; 219 220 // 221 // Does the item has any children? 222 // 223 bool ItemHasChildren(const wxTreeItemId& rItem) const; 224 225 // 226 // Is the item expanded (only makes sense if HasChildren())? 227 // 228 bool IsExpanded(const wxTreeItemId& rItem) const; 229 230 // 231 // Is this item currently selected (the same as has focus)? 232 // 233 bool IsSelected(const wxTreeItemId& rItem) const; 234 235 // 236 // Is item text in bold font? 237 // 238 bool IsBold(const wxTreeItemId& rItem) const; 239 240 // 241 // Number of children 242 // ------------------ 243 // 244 245 // 246 // If 'bRecursively' is false, only immediate children count, otherwise 247 // the returned number is the number of all items in this branch 248 // 249 size_t GetChildrenCount( const wxTreeItemId& rItem 250 ,bool bRecursively = true 251 ) const; 252 253 // 254 // Navigation 255 // ---------- 256 // 257 258 // 259 // Get the root tree item 260 // 261 wxTreeItemId GetRootItem(void) const; 262 263 // 264 // Get the item currently selected (may return NULL if no selection) 265 // 266 wxTreeItemId GetSelection(void) const; 267 268 // 269 // Get the items currently selected, return the number of such item 270 // 271 size_t GetSelections(wxArrayTreeItemIds& rSelections) const; 272 273 // 274 // Get the parent of this item (may return NULL if root) 275 // 276 wxTreeItemId GetItemParent(const wxTreeItemId& rItem) const; 277 278 // for this enumeration function you must pass in a "cookie" parameter 279 // which is opaque for the application but is necessary for the library 280 // to make these functions reentrant (i.e. allow more than one 281 // enumeration on one and the same object simultaneously). Of course, 282 // the "cookie" passed to GetFirstChild() and GetNextChild() should be 283 // the same! 284 285 // get the first child of this item 286 wxTreeItemId GetFirstChild(const wxTreeItemId& item, 287 wxTreeItemIdValue& cookie) const; 288 // get the next child 289 wxTreeItemId GetNextChild(const wxTreeItemId& item, 290 wxTreeItemIdValue& cookie) const; 291 292 // 293 // Get the last child of this item - this method doesn't use cookies 294 // 295 wxTreeItemId GetLastChild(const wxTreeItemId& rItem) const; 296 297 // 298 // Get the next sibling of this item 299 // 300 wxTreeItemId GetNextSibling(const wxTreeItemId& rItem) const; 301 302 // 303 // Get the previous sibling 304 // 305 wxTreeItemId GetPrevSibling(const wxTreeItemId& rItem) const; 306 307 // 308 // Get first visible item 309 // 310 wxTreeItemId GetFirstVisibleItem(void) const; 311 312 // 313 // Get the next visible item: item must be visible itself! 314 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem() 315 // 316 wxTreeItemId GetNextVisible(const wxTreeItemId& rItem) const; 317 318 // 319 // Get the previous visible item: item must be visible itself! 320 // 321 wxTreeItemId GetPrevVisible(const wxTreeItemId& rItem) const; 322 323 // 324 // Operations 325 // ---------- 326 // 327 328 // 329 // Add the root node to the tree 330 // 331 wxTreeItemId AddRoot( const wxString& rsText 332 ,int nImage = -1 333 ,int nSelectedImage = -1 334 ,wxTreeItemData* pData = NULL 335 ); 336 337 // 338 // Insert a new item in as the first child of the parent 339 // 340 wxTreeItemId PrependItem( const wxTreeItemId& rParent 341 ,const wxString& rsText 342 ,int nImage = -1 343 ,int nSelectedImage = -1 344 ,wxTreeItemData* pData = NULL 345 ); 346 347 // 348 // Insert a new item after a given one 349 // 350 wxTreeItemId InsertItem( const wxTreeItemId& rParent 351 ,const wxTreeItemId& rIdPrevious 352 ,const wxString& rsText 353 ,int nImage = -1 354 ,int nSelectedImage = -1 355 ,wxTreeItemData* pData = NULL 356 ); 357 358 // 359 // Insert a new item before the one with the given index 360 // 361 wxTreeItemId InsertItem( const wxTreeItemId& pParent 362 ,size_t nIndex 363 ,const wxString& rsText 364 ,int nImage = -1 365 ,int nSelectedImage = -1 366 ,wxTreeItemData* pData = NULL 367 ); 368 369 // 370 // Insert a new item in as the last child of the parent 371 // 372 wxTreeItemId AppendItem( const wxTreeItemId& rParent 373 ,const wxString& rsText 374 ,int nImage = -1 375 ,int nSelectedImage = -1 376 ,wxTreeItemData* pData = NULL 377 ); 378 379 // 380 // Delete this item and associated data if any 381 // 382 void Delete(const wxTreeItemId& rItem); 383 384 // 385 // Delete all children (but don't delete the item itself) 386 // 387 void DeleteChildren(const wxTreeItemId& rItem); 388 389 // 390 // Delete all items from the tree 391 // 392 void DeleteAllItems(void); 393 394 // 395 // Expand this item 396 // 397 void Expand(const wxTreeItemId& rItem); 398 399 // 400 // Collapse the item without removing its children 401 // 402 void Collapse(const wxTreeItemId& rItem); 403 404 // 405 // Collapse the item and remove all children 406 // 407 void CollapseAndReset(const wxTreeItemId& rItem); 408 409 // 410 // Toggles the current state 411 // 412 void Toggle(const wxTreeItemId& rItem); 413 414 // 415 // Remove the selection from currently selected item (if any) 416 // 417 void Unselect(void); 418 419 // 420 // Unselect all items (only makes sense for multiple selection control) 421 // 422 void UnselectAll(void); 423 424 // 425 // Select this item 426 // 427 void SelectItem(const wxTreeItemId& rItem); 428 429 // 430 // Make sure this item is visible (expanding the parent item and/or 431 // scrolling to this item if necessary) 432 // 433 void EnsureVisible(const wxTreeItemId& rItem); 434 435 // 436 // Scroll to this item (but don't expand its parent) 437 // 438 void ScrollTo(const wxTreeItemId& rItem); 439 440 // 441 // OS/2 does not use a separate edit field for editting text. Here for 442 // interface compatibility, only. 443 // 444 wxTextCtrl* EditLabel( const wxTreeItemId& rItem 445 ,wxClassInfo* pTextCtrlClass = CLASSINFO(wxTextCtrl) 446 ); 447 448 // 449 // returns NULL for OS/2 in ALL cases 450 // 451 wxTextCtrl* GetEditControl(void) const {return (wxTextCtrl*)NULL;} 452 453 // 454 // End editing and accept or discard the changes to item label 455 // 456 void EndEditLabel( const wxTreeItemId& rItem 457 ,bool bDiscardChanges = false 458 ); 459 460 // 461 // Sorting 462 // ------- 463 // 464 465 // 466 // This function is called to compare 2 items and should return -1, 0 467 // or +1 if the first item is less than, equal to or greater than the 468 // second one. The base class version performs alphabetic comparaison 469 // of item labels (GetText) 470 // 471 virtual int OnCompareItems( const wxTreeItemId& rItem1 472 ,const wxTreeItemId& rItem2 473 ); 474 475 // 476 // Sort the children of this item using OnCompareItems 477 // 478 void SortChildren(const wxTreeItemId& rItem); 479 480 // 481 // Helpers 482 // ------- 483 // 484 485 // 486 // Determine to which item (if any) belongs the given point (the 487 // coordinates specified are relative to the client area of tree ctrl) 488 // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx 489 // constants. 490 491 // 492 // The first function is more portable (because easier to implement 493 // on other platforms), but the second one returns some extra info. 494 // 495 wxTreeItemId HitTest(const wxPoint& rPoint) 496 { int nDummy = 0; return HitTest(rPoint, nDummy); } 497 wxTreeItemId HitTest( const wxPoint& rPoint 498 ,int& rFlags 499 ); 500 501 // 502 // Get the bounding rectangle of the item (or of its label only) 503 // 504 bool GetBoundingRect( const wxTreeItemId& rItem 505 ,wxRect& rRect 506 ,bool bTextOnly = false 507 ) const; 508 509 // 510 // Deprecated 511 // ---------- 512 513#if WXWIN_COMPATIBILITY_2_4 514 // These methods are deprecated and will be removed in future versions of 515 // wxWidgets, they're here for compatibility only, don't use them in new 516 // code (the comments indicate why these methods are now useless and how to 517 // replace them) 518 // 519 520 // 521 // Use Expand, Collapse, CollapseAndReset or Toggle 522 // 523 wxDEPRECATED( void ExpandItem( const wxTreeItemId& rItem 524 ,int nAction 525 ) ); 526 527 // 528 // Use AddRoot, PrependItem or AppendItem 529 // 530 wxDEPRECATED( wxTreeItemId InsertItem( const wxTreeItemId& pParent 531 ,const wxString& rsText 532 ,int nImage = -1 533 ,int nSelImage = -1 534 ,long lInsertAfter = wxTREE_INSERT_LAST 535 ) ); 536 537 // 538 // Use Set/GetImageList and Set/GetStateImageList 539 // 540 wxDEPRECATED( wxImageList* GetImageList(int nVal) const ); 541 wxDEPRECATED( void SetImageList(wxImageList* pImageList, int nVal) ); 542 543 // 544 // Use Set/GetItemImage directly 545 // 546 wxDEPRECATED( int GetItemSelectedImage(const wxTreeItemId& rItem) const ); 547 wxDEPRECATED( void SetItemSelectedImage(const wxTreeItemId& rItem, int nImage) ); 548 549 // 550 // For this enumeration function you must pass in a "cookie" parameter 551 // which is opaque for the application but is necessary for the library 552 // to make these functions reentrant (i.e. allow more than one 553 // enumeration on one and the same object simultaneously). Of course, 554 // the "cookie" passed to GetFirstChild() and GetNextChild() should be 555 // the same! 556 // 557 558 // 559 // Get the first child of this item 560 // 561 wxDEPRECATED( wxTreeItemId GetFirstChild( const wxTreeItemId& rItem 562 ,long& rCookie 563 ) const ); 564 565 // 566 // Get the next child 567 // 568 wxDEPRECATED( wxTreeItemId GetNextChild( const wxTreeItemId& rItem 569 ,long& rCookie 570 ) const ); 571#endif // WXWIN_COMPATIBILITY_2_4 572 573 // 574 // Implementation 575 // -------------- 576 // 577 578 virtual MRESULT OS2WindowProc( WXUINT uMsg 579 ,WXWPARAM wParam 580 ,WXLPARAM lParam 581 ); 582 virtual bool OS2Command( WXUINT uParam 583 ,WXWORD wId 584 ); 585// virtual bool OMSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result); 586 587 // 588 // Override some base class virtuals 589 // 590 virtual bool SetBackgroundColour(const wxColour& rColour); 591 virtual bool SetForegroundColour(const wxColour& rColour); 592 593 // 594 // Get/set the check state for the item (only for wxTR_MULTIPLE) 595 // 596 bool IsItemChecked(const wxTreeItemId& rItem) const; 597 void SetItemCheck( const wxTreeItemId& rItem 598 ,bool bCheck = true 599 ); 600 601protected: 602 // 603 // SetImageList helper 604 // 605 void SetAnyImageList( wxImageList* pImageList 606 ,int nWhich 607 ); 608 609 // 610 // Refresh a single item 611 // 612 void RefreshItem(const wxTreeItemId& rItem); 613 614 wxImageList* m_pImageListNormal; // images for tree elements 615 wxImageList* m_pImageListState; // special images for app defined states 616 bool m_bOwnsImageListNormal; 617 bool m_bOwnsImageListState; 618 619private: 620 621 // 622 // The common part of all ctors 623 // 624 void Init(void); 625 626 // 627 // Helper functions 628 // 629 inline bool DoGetItem(wxTreeViewItem* pTvItem) const; 630 inline void DoSetItem(wxTreeViewItem* pTvItem); 631 632 inline void DoExpand( const wxTreeItemId& rItem 633 ,int nFlag 634 ); 635 wxTreeItemId DoInsertItem( const wxTreeItemId& pParent 636 ,wxTreeItemId hInsertAfter 637 ,const wxString& rsText 638 ,int nImage 639 ,int nSelectedImage 640 ,wxTreeItemData* pData 641 ); 642 int DoGetItemImageFromData( const wxTreeItemId& rItem 643 ,wxTreeItemIcon vWhich 644 ) const; 645 void DoSetItemImageFromData( const wxTreeItemId& rItem 646 ,int nImage 647 ,wxTreeItemIcon vWhich 648 ) const; 649 void DoSetItemImages( const wxTreeItemId& rItem 650 ,int nImage 651 ,int nImageSel 652 ); 653 void DeleteTextCtrl() { }; 654 655 // 656 // support for additional item images which we implement using 657 // wxTreeItemIndirectData technique - see the comments in msw/treectrl.cpp 658 // 659 void SetIndirectItemData( const wxTreeItemId& rItem 660 ,class wxTreeItemIndirectData* pData 661 ); 662 bool HasIndirectData(const wxTreeItemId& rItem) const; 663 bool IsDataIndirect(wxTreeItemData* pData) const 664 { return pData && pData->GetId().m_pItem == 0; } 665 666 // 667 // The hash storing the items attributes (indexed by items ids) 668 // 669 wxMapTreeAttr m_vAttrs; 670 671 // 672 // true if the hash above is not empty 673 // 674 bool m_bHasAnyAttr; 675 676 // 677 // Used for dragging 678 // 679 wxDragImage* m_pDragImage; 680 681 // Virtual root item, if wxTR_HIDE_ROOT is set. 682// void* m_pVirtualRoot; 683 684 // the starting item for selection with Shift 685// WXHTREEITEM m_htSelStart; 686// 687 friend class wxTreeItemIndirectData; 688 friend class wxTreeSortHelper; 689 690 DECLARE_DYNAMIC_CLASS(wxTreeCtrl) 691 DECLARE_NO_COPY_CLASS(wxTreeCtrl) 692}; // end of CLASS wxTreeCtrl 693 694#endif // wxUSE_TREECTRL 695 696#endif 697 // _WX_TREECTRL_H_ 698