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