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