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