include/wx/gtk1/treectrl.h

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