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         // for this enumeration function you must pass in a "cookie" parameter
 277         // which is opaque for the application but is necessary for the library
 278         // to make these functions reentrant (i.e. allow more than one
 279         // enumeration on one and the same object simultaneously). Of course,
 280         // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 281         // the same!
 282
 283         // get the first child of this item
 284     wxTreeItemId GetFirstChild(const wxTreeItemId& item,
 285                                wxTreeItemIdValue& cookie) const;
 286         // get the next child
 287     wxTreeItemId GetNextChild(const wxTreeItemId& item,
 288                               wxTreeItemIdValue& cookie) const;
 289
 290     //
 291     // Get the last child of this item - this method doesn't use cookies
 292     //
 293     wxTreeItemId GetLastChild(const wxTreeItemId& rItem) const;
 294
 295     //
 296     // Get the next sibling of this item
 297     //
 298     wxTreeItemId GetNextSibling(const wxTreeItemId& rItem) const;
 299
 300     //
 301     // Get the previous sibling
 302     //
 303     wxTreeItemId GetPrevSibling(const wxTreeItemId& rItem) const;
 304
 305     //
 306     // Get first visible item
 307     //
 308     wxTreeItemId GetFirstVisibleItem(void) const;
 309
 310     //
 311     // Get the next visible item: item must be visible itself!
 312     // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
 313     //
 314     wxTreeItemId GetNextVisible(const wxTreeItemId& rItem) const;
 315
 316     //
 317     // Get the previous visible item: item must be visible itself!
 318     //
 319     wxTreeItemId GetPrevVisible(const wxTreeItemId& rItem) const;
 320
 321     //
 322     // Operations
 323     // ----------
 324     //
 325
 326     //
 327     // Add the root node to the tree
 328     //
 329     wxTreeItemId AddRoot( const wxString& rsText
 330                          ,int             nImage = -1
 331                          ,int             nSelectedImage = -1
 332                          ,wxTreeItemData* pData = NULL
 333                         );
 334
 335     //
 336     // Insert a new item in as the first child of the parent
 337     //
 338     wxTreeItemId PrependItem( const wxTreeItemId& rParent
 339                              ,const wxString&     rsText
 340                              ,int                 nImage = -1
 341                              ,int                 nSelectedImage = -1
 342                              ,wxTreeItemData*     pData = NULL
 343                             );
 344
 345     //
 346     // Insert a new item after a given one
 347     //
 348     wxTreeItemId InsertItem( const wxTreeItemId& rParent
 349                             ,const wxTreeItemId& rIdPrevious
 350                             ,const wxString&     rsText
 351                             ,int                 nImage = -1
 352                             ,int                 nSelectedImage = -1
 353                             ,wxTreeItemData*     pData = NULL
 354                            );
 355
 356     //
 357     // Insert a new item before the one with the given index
 358     //
 359     wxTreeItemId InsertItem( const wxTreeItemId& pParent
 360                             ,size_t              nIndex
 361                             ,const wxString&     rsText
 362                             ,int                 nImage = -1
 363                             ,int                 nSelectedImage = -1
 364                             ,wxTreeItemData*     pData = NULL
 365                            );
 366
 367     //
 368     // Insert a new item in as the last child of the parent
 369     //
 370     wxTreeItemId AppendItem( const wxTreeItemId& rParent
 371                             ,const wxString&     rsText
 372                             ,int                 nImage = -1
 373                             ,int                 nSelectedImage = -1
 374                             ,wxTreeItemData*     pData = NULL
 375                            );
 376
 377     //
 378     // Delete this item and associated data if any
 379     //
 380     void Delete(const wxTreeItemId& rItem);
 381
 382     //
 383     // Delete all children (but don't delete the item itself)
 384     //
 385     void DeleteChildren(const wxTreeItemId& rItem);
 386
 387     //
 388     // Delete all items from the tree
 389     //
 390     void DeleteAllItems(void);
 391
 392     //
 393     // Expand this item
 394     //
 395     void Expand(const wxTreeItemId& rItem);
 396
 397     //
 398     // Collapse the item without removing its children
 399     //
 400     void Collapse(const wxTreeItemId& rItem);
 401
 402     //
 403     // Collapse the item and remove all children
 404     //
 405     void CollapseAndReset(const wxTreeItemId& rItem);
 406
 407     //
 408     // Toggles the current state
 409     //
 410     void Toggle(const wxTreeItemId& rItem);
 411
 412     //
 413     // Remove the selection from currently selected item (if any)
 414     //
 415     void Unselect(void);
 416
 417     //
 418     // Unselect all items (only makes sense for multiple selection control)
 419     //
 420     void UnselectAll(void);
 421
 422     //
 423     // Select this item
 424     //
 425     void SelectItem(const wxTreeItemId& rItem);
 426
 427     //
 428     // Make sure this item is visible (expanding the parent item and/or
 429     // scrolling to this item if necessary)
 430     //
 431     void EnsureVisible(const wxTreeItemId& rItem);
 432
 433     //
 434     // Scroll to this item (but don't expand its parent)
 435     //
 436     void ScrollTo(const wxTreeItemId& rItem);
 437
 438     //
 439     // OS/2 does not use a separate edit field for editting text. Here for
 440     // interface compatibility, only.
 441     //
 442     wxTextCtrl* EditLabel( const wxTreeItemId& rItem
 443                           ,wxClassInfo*        pTextCtrlClass = CLASSINFO(wxTextCtrl)
 444                          );
 445
 446     //
 447     // returns NULL for OS/2 in ALL cases
 448     //
 449     wxTextCtrl* GetEditControl(void) const {return (wxTextCtrl*)NULL;}
 450
 451     //
 452     // End editing and accept or discard the changes to item label
 453     //
 454     void EndEditLabel( const wxTreeItemId& rItem
 455                       ,bool                bDiscardChanges = false
 456                      );
 457
 458     //
 459     // Sorting
 460     // -------
 461     //
 462
 463     //
 464     // This function is called to compare 2 items and should return -1, 0
 465     // or +1 if the first item is less than, equal to or greater than the
 466     // second one. The base class version performs alphabetic comparaison
 467     // of item labels (GetText)
 468     //
 469     virtual int OnCompareItems( const wxTreeItemId& rItem1
 470                                ,const wxTreeItemId& rItem2
 471                               );
 472
 473     //
 474     // Sort the children of this item using OnCompareItems
 475     //
 476     void SortChildren(const wxTreeItemId& rItem);
 477
 478     //
 479     // Helpers
 480     // -------
 481     //
 482
 483     //
 484     // Determine to which item (if any) belongs the given point (the
 485     // coordinates specified are relative to the client area of tree ctrl)
 486     // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx
 487     // constants.
 488
 489     //
 490     // The first function is more portable (because easier to implement
 491     // on other platforms), but the second one returns some extra info.
 492     //
 493     wxTreeItemId HitTest(const wxPoint& rPoint)
 494         { int nDummy = 0; return HitTest(rPoint, nDummy); }
 495     wxTreeItemId HitTest( const wxPoint& rPoint
 496                          ,int&           rFlags
 497                         );
 498
 499     //
 500     // Get the bounding rectangle of the item (or of its label only)
 501     //
 502     bool GetBoundingRect( const wxTreeItemId& rItem
 503                          ,wxRect&             rRect
 504                          ,bool                bTextOnly = false
 505                         ) const;
 506
 507     //
 508     // Deprecated
 509     // ----------
 510
 511 #if WXWIN_COMPATIBILITY_2_4
 512     // These methods are deprecated and will be removed in future versions of
 513     // wxWidgets, they're here for compatibility only, don't use them in new
 514     // code (the comments indicate why these methods are now useless and how to
 515     // replace them)
 516     //
 517
 518     //
 519     // Use Expand, Collapse, CollapseAndReset or Toggle
 520     //
 521     wxDEPRECATED( void ExpandItem( const wxTreeItemId& rItem
 522                                   ,int                 nAction
 523                                  ) );
 524
 525     //
 526     // Use AddRoot, PrependItem or AppendItem
 527     //
 528     wxDEPRECATED( wxTreeItemId InsertItem( const wxTreeItemId& pParent
 529                                           ,const wxString&     rsText
 530                                           ,int                 nImage = -1
 531                                           ,int                 nSelImage = -1
 532                                           ,long                lInsertAfter = wxTREE_INSERT_LAST
 533                                          ) );
 534
 535     //
 536     // Use Set/GetImageList and Set/GetStateImageList
 537     //
 538     wxDEPRECATED( wxImageList* GetImageList(int nVal) const );
 539     wxDEPRECATED( void SetImageList(wxImageList* pImageList, int nVal) );
 540
 541     //
 542     // Use Set/GetItemImage directly
 543     //
 544     wxDEPRECATED( int GetItemSelectedImage(const wxTreeItemId& rItem) const );
 545     wxDEPRECATED( void SetItemSelectedImage(const wxTreeItemId& rItem, int nImage) );
 546
 547     //
 548     // For this enumeration function you must pass in a "cookie" parameter
 549     // which is opaque for the application but is necessary for the library
 550     // to make these functions reentrant (i.e. allow more than one
 551     // enumeration on one and the same object simultaneously). Of course,
 552     // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 553     // the same!
 554     //
 555
 556     //
 557     // Get the first child of this item
 558     //
 559     wxDEPRECATED( wxTreeItemId GetFirstChild( const wxTreeItemId& rItem
 560                                              ,long&               rCookie
 561                                             ) const );
 562
 563     //
 564     // Get the next child
 565     //
 566     wxDEPRECATED( wxTreeItemId GetNextChild( const wxTreeItemId& rItem
 567                                             ,long&               rCookie
 568                                            ) const );
 569 #endif // WXWIN_COMPATIBILITY_2_4
 570
 571     //
 572     // Implementation
 573     // --------------
 574     //
 575
 576     virtual MRESULT OS2WindowProc( WXUINT   uMsg
 577                                   ,WXWPARAM wParam
 578                                   ,WXLPARAM lParam
 579                                  );
 580     virtual bool    OS2Command( WXUINT uParam
 581                                ,WXWORD wId
 582                               );
 583 //    virtual bool    OMSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
 584
 585     //
 586     // Override some base class virtuals
 587     //
 588     virtual bool SetBackgroundColour(const wxColour& rColour);
 589     virtual bool SetForegroundColour(const wxColour& rColour);
 590
 591     //
 592     // Get/set the check state for the item (only for wxTR_MULTIPLE)
 593     //
 594     bool IsItemChecked(const wxTreeItemId& rItem) const;
 595     void SetItemCheck( const wxTreeItemId& rItem
 596                       ,bool                bCheck = true
 597                      );
 598
 599 protected:
 600     //
 601     // SetImageList helper
 602     //
 603     void SetAnyImageList( wxImageList* pImageList
 604                          ,int          nWhich
 605                         );
 606
 607     //
 608     // Refresh a single item
 609     //
 610     void RefreshItem(const wxTreeItemId& rItem);
 611
 612     wxImageList*                    m_pImageListNormal; // images for tree elements
 613     wxImageList*                    m_pImageListState;  // special images for app defined states
 614     bool                            m_bOwnsImageListNormal;
 615     bool                            m_bOwnsImageListState;
 616
 617 private:
 618
 619     //
 620     // The common part of all ctors
 621     //
 622     void Init(void);
 623
 624     //
 625     // Helper functions
 626     //
 627     inline bool DoGetItem(wxTreeViewItem* pTvItem) const;
 628     inline void DoSetItem(wxTreeViewItem* pTvItem);
 629
 630     inline void DoExpand( const wxTreeItemId& rItem
 631                          ,int                 nFlag
 632                         );
 633     wxTreeItemId DoInsertItem( const wxTreeItemId& pParent
 634                               ,wxTreeItemId        hInsertAfter
 635                               ,const wxString&     rsText
 636                               ,int                 nImage
 637                               ,int                 nSelectedImage
 638                               ,wxTreeItemData*     pData
 639                              );
 640     int  DoGetItemImageFromData( const wxTreeItemId& rItem
 641                                 ,wxTreeItemIcon      vWhich
 642                                ) const;
 643     void DoSetItemImageFromData( const wxTreeItemId& rItem
 644                                 ,int                 nImage
 645                                 ,wxTreeItemIcon      vWhich
 646                                ) const;
 647     void DoSetItemImages( const wxTreeItemId& rItem
 648                          ,int                 nImage
 649                          ,int                 nImageSel
 650                         );
 651     void DeleteTextCtrl() { };
 652
 653     //
 654     // support for additional item images which we implement using
 655     // wxTreeItemIndirectData technique - see the comments in msw/treectrl.cpp
 656     //
 657     void SetIndirectItemData( const wxTreeItemId&           rItem
 658                              ,class wxTreeItemIndirectData* pData
 659                             );
 660     bool HasIndirectData(const wxTreeItemId& rItem) const;
 661     bool IsDataIndirect(wxTreeItemData* pData) const
 662         { return pData && pData->GetId().m_pItem == 0; }
 663
 664     //
 665     // The hash storing the items attributes (indexed by items ids)
 666     //
 667     wxMapTreeAttr                   m_vAttrs;
 668
 669     //
 670     // true if the hash above is not empty
 671     //
 672     bool                            m_bHasAnyAttr;
 673
 674     //
 675     // Used for dragging
 676     //
 677     wxDragImage*                    m_pDragImage;
 678
 679     // Virtual root item, if wxTR_HIDE_ROOT is set.
 680 //    void* m_pVirtualRoot;
 681
 682     // the starting item for selection with Shift
 683 //    WXHTREEITEM m_htSelStart;
 684 //
 685     friend class wxTreeItemIndirectData;
 686     friend class wxTreeSortHelper;
 687
 688     DECLARE_DYNAMIC_CLASS(wxTreeCtrl)
 689     DECLARE_NO_COPY_CLASS(wxTreeCtrl)
 690 }; // end of CLASS wxTreeCtrl
 691
 692 #endif // wxUSE_TREECTRL
 693
 694 #endif
 695     // _WX_TREECTRL_H_