include/wx/os2/treectrl.h

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