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