Commit | Line | Data |
---|---|---|
4540e33b | 1 | ///////////////////////////////////////////////////////////////////////////// |
8ef94bfc | 2 | // Name: wx/gtk1/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 | |
65571936 | 9 | // Licence: wxWindows licence |
4540e33b | 10 | ///////////////////////////////////////////////////////////////////////////// |
f4e325b3 | 11 | |
1c3d4180 DP |
12 | #ifndef _WX_TREECTRL_H_ |
13 | #define _WX_TREECTRL_H_ | |
f4e325b3 | 14 | |
1c3d4180 | 15 | #include "wx/textctrl.h" |
f4e325b3 | 16 | #include "wx/imaglist.h" |
f4e325b3 DP |
17 | |
18 | #include <gtk/gtk.h> | |
19 | ||
e21a5048 DP |
20 | // the type for "untyped" data |
21 | typedef long wxDataType; | |
22 | ||
23 | // fwd decl | |
20123d49 | 24 | class WXDLLIMPEXP_CORE wxImageList; |
e21a5048 DP |
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 | |
b5dbe15d | 30 | class WXDLLIMPEXP_FWD_CORE wxTreeItemData; |
e21a5048 DP |
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 | ||
989ab1e5 WS |
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 | |
f4e325b3 | 73 | |
e21a5048 DP |
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 | // ---------------------------------------------------------------------------- | |
53a2db12 | 79 | class WXDLLIMPEXP_CORE wxTreeItemId { |
f4e325b3 | 80 | public: |
e21a5048 DP |
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 | |
77ffb593 | 92 | // versions of wxWidgets |
e21a5048 DP |
93 | |
94 | // for wxTreeCtrl usage only | |
95 | wxTreeItemId(GtkTreeItem *itemId) { m_itemId = itemId; } | |
96 | operator GtkTreeItem *() const { return m_itemId; } | |
3efb01df | 97 | void operator =(GtkTreeItem *item) { m_itemId = item; } |
e21a5048 DP |
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 | // ---------------------------------------------------------------------------- | |
53a2db12 | 116 | class WXDLLIMPEXP_CORE wxTreeItemData : private wxTreeItemId { |
e21a5048 | 117 | public: |
3efb01df | 118 | // default ctor/copy ctor/assignment operator are ok |
e21a5048 | 119 | |
3efb01df DP |
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() { } | |
e21a5048 | 124 | |
3efb01df DP |
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; } | |
f4e325b3 DP |
128 | }; |
129 | ||
53a2db12 | 130 | class WXDLLIMPEXP_CORE wxTreeCtrl: public wxControl { |
f4e325b3 | 131 | public: |
1c3d4180 DP |
132 | // creation |
133 | // -------- | |
e21a5048 DP |
134 | wxTreeCtrl() { Init(); } |
135 | ||
e2effeb9 | 136 | wxTreeCtrl(wxWindow *parent, wxWindowID id = wxID_ANY, |
e21a5048 DP |
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") { | |
1c3d4180 DP |
142 | Create(parent, id, pos, size, style, validator, name); |
143 | } | |
f4e325b3 | 144 | |
e21a5048 DP |
145 | virtual ~wxTreeCtrl(); |
146 | ||
e2effeb9 | 147 | bool Create(wxWindow *parent, wxWindowID id = wxID_ANY, |
e21a5048 DP |
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 | |
027d45e8 | 158 | virtual unsigned int GetCount() const; |
e21a5048 DP |
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; | |
e21a5048 DP |
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); | |
e21a5048 DP |
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 | ||
4832f7c0 VZ |
219 | // number of children |
220 | // ------------------ | |
221 | ||
e2effeb9 | 222 | // if 'recursively' is false, only immediate children count, otherwise |
4832f7c0 | 223 | // the returned number is the number of all items in this branch |
e2effeb9 | 224 | size_t GetChildrenCount(const wxTreeItemId& item, bool recursively = true); |
4832f7c0 | 225 | |
e21a5048 DP |
226 | // navigation |
227 | // ---------- | |
228 | ||
e2effeb9 | 229 | // wxTreeItemId.IsOk() will return false if there is no such item |
e21a5048 DP |
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) | |
99006e44 | 238 | wxTreeItemId GetItemParent(const wxTreeItemId& item) const; |
e21a5048 DP |
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 | ||
978f38c2 VZ |
247 | // get the last child of this item - this method doesn't use cookies |
248 | wxTreeItemId GetLastChild(const wxTreeItemId& item) const; | |
e21a5048 DP |
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 | ||
1c3d4180 DP |
263 | // operations |
264 | // ---------- | |
e21a5048 DP |
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, | |
b19b28c8 | 319 | wxClassInfo* textCtrlClass = wxCLASSINFO(wxTextCtrl)); |
e21a5048 DP |
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 | |
e2effeb9 | 325 | void EndEditLabel(const wxTreeItemId& item, bool discardChanges = false); |
e21a5048 DP |
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 | ||
989ab1e5 | 338 | #if WXWIN_COMPATIBILITY_2_6 |
e21a5048 | 339 | // these methods are deprecated and will be removed in future versions of |
77ffb593 | 340 | // wxWidgets, they're here for compatibility only, don't use them in new |
e21a5048 DP |
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 | |
989ab1e5 WS |
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 ); | |
e21a5048 DP |
359 | |
360 | // use AddRoot, PrependItem or AppendItem | |
989ab1e5 WS |
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 | |
e21a5048 DP |
367 | |
368 | // use Set/GetImageList and Set/GetStateImageList | |
369 | wxImageList *GetImageList(int) const | |
370 | { return GetImageList(); } | |
e21a5048 | 371 | |
989ab1e5 WS |
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 | ||
1c3d4180 | 379 | protected: |
f4e325b3 | 380 | |
989ab1e5 WS |
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; | |
f4e325b3 | 389 | |
989ab1e5 | 390 | void SendMessage(wxEventType command, const wxTreeItemId& item); |
e21a5048 DP |
391 | // GtkTreeItem *findGtkTreeItem(wxTreeCtrlId &id) const; |
392 | ||
393 | // the common part of all ctors | |
989ab1e5 WS |
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); | |
e21a5048 | 400 | |
f4e325b3 | 401 | |
989ab1e5 | 402 | DECLARE_DYNAMIC_CLASS(wxTreeCtrl) |
f4e325b3 DP |
403 | }; |
404 | ||
f4e325b3 | 405 | #endif |
1c3d4180 | 406 | // _WX_TREECTRL_H_ |