Commit | Line | Data |
---|---|---|
4540e33b DP |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: treectrl.h | |
1c3d4180 | 3 | // Purpose: wxTreeCtrl class |
4540e33b | 4 | // Author: Denis Pershin |
1c3d4180 | 5 | // Modified by: |
4540e33b | 6 | // Created: 08/08/98 |
1c3d4180 DP |
7 | // RCS-ID: $Id$ |
8 | // Copyright: (c) Denis Pershin | |
4832f7c0 | 9 | // Licence: wxWindows license |
4540e33b | 10 | ///////////////////////////////////////////////////////////////////////////// |
f4e325b3 | 11 | |
1c3d4180 DP |
12 | #ifndef _WX_TREECTRL_H_ |
13 | #define _WX_TREECTRL_H_ | |
f4e325b3 DP |
14 | |
15 | #ifdef __GNUG__ | |
16 | #pragma interface "treectrl.h" | |
17 | #endif | |
18 | ||
1c3d4180 | 19 | #include "wx/textctrl.h" |
f4e325b3 | 20 | #include "wx/imaglist.h" |
f4e325b3 DP |
21 | |
22 | #include <gtk/gtk.h> | |
23 | ||
e21a5048 DP |
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 | { | |
f4e325b3 DP |
76 | wxTREE_EXPAND_EXPAND, |
77 | wxTREE_EXPAND_COLLAPSE, | |
78 | wxTREE_EXPAND_COLLAPSE_RESET, | |
79 | wxTREE_EXPAND_TOGGLE | |
80 | }; | |
81 | ||
e21a5048 | 82 | // flags for deprecated InsertItem() variant |
1c3d4180 DP |
83 | #define wxTREE_INSERT_FIRST 0xFFFF0001 |
84 | #define wxTREE_INSERT_LAST 0xFFFF0002 | |
f4e325b3 | 85 | |
e21a5048 DP |
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 { | |
f4e325b3 | 92 | public: |
e21a5048 DP |
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; } | |
3efb01df | 109 | void operator =(GtkTreeItem *item) { m_itemId = item; } |
e21a5048 DP |
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 | // ---------------------------------------------------------------------------- | |
3efb01df | 128 | class WXDLLEXPORT wxTreeItemData : private wxTreeItemId { |
e21a5048 | 129 | public: |
3efb01df | 130 | // default ctor/copy ctor/assignment operator are ok |
e21a5048 | 131 | |
3efb01df DP |
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() { } | |
e21a5048 | 136 | |
3efb01df DP |
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; } | |
f4e325b3 DP |
140 | }; |
141 | ||
1c3d4180 | 142 | class WXDLLEXPORT wxTreeCtrl: public wxControl { |
f4e325b3 | 143 | public: |
1c3d4180 DP |
144 | // creation |
145 | // -------- | |
e21a5048 DP |
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") { | |
1c3d4180 DP |
154 | Create(parent, id, pos, size, style, validator, name); |
155 | } | |
f4e325b3 | 156 | |
e21a5048 DP |
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 | ||
4832f7c0 VZ |
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 | ||
e21a5048 DP |
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; | |
978f38c2 | 265 | // get the next child (after GetFirstChild or GetNextChild) |
e21a5048 | 266 | wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const; |
978f38c2 VZ |
267 | // get the last child of this item - this method doesn't use cookies |
268 | wxTreeItemId GetLastChild(const wxTreeItemId& item) const; | |
e21a5048 DP |
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 | ||
1c3d4180 DP |
283 | // operations |
284 | // ---------- | |
e21a5048 DP |
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); | |
1c3d4180 | 384 | protected: |
e1dc4cc6 | 385 | wxTreeItemId m_editItem; |
1c3d4180 DP |
386 | GtkTree *m_tree; |
387 | GtkTreeItem *m_anchor; | |
388 | wxTextCtrl* m_textCtrl; | |
389 | wxImageList* m_imageListNormal; | |
390 | wxImageList* m_imageListState; | |
f4e325b3 | 391 | |
1c3d4180 | 392 | long m_curitemId; |
f4e325b3 | 393 | |
e895ec45 | 394 | void SendMessage(wxEventType command, const wxTreeItemId& item); |
e21a5048 DP |
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 | ||
f4e325b3 | 405 | |
f4e325b3 DP |
406 | DECLARE_DYNAMIC_CLASS(wxTreeCtrl) |
407 | }; | |
408 | ||
f4e325b3 | 409 | #endif |
1c3d4180 | 410 | // _WX_TREECTRL_H_ |