include/wx/treectrl.h

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