]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: treectrl.h | |
3 | // Purpose: wxTreeCtrl class | |
4 | // Author: Julian Smart | |
5 | // Modified by: Vadim Zeitlin to be less MSW-specific on 10/10/98 | |
6 | // Created: 01/02/97 | |
7 | // RCS-ID: $Id$ | |
8 | // Copyright: (c) Julian Smart and Markus Holzem | |
9 | // Licence: wxWindows license | |
10 | ///////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | #ifndef _WX_TREECTRL_H_ | |
13 | #define _WX_TREECTRL_H_ | |
14 | ||
15 | // ---------------------------------------------------------------------------- | |
16 | // headers | |
17 | // ---------------------------------------------------------------------------- | |
18 | ||
19 | #ifdef __GNUG__ | |
20 | #pragma interface "treectrl.h" | |
21 | #endif | |
22 | ||
23 | #include "wx/textctrl.h" | |
24 | #include "wx/dynarray.h" | |
25 | ||
26 | #ifdef __GNUWIN32__ | |
27 | // Cygwin windows.h defines these identifiers | |
28 | #undef GetFirstChild | |
29 | #undef GetNextSibling | |
30 | #endif // Cygwin | |
31 | ||
32 | // the type for "untyped" data | |
33 | typedef long wxDataType; | |
34 | ||
35 | // fwd decl | |
36 | class WXDLLEXPORT wxImageList; | |
37 | class WXDLLEXPORT wxDragImage; | |
38 | struct WXDLLEXPORT wxTreeViewItem; | |
39 | ||
40 | // a callback function used for sorting tree items, it should return -1 if the | |
41 | // first item precedes the second, +1 if the second precedes the first or 0 if | |
42 | // they're equivalent | |
43 | class wxTreeItemData; | |
44 | ||
45 | // NB: all the following flags are for compatbility only and will be removed in the | |
46 | // next versions | |
47 | ||
48 | // flags for deprecated `Expand(int action)' | |
49 | enum | |
50 | { | |
51 | wxTREE_EXPAND_EXPAND, | |
52 | wxTREE_EXPAND_COLLAPSE, | |
53 | wxTREE_EXPAND_COLLAPSE_RESET, | |
54 | wxTREE_EXPAND_TOGGLE | |
55 | }; | |
56 | ||
57 | // flags for deprecated InsertItem() variant | |
58 | #define wxTREE_INSERT_FIRST 0xFFFF0001 | |
59 | #define wxTREE_INSERT_LAST 0xFFFF0002 | |
60 | ||
61 | // ---------------------------------------------------------------------------- | |
62 | // wxTreeItemId identifies an element of the tree. In this implementation, it's | |
63 | // just a trivial wrapper around Win32 HTREEITEM. It's opaque for the | |
64 | // application. | |
65 | // ---------------------------------------------------------------------------- | |
66 | class WXDLLEXPORT wxTreeItemId | |
67 | { | |
68 | public: | |
69 | // ctors | |
70 | // 0 is invalid value for HTREEITEM | |
71 | wxTreeItemId() { m_itemId = 0; } | |
72 | ||
73 | // default copy ctor/assignment operator are ok for us | |
74 | ||
75 | // accessors | |
76 | // is this a valid tree item? | |
77 | bool IsOk() const { return m_itemId != 0; } | |
78 | ||
79 | // conversion to/from either real (system-dependent) tree item id or | |
80 | // to "long" which used to be the type for tree item ids in previous | |
81 | // versions of wxWindows | |
82 | ||
83 | // for wxTreeCtrl usage only | |
84 | wxTreeItemId(WXHTREEITEM itemId) { m_itemId = (long)itemId; } | |
85 | operator WXHTREEITEM() const { return (WXHTREEITEM)m_itemId; } | |
86 | ||
87 | void operator=(WXHTREEITEM item) { m_itemId = (long) item; } | |
88 | ||
89 | protected: | |
90 | long m_itemId; | |
91 | }; | |
92 | ||
93 | WX_DEFINE_EXPORTED_ARRAY(WXHTREEITEM, wxArrayTreeItemIds); | |
94 | ||
95 | // ---------------------------------------------------------------------------- | |
96 | // wxTreeItemData is some (arbitrary) user class associated with some item. The | |
97 | // main advantage of having this class (compared to old untyped interface) is | |
98 | // that wxTreeItemData's are destroyed automatically by the tree and, as this | |
99 | // class has virtual dtor, it means that the memory will be automatically | |
100 | // freed. OTOH, we don't just use wxObject instead of wxTreeItemData because | |
101 | // the size of this class is critical: in any real application, each tree leaf | |
102 | // will have wxTreeItemData associated with it and number of leaves may be | |
103 | // quite big. | |
104 | // | |
105 | // Because the objects of this class are deleted by the tree, they should | |
106 | // always be allocated on the heap! | |
107 | // ---------------------------------------------------------------------------- | |
108 | class WXDLLEXPORT wxTreeItemData : private wxTreeItemId | |
109 | { | |
110 | public: | |
111 | // default ctor/copy ctor/assignment operator are ok | |
112 | ||
113 | // dtor is virtual and all the items are deleted by the tree control when | |
114 | // it's deleted, so you normally don't have to care about freeing memory | |
115 | // allocated in your wxTreeItemData-derived class | |
116 | virtual ~wxTreeItemData() { } | |
117 | ||
118 | // accessors: set/get the item associated with this node | |
119 | void SetId(const wxTreeItemId& id) { m_itemId = id; } | |
120 | const wxTreeItemId GetId() const { return *this; } | |
121 | }; | |
122 | ||
123 | // ---------------------------------------------------------------------------- | |
124 | // wxTreeCtrl | |
125 | // ---------------------------------------------------------------------------- | |
126 | class WXDLLEXPORT wxTreeCtrl : public wxControl | |
127 | { | |
128 | public: | |
129 | // creation | |
130 | // -------- | |
131 | wxTreeCtrl() { Init(); } | |
132 | ||
133 | wxTreeCtrl(wxWindow *parent, wxWindowID id = -1, | |
134 | const wxPoint& pos = wxDefaultPosition, | |
135 | const wxSize& size = wxDefaultSize, | |
136 | long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT, | |
137 | const wxValidator& validator = wxDefaultValidator, | |
138 | const wxString& name = "wxTreeCtrl") | |
139 | { | |
140 | Create(parent, id, pos, size, style, validator, name); | |
141 | } | |
142 | ||
143 | virtual ~wxTreeCtrl(); | |
144 | ||
145 | bool Create(wxWindow *parent, wxWindowID id = -1, | |
146 | const wxPoint& pos = wxDefaultPosition, | |
147 | const wxSize& size = wxDefaultSize, | |
148 | long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT, | |
149 | const wxValidator& validator = wxDefaultValidator, | |
150 | const wxString& name = "wxTreeCtrl"); | |
151 | ||
152 | // accessors | |
153 | // --------- | |
154 | ||
155 | // get the total number of items in the control | |
156 | size_t GetCount() const; | |
157 | ||
158 | // indent is the number of pixels the children are indented relative to | |
159 | // the parents position. SetIndent() also redraws the control | |
160 | // immediately. | |
161 | unsigned int GetIndent() const; | |
162 | void SetIndent(unsigned int indent); | |
163 | ||
164 | // spacing is the number of pixels between the start and the Text | |
165 | // not implemented under wxMSW | |
166 | unsigned int GetSpacing() const { return 18; } // return wxGTK default | |
167 | void SetSpacing(unsigned int WXUNUSED(spacing)) { } | |
168 | ||
169 | // image list: these functions allow to associate an image list with | |
170 | // the control and retrieve it. Note that the control does _not_ delete | |
171 | // the associated image list when it's deleted in order to allow image | |
172 | // lists to be shared between different controls. | |
173 | // | |
174 | // The normal image list is for the icons which correspond to the | |
175 | // normal tree item state (whether it is selected or not). | |
176 | // Additionally, the application might choose to show a state icon | |
177 | // which corresponds to an app-defined item state (for example, | |
178 | // checked/unchecked) which are taken from the state image list. | |
179 | wxImageList *GetImageList() const; | |
180 | wxImageList *GetStateImageList() const; | |
181 | ||
182 | void SetImageList(wxImageList *imageList); | |
183 | void SetStateImageList(wxImageList *imageList); | |
184 | ||
185 | // Functions to work with tree ctrl items. Unfortunately, they can _not_ be | |
186 | // member functions of wxTreeItem because they must know the tree the item | |
187 | // belongs to for Windows implementation and storing the pointer to | |
188 | // wxTreeCtrl in each wxTreeItem is just too much waste. | |
189 | ||
190 | // accessors | |
191 | // --------- | |
192 | ||
193 | // retrieve items label | |
194 | wxString GetItemText(const wxTreeItemId& item) const; | |
195 | // get one of the images associated with the item (normal by default) | |
196 | int GetItemImage(const wxTreeItemId& item, | |
197 | wxTreeItemIcon which = wxTreeItemIcon_Normal) const; | |
198 | // get the data associated with the item | |
199 | wxTreeItemData *GetItemData(const wxTreeItemId& item) const; | |
200 | ||
201 | // modifiers | |
202 | // --------- | |
203 | ||
204 | // set items label | |
205 | void SetItemText(const wxTreeItemId& item, const wxString& text); | |
206 | // get one of the images associated with the item (normal by default) | |
207 | void SetItemImage(const wxTreeItemId& item, int image, | |
208 | wxTreeItemIcon which = wxTreeItemIcon_Normal); | |
209 | // associate some data with the item | |
210 | void SetItemData(const wxTreeItemId& item, wxTreeItemData *data); | |
211 | ||
212 | // force appearance of [+] button near the item. This is useful to | |
213 | // allow the user to expand the items which don't have any children now | |
214 | // - but instead add them only when needed, thus minimizing memory | |
215 | // usage and loading time. | |
216 | void SetItemHasChildren(const wxTreeItemId& item, bool has = TRUE); | |
217 | ||
218 | // the item will be shown in bold | |
219 | void SetItemBold(const wxTreeItemId& item, bool bold = TRUE); | |
220 | ||
221 | // the item will be shown with a drop highlight | |
222 | void SetItemDropHighlight(const wxTreeItemId& item, bool highlight = TRUE); | |
223 | ||
224 | // set the items text colour | |
225 | void SetItemTextColour(const wxTreeItemId& item, const wxColour& col); | |
226 | ||
227 | // set the items background colour | |
228 | void SetItemBackgroundColour(const wxTreeItemId& item, const wxColour& col); | |
229 | ||
230 | // set the items font (should be of the same height for all items) | |
231 | void SetItemFont(const wxTreeItemId& item, const wxFont& font); | |
232 | ||
233 | // item status inquiries | |
234 | // --------------------- | |
235 | ||
236 | // is the item visible (it might be outside the view or not expanded)? | |
237 | bool IsVisible(const wxTreeItemId& item) const; | |
238 | // does the item has any children? | |
239 | bool ItemHasChildren(const wxTreeItemId& item) const; | |
240 | // is the item expanded (only makes sense if HasChildren())? | |
241 | bool IsExpanded(const wxTreeItemId& item) const; | |
242 | // is this item currently selected (the same as has focus)? | |
243 | bool IsSelected(const wxTreeItemId& item) const; | |
244 | // is item text in bold font? | |
245 | bool IsBold(const wxTreeItemId& item) const; | |
246 | ||
247 | // number of children | |
248 | // ------------------ | |
249 | ||
250 | // if 'recursively' is FALSE, only immediate children count, otherwise | |
251 | // the returned number is the number of all items in this branch | |
252 | size_t GetChildrenCount(const wxTreeItemId& item, | |
253 | bool recursively = TRUE) const; | |
254 | ||
255 | // navigation | |
256 | // ---------- | |
257 | ||
258 | // wxTreeItemId.IsOk() will return FALSE if there is no such item | |
259 | ||
260 | // get the root tree item | |
261 | wxTreeItemId GetRootItem() const; | |
262 | ||
263 | // get the item currently selected (may return NULL if no selection) | |
264 | wxTreeItemId GetSelection() const; | |
265 | ||
266 | // get the items currently selected, return the number of such item | |
267 | // | |
268 | // NB: this operation is expensive and can take a long time for a | |
269 | // control with a lot of items (~ O(number of items)). | |
270 | size_t GetSelections(wxArrayTreeItemIds& selections) const; | |
271 | ||
272 | // get the parent of this item (may return NULL if root) | |
273 | wxTreeItemId GetParent(const wxTreeItemId& item) const; | |
274 | ||
275 | // for this enumeration function you must pass in a "cookie" parameter | |
276 | // which is opaque for the application but is necessary for the library | |
277 | // to make these functions reentrant (i.e. allow more than one | |
278 | // enumeration on one and the same object simultaneously). Of course, | |
279 | // the "cookie" passed to GetFirstChild() and GetNextChild() should be | |
280 | // the same! | |
281 | ||
282 | // get the first child of this item | |
283 | wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& _cookie) const; | |
284 | // get the next child | |
285 | wxTreeItemId GetNextChild(const wxTreeItemId& item, long& _cookie) const; | |
286 | // get the last child of this item - this method doesn't use cookies | |
287 | wxTreeItemId GetLastChild(const wxTreeItemId& item) const; | |
288 | ||
289 | // get the next sibling of this item | |
290 | wxTreeItemId GetNextSibling(const wxTreeItemId& item) const; | |
291 | // get the previous sibling | |
292 | wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const; | |
293 | ||
294 | // get first visible item | |
295 | wxTreeItemId GetFirstVisibleItem() const; | |
296 | // get the next visible item: item must be visible itself! | |
297 | // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem() | |
298 | wxTreeItemId GetNextVisible(const wxTreeItemId& item) const; | |
299 | // get the previous visible item: item must be visible itself! | |
300 | wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const; | |
301 | ||
302 | // operations | |
303 | // ---------- | |
304 | ||
305 | // add the root node to the tree | |
306 | wxTreeItemId AddRoot(const wxString& text, | |
307 | int image = -1, int selectedImage = -1, | |
308 | wxTreeItemData *data = NULL); | |
309 | ||
310 | // insert a new item in as the first child of the parent | |
311 | wxTreeItemId PrependItem(const wxTreeItemId& parent, | |
312 | const wxString& text, | |
313 | int image = -1, int selectedImage = -1, | |
314 | wxTreeItemData *data = NULL); | |
315 | ||
316 | // insert a new item after a given one | |
317 | wxTreeItemId InsertItem(const wxTreeItemId& parent, | |
318 | const wxTreeItemId& idPrevious, | |
319 | const wxString& text, | |
320 | int image = -1, int selectedImage = -1, | |
321 | wxTreeItemData *data = NULL); | |
322 | ||
323 | // insert a new item before the one with the given index | |
324 | wxTreeItemId InsertItem(const wxTreeItemId& parent, | |
325 | size_t index, | |
326 | const wxString& text, | |
327 | int image = -1, int selectedImage = -1, | |
328 | wxTreeItemData *data = NULL); | |
329 | ||
330 | // insert a new item in as the last child of the parent | |
331 | wxTreeItemId AppendItem(const wxTreeItemId& parent, | |
332 | const wxString& text, | |
333 | int image = -1, int selectedImage = -1, | |
334 | wxTreeItemData *data = NULL); | |
335 | ||
336 | // delete this item and associated data if any | |
337 | void Delete(const wxTreeItemId& item); | |
338 | // delete all children (but don't delete the item itself) | |
339 | // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events | |
340 | void DeleteChildren(const wxTreeItemId& item); | |
341 | // delete all items from the tree | |
342 | // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events | |
343 | void DeleteAllItems(); | |
344 | ||
345 | // expand this item | |
346 | void Expand(const wxTreeItemId& item); | |
347 | // collapse the item without removing its children | |
348 | void Collapse(const wxTreeItemId& item); | |
349 | // collapse the item and remove all children | |
350 | void CollapseAndReset(const wxTreeItemId& item); | |
351 | // toggles the current state | |
352 | void Toggle(const wxTreeItemId& item); | |
353 | ||
354 | // remove the selection from currently selected item (if any) | |
355 | void Unselect(); | |
356 | // unselect all items (only makes sense for multiple selection control) | |
357 | void UnselectAll(); | |
358 | // select this item | |
359 | void SelectItem(const wxTreeItemId& item); | |
360 | // make sure this item is visible (expanding the parent item and/or | |
361 | // scrolling to this item if necessary) | |
362 | void EnsureVisible(const wxTreeItemId& item); | |
363 | // scroll to this item (but don't expand its parent) | |
364 | void ScrollTo(const wxTreeItemId& item); | |
365 | ||
366 | // start editing the item label: this (temporarily) replaces the item | |
367 | // with a one line edit control. The item will be selected if it hadn't | |
368 | // been before. textCtrlClass parameter allows you to create an edit | |
369 | // control of arbitrary user-defined class deriving from wxTextCtrl. | |
370 | wxTextCtrl* EditLabel(const wxTreeItemId& item, | |
371 | wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl)); | |
372 | // returns the same pointer as StartEdit() if the item is being edited, | |
373 | // NULL otherwise (it's assumed that no more than one item may be | |
374 | // edited simultaneously) | |
375 | wxTextCtrl* GetEditControl() const; | |
376 | // end editing and accept or discard the changes to item label | |
377 | void EndEditLabel(const wxTreeItemId& item, bool discardChanges = FALSE); | |
378 | ||
379 | // sorting | |
380 | // this function is called to compare 2 items and should return -1, 0 | |
381 | // or +1 if the first item is less than, equal to or greater than the | |
382 | // second one. The base class version performs alphabetic comparaison | |
383 | // of item labels (GetText) | |
384 | virtual int OnCompareItems(const wxTreeItemId& item1, | |
385 | const wxTreeItemId& item2); | |
386 | // sort the children of this item using OnCompareItems | |
387 | // | |
388 | // NB: this function is not reentrant and not MT-safe (FIXME)! | |
389 | void SortChildren(const wxTreeItemId& item); | |
390 | ||
391 | // helpers | |
392 | // ------- | |
393 | ||
394 | // determine to which item (if any) belongs the given point (the | |
395 | // coordinates specified are relative to the client area of tree ctrl) | |
396 | // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx | |
397 | // constants. | |
398 | // | |
399 | // The first function is more portable (because easier to implement | |
400 | // on other platforms), but the second one returns some extra info. | |
401 | wxTreeItemId HitTest(const wxPoint& point) | |
402 | { int dummy; return HitTest(point, dummy); } | |
403 | wxTreeItemId HitTest(const wxPoint& point, int& flags); | |
404 | ||
405 | // get the bounding rectangle of the item (or of its label only) | |
406 | bool GetBoundingRect(const wxTreeItemId& item, | |
407 | wxRect& rect, | |
408 | bool textOnly = FALSE) const; | |
409 | ||
410 | // deprecated | |
411 | // ---------- | |
412 | ||
413 | // these methods are deprecated and will be removed in future versions of | |
414 | // wxWindows, they're here for compatibility only, don't use them in new | |
415 | // code (the comments indicate why these methods are now useless and how to | |
416 | // replace them) | |
417 | ||
418 | // use Expand, Collapse, CollapseAndReset or Toggle | |
419 | void ExpandItem(const wxTreeItemId& item, int action); | |
420 | ||
421 | // use AddRoot, PrependItem or AppendItem | |
422 | wxTreeItemId InsertItem(const wxTreeItemId& parent, | |
423 | const wxString& text, | |
424 | int image = -1, int selImage = -1, | |
425 | long insertAfter = wxTREE_INSERT_LAST); | |
426 | ||
427 | // use Set/GetImageList and Set/GetStateImageList | |
428 | wxImageList *GetImageList(int) const | |
429 | { return GetImageList(); } | |
430 | void SetImageList(wxImageList *imageList, int) | |
431 | { SetImageList(imageList); } | |
432 | ||
433 | // use Set/GetItemImage directly | |
434 | // get the selected item image | |
435 | int GetItemSelectedImage(const wxTreeItemId& item) const | |
436 | { return GetItemImage(item, wxTreeItemIcon_Selected); } | |
437 | // set the selected item image | |
438 | void SetItemSelectedImage(const wxTreeItemId& item, int image) | |
439 | { SetItemImage(item, image, wxTreeItemIcon_Selected); } | |
440 | ||
441 | // implementation | |
442 | // -------------- | |
443 | virtual long MSWWindowProc(WXUINT nMsg, WXWPARAM wParam, WXLPARAM lParam); | |
444 | virtual bool MSWCommand(WXUINT param, WXWORD id); | |
445 | virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result); | |
446 | ||
447 | // override some base class virtuals | |
448 | virtual bool SetBackgroundColour(const wxColour &colour); | |
449 | virtual bool SetForegroundColour(const wxColour &colour); | |
450 | ||
451 | // get/set the check state for the item (only for wxTR_MULTIPLE) | |
452 | bool IsItemChecked(const wxTreeItemId& item) const; | |
453 | void SetItemCheck(const wxTreeItemId& item, bool check = TRUE); | |
454 | ||
455 | protected: | |
456 | // SetImageList helper | |
457 | void SetAnyImageList(wxImageList *imageList, int which); | |
458 | ||
459 | wxTextCtrl *m_textCtrl; // used while editing the item label | |
460 | wxImageList *m_imageListNormal, // images for tree elements | |
461 | *m_imageListState; // special images for app defined states | |
462 | ||
463 | private: | |
464 | // the common part of all ctors | |
465 | void Init(); | |
466 | ||
467 | // helper functions | |
468 | inline bool DoGetItem(wxTreeViewItem *tvItem) const; | |
469 | inline void DoSetItem(wxTreeViewItem *tvItem); | |
470 | ||
471 | inline void DoExpand(const wxTreeItemId& item, int flag); | |
472 | ||
473 | wxTreeItemId DoInsertItem(const wxTreeItemId& parent, | |
474 | wxTreeItemId hInsertAfter, | |
475 | const wxString& text, | |
476 | int image, int selectedImage, | |
477 | wxTreeItemData *data); | |
478 | ||
479 | int DoGetItemImageFromData(const wxTreeItemId& item, | |
480 | wxTreeItemIcon which) const; | |
481 | void DoSetItemImageFromData(const wxTreeItemId& item, | |
482 | int image, | |
483 | wxTreeItemIcon which) const; | |
484 | void DoSetItemImages(const wxTreeItemId& item, int image, int imageSel); | |
485 | ||
486 | void DeleteTextCtrl(); | |
487 | ||
488 | // support for additional item images | |
489 | friend class wxTreeItemIndirectData; | |
490 | void SetIndirectItemData(const wxTreeItemId& item, | |
491 | wxTreeItemIndirectData *data); | |
492 | bool HasIndirectData(const wxTreeItemId& item) const; | |
493 | ||
494 | // the array storing all item ids which have indirect data | |
495 | wxArrayTreeItemIds m_itemsWithIndirectData; | |
496 | ||
497 | // the hash storing the items attributes (indexed by items ids) | |
498 | wxHashTable m_attrs; | |
499 | ||
500 | // TRUE if the hash above is not empty | |
501 | bool m_hasAnyAttr; | |
502 | ||
503 | // used for dragging | |
504 | wxDragImage *m_dragImage; | |
505 | ||
506 | DECLARE_DYNAMIC_CLASS(wxTreeCtrl) | |
507 | }; | |
508 | ||
509 | #endif | |
510 | // _WX_TREECTRL_H_ |