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