include/wx/gtk/treectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treectrl.h
   3 // Purpose:     wxTreeCtrl class
   4 // Author:      Denis Pershin
   5 // Modified by:
   6 // Created:     08/08/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Denis Pershin
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_TREECTRL_H_
  13 #define _WX_TREECTRL_H_
  14
  15 #ifdef __GNUG__
  16 #pragma interface "treectrl.h"
  17 #endif
  18
  19 #include "wx/textctrl.h"
  20 #include "wx/imaglist.h"
  21
  22 #include <gtk/gtk.h>
  23
  24 // the type for "untyped" data
  25 typedef long wxDataType;
  26
  27 // fwd decl
  28 class  wxImageList;
  29 struct wxTreeViewItem;
  30
  31 // a callback function used for sorting tree items, it should return -1 if the
  32 // first item precedes the second, +1 if the second precedes the first or 0 if
  33 // they're equivalent
  34 class wxTreeItemData;
  35 typedef int (*wxTreeItemCmpFunc)(wxTreeItemData *item1, wxTreeItemData *item2);
  36
  37 // ----------------------------------------------------------------------------
  38 // constants
  39 // ----------------------------------------------------------------------------
  40
  41 // values for the `flags' parameter of wxTreeCtrl::HitTest() which determine
  42 // where exactly the specified point is situated:
  43     // above the client area.
  44 static const int wxTREE_HITTEST_ABOVE            = 0x0001;
  45     // below the client area.
  46 static const int wxTREE_HITTEST_BELOW            = 0x0002;
  47     // in the client area but below the last item.
  48 static const int wxTREE_HITTEST_NOWHERE          = 0x0004;
  49     // on the button associated with an item.
  50 static const int wxTREE_HITTEST_ONITEMBUTTON     = 0x0010;
  51     // on the bitmap associated with an item.
  52 static const int wxTREE_HITTEST_ONITEMICON       = 0x0020;
  53     // in the indentation associated with an item.
  54 static const int wxTREE_HITTEST_ONITEMINDENT     = 0x0040;
  55     // on the label (string) associated with an item.
  56 static const int wxTREE_HITTEST_ONITEMLABEL      = 0x0080;
  57     // in the area to the right of an item.
  58 static const int wxTREE_HITTEST_ONITEMRIGHT      = 0x0100;
  59     // on the state icon for a tree view item that is in a user-defined state.
  60 static const int wxTREE_HITTEST_ONITEMSTATEICON  = 0x0200;
  61     // to the right of the client area.
  62 static const int wxTREE_HITTEST_TOLEFT           = 0x0400;
  63     // to the left of the client area.
  64 static const int wxTREE_HITTEST_TORIGHT          = 0x0800;
  65     // anywhere on the item
  66 static const int wxTREE_HITTEST_ONITEM  = wxTREE_HITTEST_ONITEMICON |
  67                                           wxTREE_HITTEST_ONITEMLABEL |
  68                                           wxTREE_HITTEST_ONITEMSTATEICON;
  69
  70 // NB: all the following flags are for compatbility only and will be removed in
  71 //     next versions
  72
  73 // flags for deprecated `Expand(int action)'
  74 enum
  75 {
  76     wxTREE_EXPAND_EXPAND,
  77     wxTREE_EXPAND_COLLAPSE,
  78     wxTREE_EXPAND_COLLAPSE_RESET,
  79     wxTREE_EXPAND_TOGGLE
  80 };
  81
  82 // flags for deprecated InsertItem() variant
  83 #define wxTREE_INSERT_FIRST 0xFFFF0001
  84 #define wxTREE_INSERT_LAST  0xFFFF0002
  85
  86 // ----------------------------------------------------------------------------
  87 // wxTreeItemId identifies an element of the tree. In this implementation, it's
  88 // just a trivial wrapper around GTK GtkTreeItem *. It's opaque for the
  89 // application.
  90 // ----------------------------------------------------------------------------
  91 class WXDLLEXPORT wxTreeItemId {
  92 public:
  93   // ctors
  94   wxTreeItemId() { m_itemId = NULL; }
  95
  96       // default copy ctor/assignment operator are ok for us
  97
  98   // accessors
  99       // is this a valid tree item?
 100   bool IsOk() const { return m_itemId != NULL; }
 101
 102   // conversion to/from either real (system-dependent) tree item id or
 103   // to "long" which used to be the type for tree item ids in previous
 104   // versions of wxWindows
 105
 106   // for wxTreeCtrl usage only
 107   wxTreeItemId(GtkTreeItem *itemId) { m_itemId = itemId; }
 108   operator GtkTreeItem *() const { return m_itemId; }
 109   void operator =(GtkTreeItem *item) { m_itemId = item; }
 110
 111 protected:
 112   GtkTreeItem *m_itemId;
 113 };
 114
 115 // ----------------------------------------------------------------------------
 116 // wxTreeItemData is some (arbitrary) user class associated with some item. The
 117 // main advantage of having this class (compared to old untyped interface) is
 118 // that wxTreeItemData's are destroyed automatically by the tree and, as this
 119 // class has virtual dtor, it means that the memory will be automatically
 120 // freed. OTOH, we don't just use wxObject instead of wxTreeItemData because
 121 // the size of this class is critical: in any real application, each tree leaf
 122 // will have wxTreeItemData associated with it and number of leaves may be
 123 // quite big.
 124 //
 125 // Because the objects of this class are deleted by the tree, they should
 126 // always be allocated on the heap!
 127 // ----------------------------------------------------------------------------
 128 class WXDLLEXPORT wxTreeItemData : private wxTreeItemId {
 129 public:
 130     // default ctor/copy ctor/assignment operator are ok
 131
 132     // dtor is virtual and all the items are deleted by the tree control when
 133     // it's deleted, so you normally don't have to care about freeing memory
 134     // allocated in your wxTreeItemData-derived class
 135     virtual ~wxTreeItemData() { }
 136
 137     // accessors: set/get the item associated with this node
 138     void SetId(const wxTreeItemId& id) { m_itemId = id; }
 139     const wxTreeItemId& GetId() const { return (wxTreeItemId&) m_itemId; }
 140 };
 141
 142 class WXDLLEXPORT wxTreeCtrl: public wxControl {
 143 public:
 144   // creation
 145   // --------
 146   wxTreeCtrl() { Init(); }
 147
 148   wxTreeCtrl(wxWindow *parent, wxWindowID id = -1,
 149              const wxPoint& pos = wxDefaultPosition,
 150              const wxSize& size = wxDefaultSize,
 151              long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
 152              const wxValidator& validator = wxDefaultValidator,
 153              const wxString& name = "wxTreeCtrl") {
 154       Create(parent, id, pos, size, style, validator, name);
 155   }
 156
 157   virtual ~wxTreeCtrl();
 158
 159     bool Create(wxWindow *parent, wxWindowID id = -1,
 160                 const wxPoint& pos = wxDefaultPosition,
 161                 const wxSize& size = wxDefaultSize,
 162                 long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
 163                 const wxValidator& validator = wxDefaultValidator,
 164                 const wxString& name = "wxTreeCtrl");
 165
 166     // accessors
 167     // ---------
 168
 169         // get the total number of items in the control
 170     size_t GetCount() const;
 171
 172         // indent is the number of pixels the children are indented relative to
 173         // the parents position. SetIndent() also redraws the control
 174         // immediately.
 175     unsigned int GetIndent() const;
 176     void SetIndent(unsigned int indent);
 177
 178         // image list: these functions allow to associate an image list with
 179         // the control and retrieve it. Note that the control does _not_ delete
 180         // the associated image list when it's deleted in order to allow image
 181         // lists to be shared between different controls.
 182         //
 183         // The normal image list is for the icons which correspond to the
 184         // normal tree item state (whether it is selected or not).
 185         // Additionally, the application might choose to show a state icon
 186         // which corresponds to an app-defined item state (for example,
 187         // checked/unchecked) which are taken from the state image list.
 188     wxImageList *GetImageList() const;
 189     wxImageList *GetStateImageList() const;
 190
 191     void SetImageList(wxImageList *imageList);
 192     void SetStateImageList(wxImageList *imageList);
 193
 194     // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
 195     // member functions of wxTreeItem because they must know the tree the item
 196     // belongs to for Windows implementation and storing the pointer to
 197     // wxTreeCtrl in each wxTreeItem is just too much waste.
 198
 199     // accessors
 200     // ---------
 201
 202         // retrieve items label
 203     wxString GetItemText(const wxTreeItemId& item) const;
 204         // get the normal item image
 205     int GetItemImage(const wxTreeItemId& item) const;
 206         // get the selected item image
 207     int GetItemSelectedImage(const wxTreeItemId& item) const;
 208         // get the data associated with the item
 209     wxTreeItemData *GetItemData(const wxTreeItemId& item) const;
 210
 211     // modifiers
 212     // ---------
 213
 214         // set items label
 215     void SetItemText(const wxTreeItemId& item, const wxString& text);
 216         // set the normal item image
 217     void SetItemImage(const wxTreeItemId& item, int image);
 218         // set the selected item image
 219     void SetItemSelectedImage(const wxTreeItemId& item, int image);
 220         // associate some data with the item
 221     void SetItemData(const wxTreeItemId& item, wxTreeItemData *data);
 222
 223     // item status inquiries
 224     // ---------------------
 225
 226         // is the item visible (it might be outside the view or not expanded)?
 227     bool IsVisible(const wxTreeItemId& item) const;
 228         // does the item has any children?
 229     bool ItemHasChildren(const wxTreeItemId& item) const;
 230         // is the item expanded (only makes sense if HasChildren())?
 231     bool IsExpanded(const wxTreeItemId& item) const;
 232         // is this item currently selected (the same as has focus)?
 233     bool IsSelected(const wxTreeItemId& item) const;
 234
 235     // number of children
 236     // ------------------
 237
 238         // if 'recursively' is FALSE, only immediate children count, otherwise
 239         // the returned number is the number of all items in this branch
 240     size_t GetChildrenCount(const wxTreeItemId& item, bool recursively = TRUE);
 241
 242     // navigation
 243     // ----------
 244
 245     // wxTreeItemId.IsOk() will return FALSE if there is no such item
 246
 247         // get the root tree item
 248     wxTreeItemId GetRootItem() const;
 249
 250         // get the item currently selected (may return NULL if no selection)
 251     wxTreeItemId GetSelection() const;
 252
 253         // get the parent of this item (may return NULL if root)
 254     wxTreeItemId GetParent(const wxTreeItemId& item) const;
 255
 256         // for this enumeration function you must pass in a "cookie" parameter
 257         // which is opaque for the application but is necessary for the library
 258         // to make these functions reentrant (i.e. allow more than one
 259         // enumeration on one and the same object simultaneously). Of course,
 260         // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 261         // the same!
 262
 263         // get the first child of this item
 264     wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& cookie) const;
 265         // get the next child (after GetFirstChild or GetNextChild)
 266     wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const;
 267         // get the last child of this item - this method doesn't use cookies
 268     wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 269
 270         // get the next sibling of this item
 271     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 272         // get the previous sibling
 273     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 274
 275         // get first visible item
 276     wxTreeItemId GetFirstVisibleItem() const;
 277         // get the next visible item: item must be visible itself!
 278         // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
 279     wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 280         // get the previous visible item: item must be visible itself!
 281     wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 282
 283     // operations
 284     // ----------
 285
 286         // add the root node to the tree
 287     wxTreeItemId AddRoot(const wxString& text,
 288                          int image = -1, int selectedImage = -1,
 289                          wxTreeItemData *data = NULL);
 290
 291         // insert a new item in as the first child of the parent
 292     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 293                              const wxString& text,
 294                              int image = -1, int selectedImage = -1,
 295                              wxTreeItemData *data = NULL);
 296
 297         // insert a new item after a given one
 298     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 299                             const wxTreeItemId& idPrevious,
 300                             const wxString& text,
 301                             int image = -1, int selectedImage = -1,
 302                             wxTreeItemData *data = NULL);
 303
 304         // insert a new item in as the last child of the parent
 305     wxTreeItemId AppendItem(const wxTreeItemId& parent,
 306                             const wxString& text,
 307                             int image = -1, int selectedImage = -1,
 308                             wxTreeItemData *data = NULL);
 309
 310         // delete this item and associated data if any
 311     void Delete(const wxTreeItemId& item);
 312         // delete all items from the tree
 313     void DeleteAllItems();
 314
 315         // expand this item
 316     void Expand(const wxTreeItemId& item);
 317         // collapse the item without removing its children
 318     void Collapse(const wxTreeItemId& item);
 319         // collapse the item and remove all children
 320     void CollapseAndReset(const wxTreeItemId& item);
 321         // toggles the current state
 322     void Toggle(const wxTreeItemId& item);
 323
 324         // remove the selection from currently selected item (if any)
 325     void Unselect();
 326         // select this item
 327     void SelectItem(const wxTreeItemId& item);
 328         // make sure this item is visible (expanding the parent item and/or
 329         // scrolling to this item if necessary)
 330     void EnsureVisible(const wxTreeItemId& item);
 331         // scroll to this item (but don't expand its parent)
 332     void ScrollTo(const wxTreeItemId& item);
 333
 334         // start editing the item label: this (temporarily) replaces the item
 335         // with a one line edit control. The item will be selected if it hadn't
 336         // been before. textCtrlClass parameter allows you to create an edit
 337         // control of arbitrary user-defined class deriving from wxTextCtrl.
 338     wxTextCtrl* EditLabel(const wxTreeItemId& item,
 339                           wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl));
 340         // returns the same pointer as StartEdit() if the item is being edited,
 341         // NULL otherwise (it's assumed that no more than one item may be
 342         // edited simultaneously)
 343     wxTextCtrl* GetEditControl() const;
 344         // end editing and accept or discard the changes to item label
 345     void EndEditLabel(const wxTreeItemId& item, bool discardChanges = FALSE);
 346
 347         // sort the children of this item using the specified callback function
 348         // (it should return -1, 0 or +1 as usual), if it's not specified
 349         // alphabetical comparaison is performed.
 350         //
 351         // NB: this function is not reentrant!
 352     void SortChildren(const wxTreeItemId& item,
 353                       wxTreeItemCmpFunc *cmpFunction = NULL);
 354
 355     // deprecated
 356     // ----------
 357
 358     // these methods are deprecated and will be removed in future versions of
 359     // wxWindows, they're here for compatibility only, don't use them in new
 360     // code (the comments indicate why these methods are now useless and how to
 361     // replace them)
 362
 363         // use Expand, Collapse, CollapseAndReset or Toggle
 364     void ExpandItem(const wxTreeItemId& item, int action);
 365
 366         // use AddRoot, PrependItem or AppendItem
 367     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 368                             const wxString& text,
 369                             int image = -1, int selImage = -1,
 370                             long insertAfter = wxTREE_INSERT_LAST);
 371
 372         // use Set/GetImageList and Set/GetStateImageList
 373     wxImageList *GetImageList(int) const
 374         { return GetImageList(); }
 375     void SetImageList(wxImageList *imageList, int)
 376         { SetImageList(imageList); }
 377
 378   void SendExpanding(const wxTreeItemId& item);
 379   void SendExpanded(const wxTreeItemId& item);
 380   void SendCollapsing(const wxTreeItemId& item);
 381   void SendCollapsed(const wxTreeItemId& item);
 382   void SendSelChanging(const wxTreeItemId& item);
 383   void SendSelChanged(const wxTreeItemId& item);
 384 protected:
 385   wxTreeItemId m_editItem;
 386   GtkTree *m_tree;
 387   GtkTreeItem *m_anchor;
 388   wxTextCtrl*  m_textCtrl;
 389   wxImageList* m_imageListNormal;
 390   wxImageList* m_imageListState;
 391
 392   long m_curitemId;
 393
 394   void SendMessage(wxEventType command, const wxTreeItemId& item);
 395 //  GtkTreeItem *findGtkTreeItem(wxTreeCtrlId &id) const;
 396
 397     // the common part of all ctors
 398   void Init();
 399       // insert a new item in as the last child of the parent
 400   wxTreeItemId p_InsertItem(GtkTreeItem *p,
 401                           const wxString& text,
 402                           int image, int selectedImage,
 403                           wxTreeItemData *data);
 404
 405
 406   DECLARE_DYNAMIC_CLASS(wxTreeCtrl)
 407 };
 408
 409 #endif
 410     // _WX_TREECTRL_H_