include/wx/os2/treectrl.h

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