]> git.saurik.com Git - wxWidgets.git/blame - include/wx/treectrl.h
remove unused file
[wxWidgets.git] / include / wx / treectrl.h
CommitLineData
99d80019
JS
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
34138703
JS
12#ifndef _WX_TREECTRL_H_BASE_
13#define _WX_TREECTRL_H_BASE_
c801d85f 14
b220b1a2
WS
15// ----------------------------------------------------------------------------
16// headers
17// ----------------------------------------------------------------------------
18
19#include "wx/defs.h"
20
21#if wxUSE_TREECTRL
22
1fd0e166 23#include "wx/control.h"
484523cf 24#include "wx/treebase.h"
1fd0e166 25#include "wx/textctrl.h" // wxTextCtrl::ms_classinfo used through CLASSINFO macro
1044a386 26
b5dbe15d 27class WXDLLIMPEXP_FWD_CORE wxImageList;
8cee4a30
VZ
28
29// ----------------------------------------------------------------------------
30// wxTreeCtrlBase
31// ----------------------------------------------------------------------------
32
33class WXDLLEXPORT wxTreeCtrlBase : public wxControl
34{
35public:
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;
7c384067
JS
45
46 // quick DoGetBestSize calculation
47 m_quickBestSize = true;
8cee4a30
VZ
48 }
49
50 virtual ~wxTreeCtrlBase();
51
52 // accessors
53 // ---------
54
55 // get the total number of items in the control
027d45e8 56 virtual unsigned int GetCount() const = 0;
8cee4a30
VZ
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;
56c6fc01 126 // set one of the images associated with the item (normal by default)
8cee4a30
VZ
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;
9248adc8
VZ
175 // is the control empty?
176 bool IsEmpty() const;
177
8cee4a30
VZ
178
179 // number of children
180 // ------------------
181
182 // if 'recursively' is false, only immediate children count, otherwise
183 // the returned number is the number of all items in this branch
184 virtual size_t GetChildrenCount(const wxTreeItemId& item,
185 bool recursively = true) const = 0;
186
187 // navigation
188 // ----------
189
190 // wxTreeItemId.IsOk() will return false if there is no such item
191
192 // get the root tree item
193 virtual wxTreeItemId GetRootItem() const = 0;
194
195 // get the item currently selected (may return NULL if no selection)
196 virtual wxTreeItemId GetSelection() const = 0;
197
198 // get the items currently selected, return the number of such item
199 //
200 // NB: this operation is expensive and can take a long time for a
201 // control with a lot of items (~ O(number of items)).
202 virtual size_t GetSelections(wxArrayTreeItemIds& selections) const = 0;
203
204 // get the parent of this item (may return NULL if root)
205 virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const = 0;
206
207 // for this enumeration function you must pass in a "cookie" parameter
208 // which is opaque for the application but is necessary for the library
209 // to make these functions reentrant (i.e. allow more than one
210 // enumeration on one and the same object simultaneously). Of course,
211 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
212 // the same!
213
214 // get the first child of this item
215 virtual wxTreeItemId GetFirstChild(const wxTreeItemId& item,
216 wxTreeItemIdValue& cookie) const = 0;
217 // get the next child
218 virtual wxTreeItemId GetNextChild(const wxTreeItemId& item,
219 wxTreeItemIdValue& cookie) const = 0;
220 // get the last child of this item - this method doesn't use cookies
221 virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const = 0;
222
223 // get the next sibling of this item
224 virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const = 0;
225 // get the previous sibling
226 virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const = 0;
227
228 // get first visible item
229 virtual wxTreeItemId GetFirstVisibleItem() const = 0;
230 // get the next visible item: item must be visible itself!
231 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
232 virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const = 0;
233 // get the previous visible item: item must be visible itself!
234 virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const = 0;
235
236 // operations
237 // ----------
238
239 // add the root node to the tree
240 virtual wxTreeItemId AddRoot(const wxString& text,
241 int image = -1, int selImage = -1,
242 wxTreeItemData *data = NULL) = 0;
243
244 // insert a new item in as the first child of the parent
245 wxTreeItemId PrependItem(const wxTreeItemId& parent,
246 const wxString& text,
247 int image = -1, int selImage = -1,
248 wxTreeItemData *data = NULL)
249 {
250 return DoInsertItem(parent, 0u, text, image, selImage, data);
251 }
252
253 // insert a new item after a given one
254 wxTreeItemId InsertItem(const wxTreeItemId& parent,
255 const wxTreeItemId& idPrevious,
256 const wxString& text,
257 int image = -1, int selImage = -1,
258 wxTreeItemData *data = NULL)
259 {
260 return DoInsertAfter(parent, idPrevious, text, image, selImage, data);
261 }
262
263 // insert a new item before the one with the given index
264 wxTreeItemId InsertItem(const wxTreeItemId& parent,
265 size_t pos,
266 const wxString& text,
267 int image = -1, int selImage = -1,
268 wxTreeItemData *data = NULL)
269 {
270 return DoInsertItem(parent, pos, text, image, selImage, data);
271 }
272
273 // insert a new item in as the last child of the parent
274 wxTreeItemId AppendItem(const wxTreeItemId& parent,
275 const wxString& text,
276 int image = -1, int selImage = -1,
277 wxTreeItemData *data = NULL)
278 {
279 return DoInsertItem(parent, (size_t)-1, text, image, selImage, data);
280 }
281
282 // delete this item and associated data if any
283 virtual void Delete(const wxTreeItemId& item) = 0;
284 // delete all children (but don't delete the item itself)
285 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
286 virtual void DeleteChildren(const wxTreeItemId& item) = 0;
287 // delete all items from the tree
288 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
289 virtual void DeleteAllItems() = 0;
290
291 // expand this item
292 virtual void Expand(const wxTreeItemId& item) = 0;
bcac8161 293 // expand the item and all its children recursively
70934138
VZ
294 void ExpandAllChildren(const wxTreeItemId& item);
295 // expand all items
296 void ExpandAll();
8cee4a30
VZ
297 // collapse the item without removing its children
298 virtual void Collapse(const wxTreeItemId& item) = 0;
bcac8161 299 // collapse the item and all its children
9248adc8
VZ
300 void CollapseAllChildren(const wxTreeItemId& item);
301 // collapse all items
302 void CollapseAll();
8cee4a30
VZ
303 // collapse the item and remove all children
304 virtual void CollapseAndReset(const wxTreeItemId& item) = 0;
305 // toggles the current state
306 virtual void Toggle(const wxTreeItemId& item) = 0;
307
308 // remove the selection from currently selected item (if any)
309 virtual void Unselect() = 0;
310 // unselect all items (only makes sense for multiple selection control)
311 virtual void UnselectAll() = 0;
312 // select this item
313 virtual void SelectItem(const wxTreeItemId& item, bool select = true) = 0;
314 // unselect this item
315 void UnselectItem(const wxTreeItemId& item) { SelectItem(item, false); }
316 // toggle item selection
317 void ToggleItemSelection(const wxTreeItemId& item)
318 {
319 SelectItem(item, !IsSelected(item));
320 }
321
322 // make sure this item is visible (expanding the parent item and/or
323 // scrolling to this item if necessary)
324 virtual void EnsureVisible(const wxTreeItemId& item) = 0;
325 // scroll to this item (but don't expand its parent)
326 virtual void ScrollTo(const wxTreeItemId& item) = 0;
327
328 // start editing the item label: this (temporarily) replaces the item
329 // with a one line edit control. The item will be selected if it hadn't
330 // been before. textCtrlClass parameter allows you to create an edit
331 // control of arbitrary user-defined class deriving from wxTextCtrl.
332 virtual wxTextCtrl *EditLabel(const wxTreeItemId& item,
333 wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl)) = 0;
334 // returns the same pointer as StartEdit() if the item is being edited,
335 // NULL otherwise (it's assumed that no more than one item may be
336 // edited simultaneously)
337 virtual wxTextCtrl *GetEditControl() const = 0;
338 // end editing and accept or discard the changes to item label
339 virtual void EndEditLabel(const wxTreeItemId& item,
340 bool discardChanges = false) = 0;
341
342 // sorting
343 // -------
344
345 // this function is called to compare 2 items and should return -1, 0
346 // or +1 if the first item is less than, equal to or greater than the
347 // second one. The base class version performs alphabetic comparaison
348 // of item labels (GetText)
349 virtual int OnCompareItems(const wxTreeItemId& item1,
350 const wxTreeItemId& item2)
351 {
352 return wxStrcmp(GetItemText(item1), GetItemText(item2));
353 }
354
355 // sort the children of this item using OnCompareItems
356 //
357 // NB: this function is not reentrant and not MT-safe (FIXME)!
358 virtual void SortChildren(const wxTreeItemId& item) = 0;
359
360 // items geometry
361 // --------------
362
363 // determine to which item (if any) belongs the given point (the
364 // coordinates specified are relative to the client area of tree ctrl)
365 // and, in the second variant, fill the flags parameter with a bitmask
366 // of wxTREE_HITTEST_xxx constants.
be0e5d69 367 wxTreeItemId HitTest(const wxPoint& point) const
22574b4a 368 { int dummy; return DoTreeHitTest(point, dummy); }
be0e5d69 369 wxTreeItemId HitTest(const wxPoint& point, int& flags) const
22574b4a 370 { return DoTreeHitTest(point, flags); }
8cee4a30
VZ
371
372 // get the bounding rectangle of the item (or of its label only)
373 virtual bool GetBoundingRect(const wxTreeItemId& item,
374 wxRect& rect,
375 bool textOnly = false) const = 0;
376
377
378 // implementation
379 // --------------
380
381 virtual bool ShouldInheritColours() const { return false; }
382
7c384067
JS
383 // hint whether to calculate best size quickly or accurately
384 void SetQuickBestSize(bool q) { m_quickBestSize = q; }
385 bool GetQuickBestSize() const { return m_quickBestSize; }
386
8cee4a30
VZ
387protected:
388 virtual wxSize DoGetBestSize() const;
389
390 // common part of Append/Prepend/InsertItem()
391 //
392 // pos is the position at which to insert the item or (size_t)-1 to append
393 // it to the end
394 virtual wxTreeItemId DoInsertItem(const wxTreeItemId& parent,
395 size_t pos,
396 const wxString& text,
397 int image, int selImage,
398 wxTreeItemData *data) = 0;
399
400 // and this function implements overloaded InsertItem() taking wxTreeItemId
401 // (it can't be called InsertItem() as we'd have virtual function hiding
402 // problem in derived classes then)
403 virtual wxTreeItemId DoInsertAfter(const wxTreeItemId& parent,
404 const wxTreeItemId& idPrevious,
405 const wxString& text,
406 int image = -1, int selImage = -1,
407 wxTreeItemData *data = NULL) = 0;
408
409 // real HitTest() implementation: again, can't be called just HitTest()
410 // because it's overloaded and so the non-virtual overload would be hidden
22574b4a 411 // (and can't be called DoHitTest() because this is already in wxWindow)
be0e5d69
VZ
412 virtual wxTreeItemId DoTreeHitTest(const wxPoint& point,
413 int& flags) const = 0;
8cee4a30
VZ
414
415
416 wxImageList *m_imageListNormal, // images for tree elements
417 *m_imageListState; // special images for app defined states
418 bool m_ownsImageListNormal,
419 m_ownsImageListState;
420
421 // spacing between left border and the text
b220b1a2 422 unsigned int m_spacing;
8cee4a30 423
7c384067
JS
424 // whether full or quick calculation is done in DoGetBestSize
425 bool m_quickBestSize;
426
8cee4a30
VZ
427
428 DECLARE_NO_COPY_CLASS(wxTreeCtrlBase)
429};
430
c193b707
VZ
431// ----------------------------------------------------------------------------
432// include the platform-dependent wxTreeCtrl class
433// ----------------------------------------------------------------------------
434
3e6e2754
JS
435#if defined(__WXUNIVERSAL__)
436 #include "wx/generic/treectlg.h"
4055ed82 437#elif defined(__WXPALMOS__)
b220b1a2 438 #include "wx/palmos/treectrl.h"
3e6e2754 439#elif defined(__WXMSW__)
b220b1a2 440 #include "wx/msw/treectrl.h"
2049ba38 441#elif defined(__WXMOTIF__)
484523cf 442 #include "wx/generic/treectlg.h"
2049ba38 443#elif defined(__WXGTK__)
484523cf 444 #include "wx/generic/treectlg.h"
34138703 445#elif defined(__WXMAC__)
484523cf 446 #include "wx/generic/treectlg.h"
8d0eaedd
DE
447#elif defined(__WXCOCOA__)
448 #include "wx/generic/treectlg.h"
1777b9bb 449#elif defined(__WXPM__)
dd133a20 450 #include "wx/generic/treectlg.h"
c801d85f
KB
451#endif
452
b220b1a2 453#endif // wxUSE_TREECTRL
aad0fe4b 454
b220b1a2 455#endif // _WX_TREECTRL_H_BASE_