include/wx/palmos/treectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/palmos/treectrl.h
   3 // Purpose:     wxTreeCtrl class
   4 // Author:      William Osborne - minimal working wxPalmOS port
   5 // Modified by:
   6 // Created:     10/13/04
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) William Osborne
   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 // fwd decl
  27 class  WXDLLIMPEXP_CORE wxImageList;
  28 class  WXDLLIMPEXP_CORE wxDragImage;
  29 struct WXDLLIMPEXP_FWD_CORE wxTreeViewItem;
  30
  31 // hash storing attributes for our items
  32 WX_DECLARE_EXPORTED_VOIDPTR_HASH_MAP(wxTreeItemAttr *, wxMapTreeAttr);
  33
  34 // ----------------------------------------------------------------------------
  35 // wxTreeCtrl
  36 // ----------------------------------------------------------------------------
  37
  38 class WXDLLIMPEXP_CORE wxTreeCtrl : public wxControl
  39 {
  40 public:
  41     // creation
  42     // --------
  43     wxTreeCtrl() { Init(); }
  44
  45     wxTreeCtrl(wxWindow *parent, wxWindowID id = wxID_ANY,
  46                const wxPoint& pos = wxDefaultPosition,
  47                const wxSize& size = wxDefaultSize,
  48                long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
  49                const wxValidator& validator = wxDefaultValidator,
  50                const wxString& name = wxTreeCtrlNameStr)
  51     {
  52         Create(parent, id, pos, size, style, validator, name);
  53     }
  54
  55     virtual ~wxTreeCtrl();
  56
  57     bool Create(wxWindow *parent, wxWindowID id = wxID_ANY,
  58                 const wxPoint& pos = wxDefaultPosition,
  59                 const wxSize& size = wxDefaultSize,
  60                 long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
  61                 const wxValidator& validator = wxDefaultValidator,
  62                 const wxString& name = wxTreeCtrlNameStr);
  63
  64     // accessors
  65     // ---------
  66
  67         // get the total number of items in the control
  68     virtual unsigned int GetCount() const;
  69
  70         // indent is the number of pixels the children are indented relative to
  71         // the parents position. SetIndent() also redraws the control
  72         // immediately.
  73     unsigned int GetIndent() const;
  74     void SetIndent(unsigned int indent);
  75
  76     // spacing is the number of pixels between the start and the Text
  77     unsigned int GetSpacing() const { return 18; } // return wxGTK default
  78     void SetSpacing(unsigned int WXUNUSED(spacing)) { }
  79
  80         // image list: these functions allow to associate an image list with
  81         // the control and retrieve it. Note that the control does _not_ delete
  82         // the associated image list when it's deleted in order to allow image
  83         // lists to be shared between different controls.
  84         //
  85         // The normal image list is for the icons which correspond to the
  86         // normal tree item state (whether it is selected or not).
  87         // Additionally, the application might choose to show a state icon
  88         // which corresponds to an app-defined item state (for example,
  89         // checked/unchecked) which are taken from the state image list.
  90     wxImageList *GetImageList() const;
  91     wxImageList *GetStateImageList() const;
  92
  93     void SetImageList(wxImageList *imageList);
  94     void SetStateImageList(wxImageList *imageList);
  95     void AssignImageList(wxImageList *imageList);
  96     void AssignStateImageList(wxImageList *imageList);
  97
  98     // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
  99     // member functions of wxTreeItem because they must know the tree the item
 100     // belongs to for Windows implementation and storing the pointer to
 101     // wxTreeCtrl in each wxTreeItem is just too much waste.
 102
 103     // accessors
 104     // ---------
 105
 106         // retrieve items label
 107     wxString GetItemText(const wxTreeItemId& item) const;
 108         // get one of the images associated with the item (normal by default)
 109     int GetItemImage(const wxTreeItemId& item,
 110                      wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 111         // get the data associated with the item
 112     wxTreeItemData *GetItemData(const wxTreeItemId& item) const;
 113
 114         // get the item's text colour
 115     wxColour GetItemTextColour(const wxTreeItemId& item) const;
 116
 117         // get the item's background colour
 118     wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
 119
 120         // get the item's font
 121     wxFont GetItemFont(const wxTreeItemId& item) const;
 122
 123     // modifiers
 124     // ---------
 125
 126         // set items label
 127     void SetItemText(const wxTreeItemId& item, const wxString& text);
 128         // get one of the images associated with the item (normal by default)
 129     void SetItemImage(const wxTreeItemId& item, int image,
 130                       wxTreeItemIcon which = wxTreeItemIcon_Normal);
 131         // associate some data with the item
 132     void SetItemData(const wxTreeItemId& item, wxTreeItemData *data);
 133
 134         // force appearance of [+] button near the item. This is useful to
 135         // allow the user to expand the items which don't have any children now
 136         // - but instead add them only when needed, thus minimizing memory
 137         // usage and loading time.
 138     void SetItemHasChildren(const wxTreeItemId& item, bool has = true);
 139
 140         // the item will be shown in bold
 141     void SetItemBold(const wxTreeItemId& item, bool bold = true);
 142
 143         // the item will be shown with a drop highlight
 144     void SetItemDropHighlight(const wxTreeItemId& item, bool highlight = true);
 145
 146         // set the items text colour
 147     void SetItemTextColour(const wxTreeItemId& item, const wxColour& col);
 148
 149         // set the items background colour
 150     void SetItemBackgroundColour(const wxTreeItemId& item, const wxColour& col);
 151
 152         // set the items font (should be of the same height for all items)
 153     void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 154
 155     // item status inquiries
 156     // ---------------------
 157
 158         // is the item visible (it might be outside the view or not expanded)?
 159     bool IsVisible(const wxTreeItemId& item) const;
 160         // does the item has any children?
 161     bool ItemHasChildren(const wxTreeItemId& item) const;
 162         // is the item expanded (only makes sense if HasChildren())?
 163     bool IsExpanded(const wxTreeItemId& item) const;
 164         // is this item currently selected (the same as has focus)?
 165     bool IsSelected(const wxTreeItemId& item) const;
 166         // is item text in bold font?
 167     bool IsBold(const wxTreeItemId& item) const;
 168
 169     // number of children
 170     // ------------------
 171
 172         // if 'recursively' is false, only immediate children count, otherwise
 173         // the returned number is the number of all items in this branch
 174     size_t GetChildrenCount(const wxTreeItemId& item,
 175                             bool recursively = true) const;
 176
 177     // navigation
 178     // ----------
 179
 180     // wxTreeItemId.IsOk() will return false if there is no such item
 181
 182         // get the root tree item
 183     wxTreeItemId GetRootItem() const;
 184
 185         // get the item currently selected (may return NULL if no selection)
 186     wxTreeItemId GetSelection() const;
 187
 188         // get the items currently selected, return the number of such item
 189         //
 190         // NB: this operation is expensive and can take a long time for a
 191         //     control with a lot of items (~ O(number of items)).
 192     size_t GetSelections(wxArrayTreeItemIds& selections) const;
 193
 194         // get the parent of this item (may return NULL if root)
 195     wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
 196
 197         // for this enumeration function you must pass in a "cookie" parameter
 198         // which is opaque for the application but is necessary for the library
 199         // to make these functions reentrant (i.e. allow more than one
 200         // enumeration on one and the same object simultaneously). Of course,
 201         // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 202         // the same!
 203
 204         // get the first child of this item
 205     wxTreeItemId GetFirstChild(const wxTreeItemId& item,
 206                                wxTreeItemIdValue& cookie) const;
 207         // get the next child
 208     wxTreeItemId GetNextChild(const wxTreeItemId& item,
 209                               wxTreeItemIdValue& cookie) const;
 210         // get the last child of this item - this method doesn't use cookies
 211     wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 212
 213         // get the next sibling of this item
 214     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 215         // get the previous sibling
 216     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 217
 218         // get first visible item
 219     wxTreeItemId GetFirstVisibleItem() const;
 220         // get the next visible item: item must be visible itself!
 221         // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
 222     wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 223         // get the previous visible item: item must be visible itself!
 224     wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 225
 226     // operations
 227     // ----------
 228
 229         // add the root node to the tree
 230     wxTreeItemId AddRoot(const wxString& text,
 231                          int image = -1, int selectedImage = -1,
 232                          wxTreeItemData *data = NULL);
 233
 234         // insert a new item in as the first child of the parent
 235     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 236                              const wxString& text,
 237                              int image = -1, int selectedImage = -1,
 238                              wxTreeItemData *data = NULL);
 239
 240         // insert a new item after a given one
 241     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 242                             const wxTreeItemId& idPrevious,
 243                             const wxString& text,
 244                             int image = -1, int selectedImage = -1,
 245                             wxTreeItemData *data = NULL);
 246
 247         // insert a new item before the one with the given index
 248     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 249                             size_t index,
 250                             const wxString& text,
 251                             int image = -1, int selectedImage = -1,
 252                             wxTreeItemData *data = NULL);
 253
 254         // insert a new item in as the last child of the parent
 255     wxTreeItemId AppendItem(const wxTreeItemId& parent,
 256                             const wxString& text,
 257                             int image = -1, int selectedImage = -1,
 258                             wxTreeItemData *data = NULL);
 259
 260         // delete this item and associated data if any
 261     void Delete(const wxTreeItemId& item);
 262         // delete all children (but don't delete the item itself)
 263         // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 264     void DeleteChildren(const wxTreeItemId& item);
 265         // delete all items from the tree
 266         // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 267     void DeleteAllItems();
 268
 269         // expand this item
 270     void Expand(const wxTreeItemId& item);
 271         // collapse the item without removing its children
 272     void Collapse(const wxTreeItemId& item);
 273         // collapse the item and remove all children
 274     void CollapseAndReset(const wxTreeItemId& item);
 275         // toggles the current state
 276     void Toggle(const wxTreeItemId& item);
 277
 278         // remove the selection from currently selected item (if any)
 279     void Unselect();
 280         // unselect all items (only makes sense for multiple selection control)
 281     void UnselectAll();
 282         // select this item
 283     void SelectItem(const wxTreeItemId& item, bool select = true);
 284         // unselect this item
 285     void UnselectItem(const wxTreeItemId& item);
 286         // toggle item selection
 287     void ToggleItemSelection(const wxTreeItemId& item);
 288
 289         // make sure this item is visible (expanding the parent item and/or
 290         // scrolling to this item if necessary)
 291     void EnsureVisible(const wxTreeItemId& item);
 292         // scroll to this item (but don't expand its parent)
 293     void ScrollTo(const wxTreeItemId& item);
 294
 295         // start editing the item label: this (temporarily) replaces the item
 296         // with a one line edit control. The item will be selected if it hadn't
 297         // been before. textCtrlClass parameter allows you to create an edit
 298         // control of arbitrary user-defined class deriving from wxTextCtrl.
 299     wxTextCtrl* EditLabel(const wxTreeItemId& item,
 300                           wxClassInfo* textCtrlClass = wxCLASSINFO(wxTextCtrl));
 301         // returns the same pointer as StartEdit() if the item is being edited,
 302         // NULL otherwise (it's assumed that no more than one item may be
 303         // edited simultaneously)
 304     wxTextCtrl* GetEditControl() const;
 305         // end editing and accept or discard the changes to item label
 306     void EndEditLabel(const wxTreeItemId& item, bool discardChanges = false);
 307
 308     // sorting
 309         // this function is called to compare 2 items and should return -1, 0
 310         // or +1 if the first item is less than, equal to or greater than the
 311         // second one. The base class version performs alphabetic comparaison
 312         // of item labels (GetText)
 313     virtual int OnCompareItems(const wxTreeItemId& item1,
 314                                const wxTreeItemId& item2);
 315         // sort the children of this item using OnCompareItems
 316         //
 317         // NB: this function is not reentrant and not MT-safe (FIXME)!
 318     void SortChildren(const wxTreeItemId& item);
 319
 320     // helpers
 321     // -------
 322
 323         // determine to which item (if any) belongs the given point (the
 324         // coordinates specified are relative to the client area of tree ctrl)
 325         // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx
 326         // constants.
 327         //
 328         // The first function is more portable (because easier to implement
 329         // on other platforms), but the second one returns some extra info.
 330     wxTreeItemId HitTest(const wxPoint& point)
 331         { int dummy; return HitTest(point, dummy); }
 332     wxTreeItemId HitTest(const wxPoint& point, int& flags);
 333
 334         // get the bounding rectangle of the item (or of its label only)
 335     bool GetBoundingRect(const wxTreeItemId& item,
 336                          wxRect& rect,
 337                          bool textOnly = false) const;
 338
 339     // implementation
 340     // --------------
 341
 342     virtual bool ShouldInheritColours() const { return false; }
 343
 344     virtual wxVisualAttributes GetDefaultAttributes() const
 345     {
 346         return GetClassDefaultAttributes(GetWindowVariant());
 347     }
 348
 349     static wxVisualAttributes
 350     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 351
 352     // override some base class virtuals
 353     virtual bool SetBackgroundColour(const wxColour &colour);
 354     virtual bool SetForegroundColour(const wxColour &colour);
 355
 356     // get/set the check state for the item (only for wxTR_MULTIPLE)
 357     bool IsItemChecked(const wxTreeItemId& item) const;
 358     void SetItemCheck(const wxTreeItemId& item, bool check = true);
 359
 360     // set/get the item state.image (state == -1 means cycle to the next one)
 361     void SetState(const wxTreeItemId& node, int state);
 362     int GetState(const wxTreeItemId& node);
 363
 364 protected:
 365     // SetImageList helper
 366     void SetAnyImageList(wxImageList *imageList, int which);
 367
 368     // refresh a single item
 369     void RefreshItem(const wxTreeItemId& item);
 370
 371     wxTextCtrl  *m_textCtrl;        // used while editing the item label
 372     wxImageList *m_imageListNormal, // images for tree elements
 373                 *m_imageListState;  // special images for app defined states
 374     bool         m_ownsImageListNormal, m_ownsImageListState;
 375
 376 private:
 377     // the common part of all ctors
 378     void Init();
 379
 380     // helper functions
 381     inline bool DoGetItem(wxTreeViewItem *tvItem) const;
 382     inline void DoSetItem(wxTreeViewItem *tvItem);
 383
 384     inline void DoExpand(const wxTreeItemId& item, int flag);
 385
 386     wxTreeItemId DoInsertItem(const wxTreeItemId& parent,
 387                               wxTreeItemId hInsertAfter,
 388                               const wxString& text,
 389                               int image, int selectedImage,
 390                               wxTreeItemData *data);
 391
 392     int DoGetItemImageFromData(const wxTreeItemId& item,
 393                                wxTreeItemIcon which) const;
 394     void DoSetItemImageFromData(const wxTreeItemId& item,
 395                                 int image,
 396                                 wxTreeItemIcon which) const;
 397     void DoSetItemImages(const wxTreeItemId& item, int image, int imageSel);
 398
 399     void DeleteTextCtrl();
 400
 401     // support for additional item images which we implement using
 402     // wxTreeItemIndirectData technique
 403     void SetIndirectItemData(const wxTreeItemId& item,
 404                              class wxTreeItemIndirectData *data);
 405     bool HasIndirectData(const wxTreeItemId& item) const;
 406     bool IsDataIndirect(wxTreeItemData *data) const
 407         { return data && data->GetId().m_pItem == 0; }
 408
 409     // the hash storing the items attributes (indexed by item ids)
 410     wxMapTreeAttr m_attrs;
 411
 412     // true if the hash above is not empty
 413     bool m_hasAnyAttr;
 414
 415     // used for dragging
 416     wxDragImage *m_dragImage;
 417
 418     // Virtual root item, if wxTR_HIDE_ROOT is set.
 419     void* m_pVirtualRoot;
 420
 421     // the starting item for selection with Shift
 422     wxTreeItemId m_htSelStart;
 423
 424     friend class wxTreeItemIndirectData;
 425     friend class wxTreeSortHelper;
 426
 427     DECLARE_DYNAMIC_CLASS(wxTreeCtrl)
 428     wxDECLARE_NO_COPY_CLASS(wxTreeCtrl);
 429 };
 430
 431 #endif // wxUSE_TREECTRL
 432
 433 #endif // _WX_TREECTRL_H_