]> git.saurik.com Git - wxWidgets.git/blob - include/wx/gtk1/treectrl.h
remove unused variable assignment, closes #14928
[wxWidgets.git] / 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_