]> git.saurik.com Git - wxWidgets.git/blob - include/wx/treectrl.h
fix wxBitmapComboBox Gtk-CRITICAL assertion `GTK_IS_ENTRY (entry)' failed
[wxWidgets.git] / include / wx / treectrl.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/treectrl.h
3 // Purpose: wxTreeCtrl base header
4 // Author: Karsten Ballueder
5 // Modified by:
6 // Created:
7 // Copyright: (c) Karsten Ballueder
8 // RCS-ID: $Id$
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_TREECTRL_H_BASE_
13 #define _WX_TREECTRL_H_BASE_
14
15 // ----------------------------------------------------------------------------
16 // headers
17 // ----------------------------------------------------------------------------
18
19 #include "wx/defs.h"
20
21 #if wxUSE_TREECTRL
22
23 #include "wx/control.h"
24 #include "wx/treebase.h"
25 #include "wx/textctrl.h" // wxTextCtrl::ms_classinfo used through wxCLASSINFO macro
26
27 class WXDLLIMPEXP_FWD_CORE wxImageList;
28
29 // ----------------------------------------------------------------------------
30 // wxTreeCtrlBase
31 // ----------------------------------------------------------------------------
32
33 class WXDLLIMPEXP_CORE wxTreeCtrlBase : public wxControl
34 {
35 public:
36 wxTreeCtrlBase();
37 virtual ~wxTreeCtrlBase();
38
39 // accessors
40 // ---------
41
42 // get the total number of items in the control
43 virtual unsigned int GetCount() const = 0;
44
45 // indent is the number of pixels the children are indented relative to
46 // the parents position. SetIndent() also redraws the control
47 // immediately.
48 virtual unsigned int GetIndent() const = 0;
49 virtual void SetIndent(unsigned int indent) = 0;
50
51 // spacing is the number of pixels between the start and the Text
52 // (has no effect under wxMSW)
53 unsigned int GetSpacing() const { return m_spacing; }
54 void SetSpacing(unsigned int spacing) { m_spacing = spacing; }
55
56 // image list: these functions allow to associate an image list with
57 // the control and retrieve it. Note that the control does _not_ delete
58 // the associated image list when it's deleted in order to allow image
59 // lists to be shared between different controls.
60 //
61 // The normal image list is for the icons which correspond to the
62 // normal tree item state (whether it is selected or not).
63 // Additionally, the application might choose to show a state icon
64 // which corresponds to an app-defined item state (for example,
65 // checked/unchecked) which are taken from the state image list.
66 wxImageList *GetImageList() const { return m_imageListNormal; }
67 wxImageList *GetStateImageList() const { return m_imageListState; }
68
69 virtual void SetImageList(wxImageList *imageList) = 0;
70 virtual void SetStateImageList(wxImageList *imageList) = 0;
71 void AssignImageList(wxImageList *imageList)
72 {
73 SetImageList(imageList);
74 m_ownsImageListNormal = true;
75 }
76 void AssignStateImageList(wxImageList *imageList)
77 {
78 SetStateImageList(imageList);
79 m_ownsImageListState = true;
80 }
81
82
83 // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
84 // member functions of wxTreeItem because they must know the tree the item
85 // belongs to for Windows implementation and storing the pointer to
86 // wxTreeCtrl in each wxTreeItem is just too much waste.
87
88 // accessors
89 // ---------
90
91 // retrieve items label
92 virtual wxString GetItemText(const wxTreeItemId& item) const = 0;
93 // get one of the images associated with the item (normal by default)
94 virtual int GetItemImage(const wxTreeItemId& item,
95 wxTreeItemIcon which = wxTreeItemIcon_Normal) const = 0;
96 // get the data associated with the item
97 virtual wxTreeItemData *GetItemData(const wxTreeItemId& item) const = 0;
98
99 // get the item's text colour
100 virtual wxColour GetItemTextColour(const wxTreeItemId& item) const = 0;
101
102 // get the item's background colour
103 virtual wxColour GetItemBackgroundColour(const wxTreeItemId& item) const = 0;
104
105 // get the item's font
106 virtual wxFont GetItemFont(const wxTreeItemId& item) const = 0;
107
108 // get the items state
109 int GetItemState(const wxTreeItemId& item) const
110 {
111 return DoGetItemState(item);
112 }
113
114 // modifiers
115 // ---------
116
117 // set items label
118 virtual void SetItemText(const wxTreeItemId& item, const wxString& text) = 0;
119 // set one of the images associated with the item (normal by default)
120 virtual void SetItemImage(const wxTreeItemId& item,
121 int image,
122 wxTreeItemIcon which = wxTreeItemIcon_Normal) = 0;
123 // associate some data with the item
124 virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData *data) = 0;
125
126 // force appearance of [+] button near the item. This is useful to
127 // allow the user to expand the items which don't have any children now
128 // - but instead add them only when needed, thus minimizing memory
129 // usage and loading time.
130 virtual void SetItemHasChildren(const wxTreeItemId& item,
131 bool has = true) = 0;
132
133 // the item will be shown in bold
134 virtual void SetItemBold(const wxTreeItemId& item, bool bold = true) = 0;
135
136 // the item will be shown with a drop highlight
137 virtual void SetItemDropHighlight(const wxTreeItemId& item,
138 bool highlight = true) = 0;
139
140 // set the items text colour
141 virtual void SetItemTextColour(const wxTreeItemId& item,
142 const wxColour& col) = 0;
143
144 // set the items background colour
145 virtual void SetItemBackgroundColour(const wxTreeItemId& item,
146 const wxColour& col) = 0;
147
148 // set the items font (should be of the same height for all items)
149 virtual void SetItemFont(const wxTreeItemId& item,
150 const wxFont& font) = 0;
151
152 // set the items state (special state values: wxTREE_ITEMSTATE_NONE/NEXT/PREV)
153 void SetItemState(const wxTreeItemId& item, int state);
154
155 // item status inquiries
156 // ---------------------
157
158 // is the item visible (it might be outside the view or not expanded)?
159 virtual bool IsVisible(const wxTreeItemId& item) const = 0;
160 // does the item has any children?
161 virtual bool ItemHasChildren(const wxTreeItemId& item) const = 0;
162 // same as above
163 bool HasChildren(const wxTreeItemId& item) const
164 { return ItemHasChildren(item); }
165 // is the item expanded (only makes sense if HasChildren())?
166 virtual bool IsExpanded(const wxTreeItemId& item) const = 0;
167 // is this item currently selected (the same as has focus)?
168 virtual bool IsSelected(const wxTreeItemId& item) const = 0;
169 // is item text in bold font?
170 virtual bool IsBold(const wxTreeItemId& item) const = 0;
171 // is the control empty?
172 bool IsEmpty() const;
173
174
175 // number of children
176 // ------------------
177
178 // if 'recursively' is false, only immediate children count, otherwise
179 // the returned number is the number of all items in this branch
180 virtual size_t GetChildrenCount(const wxTreeItemId& item,
181 bool recursively = true) const = 0;
182
183 // navigation
184 // ----------
185
186 // wxTreeItemId.IsOk() will return false if there is no such item
187
188 // get the root tree item
189 virtual wxTreeItemId GetRootItem() const = 0;
190
191 // get the item currently selected (may return NULL if no selection)
192 virtual wxTreeItemId GetSelection() const = 0;
193
194 // get the items currently selected, return the number of such item
195 //
196 // NB: this operation is expensive and can take a long time for a
197 // control with a lot of items (~ O(number of items)).
198 virtual size_t GetSelections(wxArrayTreeItemIds& selections) const = 0;
199
200 // get the last item to be clicked when the control has wxTR_MULTIPLE
201 // equivalent to GetSelection() if not wxTR_MULTIPLE
202 virtual wxTreeItemId GetFocusedItem() const = 0;
203
204
205 // Clears the currently focused item
206 virtual void ClearFocusedItem() = 0;
207 // Sets the currently focused item. Item should be valid
208 virtual void SetFocusedItem(const wxTreeItemId& item) = 0;
209
210
211 // get the parent of this item (may return NULL if root)
212 virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const = 0;
213
214 // for this enumeration function you must pass in a "cookie" parameter
215 // which is opaque for the application but is necessary for the library
216 // to make these functions reentrant (i.e. allow more than one
217 // enumeration on one and the same object simultaneously). Of course,
218 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
219 // the same!
220
221 // get the first child of this item
222 virtual wxTreeItemId GetFirstChild(const wxTreeItemId& item,
223 wxTreeItemIdValue& cookie) const = 0;
224 // get the next child
225 virtual wxTreeItemId GetNextChild(const wxTreeItemId& item,
226 wxTreeItemIdValue& cookie) const = 0;
227 // get the last child of this item - this method doesn't use cookies
228 virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const = 0;
229
230 // get the next sibling of this item
231 virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const = 0;
232 // get the previous sibling
233 virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const = 0;
234
235 // get first visible item
236 virtual wxTreeItemId GetFirstVisibleItem() const = 0;
237 // get the next visible item: item must be visible itself!
238 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
239 virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const = 0;
240 // get the previous visible item: item must be visible itself!
241 virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const = 0;
242
243 // operations
244 // ----------
245
246 // add the root node to the tree
247 virtual wxTreeItemId AddRoot(const wxString& text,
248 int image = -1, int selImage = -1,
249 wxTreeItemData *data = NULL) = 0;
250
251 // insert a new item in as the first child of the parent
252 wxTreeItemId PrependItem(const wxTreeItemId& parent,
253 const wxString& text,
254 int image = -1, int selImage = -1,
255 wxTreeItemData *data = NULL)
256 {
257 return DoInsertItem(parent, 0u, text, image, selImage, data);
258 }
259
260 // insert a new item after a given one
261 wxTreeItemId InsertItem(const wxTreeItemId& parent,
262 const wxTreeItemId& idPrevious,
263 const wxString& text,
264 int image = -1, int selImage = -1,
265 wxTreeItemData *data = NULL)
266 {
267 return DoInsertAfter(parent, idPrevious, text, image, selImage, data);
268 }
269
270 // insert a new item before the one with the given index
271 wxTreeItemId InsertItem(const wxTreeItemId& parent,
272 size_t pos,
273 const wxString& text,
274 int image = -1, int selImage = -1,
275 wxTreeItemData *data = NULL)
276 {
277 return DoInsertItem(parent, pos, text, image, selImage, data);
278 }
279
280 // insert a new item in as the last child of the parent
281 wxTreeItemId AppendItem(const wxTreeItemId& parent,
282 const wxString& text,
283 int image = -1, int selImage = -1,
284 wxTreeItemData *data = NULL)
285 {
286 return DoInsertItem(parent, (size_t)-1, text, image, selImage, data);
287 }
288
289 // delete this item and associated data if any
290 virtual void Delete(const wxTreeItemId& item) = 0;
291 // delete all children (but don't delete the item itself)
292 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
293 virtual void DeleteChildren(const wxTreeItemId& item) = 0;
294 // delete all items from the tree
295 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
296 virtual void DeleteAllItems() = 0;
297
298 // expand this item
299 virtual void Expand(const wxTreeItemId& item) = 0;
300 // expand the item and all its children recursively
301 void ExpandAllChildren(const wxTreeItemId& item);
302 // expand all items
303 void ExpandAll();
304 // collapse the item without removing its children
305 virtual void Collapse(const wxTreeItemId& item) = 0;
306 // collapse the item and all its children
307 void CollapseAllChildren(const wxTreeItemId& item);
308 // collapse all items
309 void CollapseAll();
310 // collapse the item and remove all children
311 virtual void CollapseAndReset(const wxTreeItemId& item) = 0;
312 // toggles the current state
313 virtual void Toggle(const wxTreeItemId& item) = 0;
314
315 // remove the selection from currently selected item (if any)
316 virtual void Unselect() = 0;
317 // unselect all items (only makes sense for multiple selection control)
318 virtual void UnselectAll() = 0;
319 // select this item
320 virtual void SelectItem(const wxTreeItemId& item, bool select = true) = 0;
321 // selects all (direct) children for given parent (only for
322 // multiselection controls)
323 virtual void SelectChildren(const wxTreeItemId& parent) = 0;
324 // unselect this item
325 void UnselectItem(const wxTreeItemId& item) { SelectItem(item, false); }
326 // toggle item selection
327 void ToggleItemSelection(const wxTreeItemId& item)
328 {
329 SelectItem(item, !IsSelected(item));
330 }
331
332 // make sure this item is visible (expanding the parent item and/or
333 // scrolling to this item if necessary)
334 virtual void EnsureVisible(const wxTreeItemId& item) = 0;
335 // scroll to this item (but don't expand its parent)
336 virtual void ScrollTo(const wxTreeItemId& item) = 0;
337
338 // start editing the item label: this (temporarily) replaces the item
339 // with a one line edit control. The item will be selected if it hadn't
340 // been before. textCtrlClass parameter allows you to create an edit
341 // control of arbitrary user-defined class deriving from wxTextCtrl.
342 virtual wxTextCtrl *EditLabel(const wxTreeItemId& item,
343 wxClassInfo* textCtrlClass = wxCLASSINFO(wxTextCtrl)) = 0;
344 // returns the same pointer as StartEdit() if the item is being edited,
345 // NULL otherwise (it's assumed that no more than one item may be
346 // edited simultaneously)
347 virtual wxTextCtrl *GetEditControl() const = 0;
348 // end editing and accept or discard the changes to item label
349 virtual void EndEditLabel(const wxTreeItemId& item,
350 bool discardChanges = false) = 0;
351
352 // Enable or disable beep when incremental match doesn't find any item.
353 // Only implemented in the generic version currently.
354 virtual void EnableBellOnNoMatch(bool WXUNUSED(on) = true) { }
355
356 // sorting
357 // -------
358
359 // this function is called to compare 2 items and should return -1, 0
360 // or +1 if the first item is less than, equal to or greater than the
361 // second one. The base class version performs alphabetic comparaison
362 // of item labels (GetText)
363 virtual int OnCompareItems(const wxTreeItemId& item1,
364 const wxTreeItemId& item2)
365 {
366 return wxStrcmp(GetItemText(item1), GetItemText(item2));
367 }
368
369 // sort the children of this item using OnCompareItems
370 //
371 // NB: this function is not reentrant and not MT-safe (FIXME)!
372 virtual void SortChildren(const wxTreeItemId& item) = 0;
373
374 // items geometry
375 // --------------
376
377 // determine to which item (if any) belongs the given point (the
378 // coordinates specified are relative to the client area of tree ctrl)
379 // and, in the second variant, fill the flags parameter with a bitmask
380 // of wxTREE_HITTEST_xxx constants.
381 wxTreeItemId HitTest(const wxPoint& point) const
382 { int dummy; return DoTreeHitTest(point, dummy); }
383 wxTreeItemId HitTest(const wxPoint& point, int& flags) const
384 { return DoTreeHitTest(point, flags); }
385
386 // get the bounding rectangle of the item (or of its label only)
387 virtual bool GetBoundingRect(const wxTreeItemId& item,
388 wxRect& rect,
389 bool textOnly = false) const = 0;
390
391
392 // implementation
393 // --------------
394
395 virtual bool ShouldInheritColours() const { return false; }
396
397 // hint whether to calculate best size quickly or accurately
398 void SetQuickBestSize(bool q) { m_quickBestSize = q; }
399 bool GetQuickBestSize() const { return m_quickBestSize; }
400
401 protected:
402 virtual wxSize DoGetBestSize() const;
403
404 // common part of Get/SetItemState()
405 virtual int DoGetItemState(const wxTreeItemId& item) const = 0;
406 virtual void DoSetItemState(const wxTreeItemId& item, int state) = 0;
407
408 // common part of Append/Prepend/InsertItem()
409 //
410 // pos is the position at which to insert the item or (size_t)-1 to append
411 // it to the end
412 virtual wxTreeItemId DoInsertItem(const wxTreeItemId& parent,
413 size_t pos,
414 const wxString& text,
415 int image, int selImage,
416 wxTreeItemData *data) = 0;
417
418 // and this function implements overloaded InsertItem() taking wxTreeItemId
419 // (it can't be called InsertItem() as we'd have virtual function hiding
420 // problem in derived classes then)
421 virtual wxTreeItemId DoInsertAfter(const wxTreeItemId& parent,
422 const wxTreeItemId& idPrevious,
423 const wxString& text,
424 int image = -1, int selImage = -1,
425 wxTreeItemData *data = NULL) = 0;
426
427 // real HitTest() implementation: again, can't be called just HitTest()
428 // because it's overloaded and so the non-virtual overload would be hidden
429 // (and can't be called DoHitTest() because this is already in wxWindow)
430 virtual wxTreeItemId DoTreeHitTest(const wxPoint& point,
431 int& flags) const = 0;
432
433
434 wxImageList *m_imageListNormal, // images for tree elements
435 *m_imageListState; // special images for app defined states
436 bool m_ownsImageListNormal,
437 m_ownsImageListState;
438
439 // spacing between left border and the text
440 unsigned int m_spacing;
441
442 // whether full or quick calculation is done in DoGetBestSize
443 bool m_quickBestSize;
444
445
446 private:
447 // Intercept Escape and Return keys to ensure that our in-place edit
448 // control always gets them before they're used for dialog navigation or
449 // anything else.
450 void OnCharHook(wxKeyEvent& event);
451
452
453 wxDECLARE_NO_COPY_CLASS(wxTreeCtrlBase);
454 };
455
456 // ----------------------------------------------------------------------------
457 // include the platform-dependent wxTreeCtrl class
458 // ----------------------------------------------------------------------------
459
460 #if defined(__WXUNIVERSAL__)
461 #include "wx/generic/treectlg.h"
462 #elif defined(__WXMSW__)
463 #include "wx/msw/treectrl.h"
464 #elif defined(__WXMOTIF__)
465 #include "wx/generic/treectlg.h"
466 #elif defined(__WXGTK__)
467 #include "wx/generic/treectlg.h"
468 #elif defined(__WXMAC__)
469 #include "wx/generic/treectlg.h"
470 #elif defined(__WXCOCOA__)
471 #include "wx/generic/treectlg.h"
472 #elif defined(__WXPM__)
473 #include "wx/generic/treectlg.h"
474 #endif
475
476 #endif // wxUSE_TREECTRL
477
478 #endif // _WX_TREECTRL_H_BASE_