1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxTreeCtrl class
4 // Author: Julian Smart
5 // Modified by: Vadim Zeitlin to be less MSW-specific on 10/10/98
8 // Copyright: (c) Julian Smart and Markus Holzem
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_TREECTRL_H_
13 #define _WX_TREECTRL_H_
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
20 #pragma interface "treectrl.h"
23 #include "wx/textctrl.h"
26 // Cygwin windows.h defines these identifiers
31 // the type for "untyped" data
32 typedef long wxDataType
;
35 class WXDLLEXPORT wxImageList
;
36 struct WXDLLEXPORT wxTreeViewItem
;
38 // a callback function used for sorting tree items, it should return -1 if the
39 // first item precedes the second, +1 if the second precedes the first or 0 if
43 // ----------------------------------------------------------------------------
45 // ----------------------------------------------------------------------------
47 // values for the `flags' parameter of wxTreeCtrl::HitTest() which determine
48 // where exactly the specified point is situated:
49 // above the client area.
50 static const int wxTREE_HITTEST_ABOVE
= 0x0001;
51 // below the client area.
52 static const int wxTREE_HITTEST_BELOW
= 0x0002;
53 // in the client area but below the last item.
54 static const int wxTREE_HITTEST_NOWHERE
= 0x0004;
55 // on the button associated with an item.
56 static const int wxTREE_HITTEST_ONITEMBUTTON
= 0x0010;
57 // on the bitmap associated with an item.
58 static const int wxTREE_HITTEST_ONITEMICON
= 0x0020;
59 // in the indentation associated with an item.
60 static const int wxTREE_HITTEST_ONITEMINDENT
= 0x0040;
61 // on the label (string) associated with an item.
62 static const int wxTREE_HITTEST_ONITEMLABEL
= 0x0080;
63 // in the area to the right of an item.
64 static const int wxTREE_HITTEST_ONITEMRIGHT
= 0x0100;
65 // on the state icon for a tree view item that is in a user-defined state.
66 static const int wxTREE_HITTEST_ONITEMSTATEICON
= 0x0200;
67 // to the right of the client area.
68 static const int wxTREE_HITTEST_TOLEFT
= 0x0400;
69 // to the left of the client area.
70 static const int wxTREE_HITTEST_TORIGHT
= 0x0800;
71 // anywhere on the item
72 static const int wxTREE_HITTEST_ONITEM
= wxTREE_HITTEST_ONITEMICON
|
73 wxTREE_HITTEST_ONITEMLABEL
|
74 wxTREE_HITTEST_ONITEMSTATEICON
;
76 // NB: all the following flags are for compatbility only and will be removed in the
79 // flags for deprecated `Expand(int action)'
83 wxTREE_EXPAND_COLLAPSE
,
84 wxTREE_EXPAND_COLLAPSE_RESET
,
88 // flags for deprecated InsertItem() variant
89 #define wxTREE_INSERT_FIRST 0xFFFF0001
90 #define wxTREE_INSERT_LAST 0xFFFF0002
92 // ----------------------------------------------------------------------------
93 // wxTreeItemId identifies an element of the tree. In this implementation, it's
94 // just a trivial wrapper around Win32 HTREEITEM. It's opaque for the
96 // ----------------------------------------------------------------------------
97 class WXDLLEXPORT wxTreeItemId
101 // 0 is invalid value for HTREEITEM
102 wxTreeItemId() { m_itemId
= 0; }
104 // default copy ctor/assignment operator are ok for us
107 // is this a valid tree item?
108 bool IsOk() const { return m_itemId
!= 0; }
110 // conversion to/from either real (system-dependent) tree item id or
111 // to "long" which used to be the type for tree item ids in previous
112 // versions of wxWindows
114 // for wxTreeCtrl usage only
115 wxTreeItemId(WXHTREEITEM itemId
) { m_itemId
= (long)itemId
; }
116 operator WXHTREEITEM() const { return (WXHTREEITEM
)m_itemId
; }
118 void operator=(WXHTREEITEM item
) { m_itemId
= (long) item
; }
124 // ----------------------------------------------------------------------------
125 // wxTreeItemData is some (arbitrary) user class associated with some item. The
126 // main advantage of having this class (compared to old untyped interface) is
127 // that wxTreeItemData's are destroyed automatically by the tree and, as this
128 // class has virtual dtor, it means that the memory will be automatically
129 // freed. OTOH, we don't just use wxObject instead of wxTreeItemData because
130 // the size of this class is critical: in any real application, each tree leaf
131 // will have wxTreeItemData associated with it and number of leaves may be
134 // Because the objects of this class are deleted by the tree, they should
135 // always be allocated on the heap!
136 // ----------------------------------------------------------------------------
137 class WXDLLEXPORT wxTreeItemData
: private wxTreeItemId
140 // default ctor/copy ctor/assignment operator are ok
142 // dtor is virtual and all the items are deleted by the tree control when
143 // it's deleted, so you normally don't have to care about freeing memory
144 // allocated in your wxTreeItemData-derived class
145 virtual ~wxTreeItemData() { }
147 // accessors: set/get the item associated with this node
148 void SetId(const wxTreeItemId
& id
) { m_itemId
= id
; }
150 const wxTreeItemId
GetId() const { return m_itemId
; }
152 const wxTreeItemId
& GetId() const { return (wxTreeItemId
&) m_itemId
; }
156 // ----------------------------------------------------------------------------
158 // ----------------------------------------------------------------------------
159 class WXDLLEXPORT wxTreeCtrl
: public wxControl
164 wxTreeCtrl() { Init(); }
166 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
167 const wxPoint
& pos
= wxDefaultPosition
,
168 const wxSize
& size
= wxDefaultSize
,
169 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
170 const wxValidator
& validator
= wxDefaultValidator
,
171 const wxString
& name
= "wxTreeCtrl")
173 Create(parent
, id
, pos
, size
, style
, validator
, name
);
176 virtual ~wxTreeCtrl();
178 bool Create(wxWindow
*parent
, wxWindowID id
= -1,
179 const wxPoint
& pos
= wxDefaultPosition
,
180 const wxSize
& size
= wxDefaultSize
,
181 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
182 const wxValidator
& validator
= wxDefaultValidator
,
183 const wxString
& name
= "wxTreeCtrl");
188 // get the total number of items in the control
189 size_t GetCount() const;
191 // indent is the number of pixels the children are indented relative to
192 // the parents position. SetIndent() also redraws the control
194 unsigned int GetIndent() const;
195 void SetIndent(unsigned int indent
);
197 // spacing is the number of pixels between the start and the Text
198 // not implemented under wxMSW
199 unsigned int GetSpacing() const { return 18; } // return wxGTK default
200 void SetSpacing(unsigned int ) {}
202 // image list: these functions allow to associate an image list with
203 // the control and retrieve it. Note that the control does _not_ delete
204 // the associated image list when it's deleted in order to allow image
205 // lists to be shared between different controls.
207 // The normal image list is for the icons which correspond to the
208 // normal tree item state (whether it is selected or not).
209 // Additionally, the application might choose to show a state icon
210 // which corresponds to an app-defined item state (for example,
211 // checked/unchecked) which are taken from the state image list.
212 wxImageList
*GetImageList() const;
213 wxImageList
*GetStateImageList() const;
215 void SetImageList(wxImageList
*imageList
);
216 void SetStateImageList(wxImageList
*imageList
);
218 // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
219 // member functions of wxTreeItem because they must know the tree the item
220 // belongs to for Windows implementation and storing the pointer to
221 // wxTreeCtrl in each wxTreeItem is just too much waste.
226 // retrieve items label
227 wxString
GetItemText(const wxTreeItemId
& item
) const;
228 // get the normal item image
229 int GetItemImage(const wxTreeItemId
& item
) const;
230 // get the selected item image
231 int GetItemSelectedImage(const wxTreeItemId
& item
) const;
232 // get the data associated with the item
233 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
239 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
240 // set the normal item image
241 void SetItemImage(const wxTreeItemId
& item
, int image
);
242 // set the selected item image
243 void SetItemSelectedImage(const wxTreeItemId
& item
, int image
);
244 // associate some data with the item
245 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
247 // force appearance of [+] button near the item. This is useful to
248 // allow the user to expand the items which don't have any children now
249 // - but instead add them only when needed, thus minimizing memory
250 // usage and loading time.
251 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= TRUE
);
253 // the item will be shown in bold
254 void SetItemBold(const wxTreeItemId
& item
, bool bold
= TRUE
);
256 // the item will be shown with a drop highlight
257 void SetItemDropHighlight(const wxTreeItemId
& item
, bool highlight
= TRUE
);
259 // item status inquiries
260 // ---------------------
262 // is the item visible (it might be outside the view or not expanded)?
263 bool IsVisible(const wxTreeItemId
& item
) const;
264 // does the item has any children?
265 bool ItemHasChildren(const wxTreeItemId
& item
) const;
266 // is the item expanded (only makes sense if HasChildren())?
267 bool IsExpanded(const wxTreeItemId
& item
) const;
268 // is this item currently selected (the same as has focus)?
269 bool IsSelected(const wxTreeItemId
& item
) const;
270 // is item text in bold font?
271 bool IsBold(const wxTreeItemId
& item
) const;
273 // number of children
274 // ------------------
276 // if 'recursively' is FALSE, only immediate children count, otherwise
277 // the returned number is the number of all items in this branch
278 size_t GetChildrenCount(const wxTreeItemId
& item
, bool recursively
= TRUE
);
283 // wxTreeItemId.IsOk() will return FALSE if there is no such item
285 // get the root tree item
286 wxTreeItemId
GetRootItem() const;
288 // get the item currently selected (may return NULL if no selection)
289 wxTreeItemId
GetSelection() const;
291 // get the parent of this item (may return NULL if root)
292 wxTreeItemId
GetParent(const wxTreeItemId
& item
) const;
294 // for this enumeration function you must pass in a "cookie" parameter
295 // which is opaque for the application but is necessary for the library
296 // to make these functions reentrant (i.e. allow more than one
297 // enumeration on one and the same object simultaneously). Of course,
298 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
301 // get the first child of this item
302 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
, long& _cookie
) const;
303 // get the next child
304 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
, long& _cookie
) const;
305 // get the last child of this item - this method doesn't use cookies
306 wxTreeItemId
GetLastChild(const wxTreeItemId
& item
) const;
308 // get the next sibling of this item
309 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
310 // get the previous sibling
311 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
313 // get first visible item
314 wxTreeItemId
GetFirstVisibleItem() const;
315 // get the next visible item: item must be visible itself!
316 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
317 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
318 // get the previous visible item: item must be visible itself!
319 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
324 // add the root node to the tree
325 wxTreeItemId
AddRoot(const wxString
& text
,
326 int image
= -1, int selectedImage
= -1,
327 wxTreeItemData
*data
= NULL
);
329 // insert a new item in as the first child of the parent
330 wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
331 const wxString
& text
,
332 int image
= -1, int selectedImage
= -1,
333 wxTreeItemData
*data
= NULL
);
335 // insert a new item after a given one
336 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
337 const wxTreeItemId
& idPrevious
,
338 const wxString
& text
,
339 int image
= -1, int selectedImage
= -1,
340 wxTreeItemData
*data
= NULL
);
342 // insert a new item in as the last child of the parent
343 wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
344 const wxString
& text
,
345 int image
= -1, int selectedImage
= -1,
346 wxTreeItemData
*data
= NULL
);
348 // delete this item and associated data if any
349 void Delete(const wxTreeItemId
& item
);
350 // delete all children (but don't delete the item itself)
351 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
352 void DeleteChildren(const wxTreeItemId
& item
);
353 // delete all items from the tree
354 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
355 void DeleteAllItems();
358 void Expand(const wxTreeItemId
& item
);
359 // collapse the item without removing its children
360 void Collapse(const wxTreeItemId
& item
);
361 // collapse the item and remove all children
362 void CollapseAndReset(const wxTreeItemId
& item
);
363 // toggles the current state
364 void Toggle(const wxTreeItemId
& item
);
366 // remove the selection from currently selected item (if any)
369 void SelectItem(const wxTreeItemId
& item
);
370 // make sure this item is visible (expanding the parent item and/or
371 // scrolling to this item if necessary)
372 void EnsureVisible(const wxTreeItemId
& item
);
373 // scroll to this item (but don't expand its parent)
374 void ScrollTo(const wxTreeItemId
& item
);
376 // start editing the item label: this (temporarily) replaces the item
377 // with a one line edit control. The item will be selected if it hadn't
378 // been before. textCtrlClass parameter allows you to create an edit
379 // control of arbitrary user-defined class deriving from wxTextCtrl.
380 wxTextCtrl
* EditLabel(const wxTreeItemId
& item
,
381 wxClassInfo
* textCtrlClass
= CLASSINFO(wxTextCtrl
));
382 // returns the same pointer as StartEdit() if the item is being edited,
383 // NULL otherwise (it's assumed that no more than one item may be
384 // edited simultaneously)
385 wxTextCtrl
* GetEditControl() const;
386 // end editing and accept or discard the changes to item label
387 void EndEditLabel(const wxTreeItemId
& item
, bool discardChanges
= FALSE
);
390 // this function is called to compare 2 items and should return -1, 0
391 // or +1 if the first item is less than, equal to or greater than the
392 // second one. The base class version performs alphabetic comparaison
393 // of item labels (GetText)
394 virtual int OnCompareItems(const wxTreeItemId
& item1
,
395 const wxTreeItemId
& item2
);
396 // sort the children of this item using OnCompareItems
398 // NB: this function is not reentrant and not MT-safe (FIXME)!
399 void SortChildren(const wxTreeItemId
& item
);
404 // determine to which item (if any) belongs the given point (the
405 // coordinates specified are relative to the client area of tree ctrl)
406 // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx
409 // The first function is more portable (because easier to implement
410 // on other platforms), but the second one returns some extra info.
411 wxTreeItemId
HitTest(const wxPoint
& point
)
412 { int dummy
; return HitTest(point
, dummy
); }
413 wxTreeItemId
HitTest(const wxPoint
& point
, int& flags
);
415 // get the bounding rectangle of the item (or of its label only)
416 bool GetBoundingRect(const wxTreeItemId
& item
,
418 bool textOnly
= FALSE
) const;
423 // these methods are deprecated and will be removed in future versions of
424 // wxWindows, they're here for compatibility only, don't use them in new
425 // code (the comments indicate why these methods are now useless and how to
428 // use Expand, Collapse, CollapseAndReset or Toggle
429 void ExpandItem(const wxTreeItemId
& item
, int action
);
431 // use AddRoot, PrependItem or AppendItem
432 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
433 const wxString
& text
,
434 int image
= -1, int selImage
= -1,
435 long insertAfter
= wxTREE_INSERT_LAST
);
437 // use Set/GetImageList and Set/GetStateImageList
438 wxImageList
*GetImageList(int) const
439 { return GetImageList(); }
440 void SetImageList(wxImageList
*imageList
, int)
441 { SetImageList(imageList
); }
445 virtual bool MSWCommand(WXUINT param
, WXWORD id
);
446 virtual bool MSWOnNotify(int idCtrl
, WXLPARAM lParam
, WXLPARAM
*result
);
449 // SetImageList helper
450 void SetAnyImageList(wxImageList
*imageList
, int which
);
452 wxTextCtrl
* m_textCtrl
; // used while editing the item label
453 wxImageList
*m_imageListNormal
, // images for tree elements
454 *m_imageListState
; // special images for app defined states
457 // the common part of all ctors
461 inline bool DoGetItem(wxTreeViewItem
*tvItem
) const;
462 inline void DoSetItem(wxTreeViewItem
*tvItem
);
464 inline void DoExpand(const wxTreeItemId
& item
, int flag
);
466 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
467 wxTreeItemId hInsertAfter
,
468 const wxString
& text
,
469 int image
, int selectedImage
,
470 wxTreeItemData
*data
);
472 void DeleteTextCtrl();
474 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)