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