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