1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxTreeCtrl class
4 // Author: Robert Roebling
8 // Copyright: (c) 1997,1998 Robert Roebling
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _GENERIC_TREECTRL_H_
13 #define _GENERIC_TREECTRL_H_
16 #pragma interface "treectrl.h"
20 #include "wx/string.h"
21 #include "wx/object.h"
23 #include "wx/scrolwin.h"
24 #include "wx/textctrl.h"
26 // -----------------------------------------------------------------------------
27 // forward declaration
28 // -----------------------------------------------------------------------------
31 class wxGenericTreeItem
;
34 typedef int (*wxTreeItemCmpFunc
)(wxTreeItemData
*item1
, wxTreeItemData
*item2
);
36 // -----------------------------------------------------------------------------
37 // wxTreeItemId - unique identifier of a tree element
38 // -----------------------------------------------------------------------------
40 class WXDLLEXPORT wxTreeItemId
42 friend class wxTreeCtrl
;
43 friend class wxTreeEvent
;
46 // 0 is invalid value for HTREEITEM
47 wxTreeItemId() { m_pItem
= 0; }
49 // default copy ctor/assignment operator are ok for us
52 // is this a valid tree item?
53 bool IsOk() const { return m_pItem
!= 0; }
55 // deprecated: only for compatibility
56 wxTreeItemId(long itemId
) { m_pItem
= (wxGenericTreeItem
*)itemId
; }
57 operator long() const { return (long)m_pItem
; }
59 //protected: // not for gcc
60 // for wxTreeCtrl usage only
61 wxTreeItemId(wxGenericTreeItem
*pItem
) { m_pItem
= pItem
; }
63 wxGenericTreeItem
*m_pItem
;
66 // ----------------------------------------------------------------------------
67 // wxTreeItemData is some (arbitrary) user class associated with some item.
69 // Because the objects of this class are deleted by the tree, they should
70 // always be allocated on the heap!
71 // ----------------------------------------------------------------------------
72 class WXDLLEXPORT wxTreeItemData
: public wxClientData
74 friend class wxTreeCtrl
;
76 // creation/destruction
77 // --------------------
81 // default copy ctor/assignment operator are ok
83 // accessor: get the item associated with us
84 const wxTreeItemId
& GetId() const { return m_pItem
; }
85 void SetId(const wxTreeItemId
& id
) { m_pItem
= id
; }
91 // -----------------------------------------------------------------------------
92 // wxTreeEvent - the event generated by the tree control
93 // -----------------------------------------------------------------------------
94 class WXDLLEXPORT wxTreeEvent
: public wxCommandEvent
96 friend class wxTreeCtrl
;
98 wxTreeEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
101 // get the item on which the operation was performed or the newly
102 // selected item for wxEVT_COMMAND_TREE_SEL_CHANGED/ING events
103 wxTreeItemId
GetItem() const { return m_item
; }
105 // for wxEVT_COMMAND_TREE_SEL_CHANGED/ING events, get the previously
107 wxTreeItemId
GetOldItem() const { return m_itemOld
; }
109 // the point where the mouse was when the drag operation started (for
110 // wxEVT_COMMAND_TREE_BEGIN_(R)DRAG events only)
111 wxPoint
GetPoint() const { return m_pointDrag
; }
113 // keyboard code (for wxEVT_COMMAND_TREE_KEY_DOWN only)
114 int GetCode() const { return m_code
; }
116 // set return code for wxEVT_COMMAND_TREE_ITEM_{EXPAND|COLLAPS}ING events
117 // call this to forbid the change in item status
118 void Veto() { m_code
= TRUE
; }
120 // for implementation usage only
121 bool WasVetoed() const { return m_code
; }
124 // @@ we could save some space by using union here
130 DECLARE_DYNAMIC_CLASS(wxTreeEvent
)
133 typedef void (wxEvtHandler::*wxTreeEventFunction
)(wxTreeEvent
&);
135 // ----------------------------------------------------------------------------
136 // macros for handling tree control events
137 // ----------------------------------------------------------------------------
139 // GetItem() returns the item being dragged, GetPoint() the mouse coords
140 #define EVT_TREE_BEGIN_DRAG(id, fn) { wxEVT_COMMAND_TREE_BEGIN_DRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
141 #define EVT_TREE_BEGIN_RDRAG(id, fn) { wxEVT_COMMAND_TREE_BEGIN_RDRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
143 // GetItem() returns the itme whose label is being edited
144 #define EVT_TREE_BEGIN_LABEL_EDIT(id, fn) { wxEVT_COMMAND_TREE_BEGIN_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
145 #define EVT_TREE_END_LABEL_EDIT(id, fn) { wxEVT_COMMAND_TREE_END_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
147 // provide/update information about GetItem() item
148 #define EVT_TREE_GET_INFO(id, fn) { wxEVT_COMMAND_TREE_GET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
149 #define EVT_TREE_SET_INFO(id, fn) { wxEVT_COMMAND_TREE_SET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
151 // GetItem() is the item being expanded/collapsed, the "ING" versions can use
152 #define EVT_TREE_ITEM_EXPANDED(id, fn) { wxEVT_COMMAND_TREE_ITEM_EXPANDED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
153 #define EVT_TREE_ITEM_EXPANDING(id, fn) { wxEVT_COMMAND_TREE_ITEM_EXPANDING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
154 #define EVT_TREE_ITEM_COLLAPSED(id, fn) { wxEVT_COMMAND_TREE_ITEM_COLLAPSED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
155 #define EVT_TREE_ITEM_COLLAPSING(id, fn) { wxEVT_COMMAND_TREE_ITEM_COLLAPSING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
157 // GetOldItem() is the item which had the selection previously, GetItem() is
158 // the item which acquires selection
159 #define EVT_TREE_SEL_CHANGED(id, fn) { wxEVT_COMMAND_TREE_SEL_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
160 #define EVT_TREE_SEL_CHANGING(id, fn) { wxEVT_COMMAND_TREE_SEL_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
162 // GetCode() returns the key code
163 // NB: this is the only message for which GetItem() is invalid (you may get the
164 // item from GetSelection())
165 #define EVT_TREE_KEY_DOWN(id, fn) { wxEVT_COMMAND_TREE_KEY_DOWN, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
167 // GetItem() returns the item being deleted, the associated data (if any) will
168 // be deleted just after the return of this event handler (if any)
169 #define EVT_TREE_DELETE_ITEM(id, fn) { wxEVT_COMMAND_TREE_DELETE_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
171 // -----------------------------------------------------------------------------
172 // wxTreeCtrl - the tree control
173 // -----------------------------------------------------------------------------
175 class WXDLLEXPORT wxTreeCtrl
: public wxScrolledWindow
180 wxTreeCtrl() { Init(); }
182 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
183 const wxPoint
& pos
= wxDefaultPosition
,
184 const wxSize
& size
= wxDefaultSize
,
185 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
186 const wxString
& name
= "wxTreeCtrl")
188 Create(parent
, id
, pos
, size
, style
, name
);
191 virtual ~wxTreeCtrl();
193 bool Create(wxWindow
*parent
, wxWindowID id
= -1,
194 const wxPoint
& pos
= wxDefaultPosition
,
195 const wxSize
& size
= wxDefaultSize
,
196 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
197 const wxString
& name
= "wxTreeCtrl");
202 // get the total number of items in the control
203 size_t GetCount() const;
205 // indent is the number of pixels the children are indented relative to
206 // the parents position. SetIndent() also redraws the control
208 unsigned int GetIndent() const { return m_indent
; }
209 void SetIndent(unsigned int indent
);
211 // image list: these functions allow to associate an image list with
212 // the control and retrieve it. Note that the control does _not_ delete
213 // the associated image list when it's deleted in order to allow image
214 // lists to be shared between different controls.
216 // The normal image list is for the icons which correspond to the
217 // normal tree item state (whether it is selected or not).
218 // Additionally, the application might choose to show a state icon
219 // which corresponds to an app-defined item state (for example,
220 // checked/unchecked) which are taken from the state image list.
221 wxImageList
*GetImageList() const;
222 wxImageList
*GetStateImageList() const;
224 void SetImageList(wxImageList
*imageList
);
225 void SetStateImageList(wxImageList
*imageList
);
227 // Functions to work with tree ctrl items.
232 // retrieve items label
233 wxString
GetItemText(const wxTreeItemId
& item
) const;
234 // get the normal item image
235 int GetItemImage(const wxTreeItemId
& item
) const;
236 // get the selected item image
237 int GetItemSelectedImage(const wxTreeItemId
& item
) const;
238 // get the data associated with the item
239 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
245 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
246 // set the normal item image
247 void SetItemImage(const wxTreeItemId
& item
, int image
);
248 // set the selected item image
249 void SetItemSelectedImage(const wxTreeItemId
& item
, int image
);
250 // associate some data with the item
251 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
253 // force appearance of [+] button near the item. This is useful to
254 // allow the user to expand the items which don't have any children now
255 // - but instead add them only when needed, thus minimizing memory
256 // usage and loading time.
257 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= TRUE
);
259 // the item will be shown in bold
260 void SetItemBold(const wxTreeItemId
& item
, bool bold
= TRUE
);
262 // item status inquiries
263 // ---------------------
265 // is the item visible (it might be outside the view or not expanded)?
266 bool IsVisible(const wxTreeItemId
& item
) const;
267 // does the item has any children?
268 bool HasChildren(const wxTreeItemId
& item
) const
269 { return ItemHasChildren(item
); }
270 bool ItemHasChildren(const wxTreeItemId
& item
) const;
271 // is the item expanded (only makes sense if HasChildren())?
272 bool IsExpanded(const wxTreeItemId
& item
) const;
273 // is this item currently selected (the same as has focus)?
274 bool IsSelected(const wxTreeItemId
& item
) const;
275 // is item text in bold font?
276 bool IsBold(const wxTreeItemId
& item
) const;
278 // number of children
279 // ------------------
281 // if 'recursively' is FALSE, only immediate children count, otherwise
282 // the returned number is the number of all items in this branch
283 size_t GetChildrenCount(const wxTreeItemId
& item
, bool recursively
= TRUE
);
288 // wxTreeItemId.IsOk() will return FALSE if there is no such item
290 // get the root tree item
291 wxTreeItemId
GetRootItem() const { return m_anchor
; }
293 // get the item currently selected (may return NULL if no selection)
294 wxTreeItemId
GetSelection() const { return m_current
; }
296 // get the parent of this item (may return NULL if root)
297 wxTreeItemId
GetParent(const wxTreeItemId
& item
) const;
299 // for this enumeration function you must pass in a "cookie" parameter
300 // which is opaque for the application but is necessary for the library
301 // to make these functions reentrant (i.e. allow more than one
302 // enumeration on one and the same object simultaneously). Of course,
303 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
306 // get the first child of this item
307 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
, long& cookie
) const;
308 // get the next child
309 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
, long& cookie
) const;
311 // get the next sibling of this item
312 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
313 // get the previous sibling
314 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
316 // get first visible item
317 wxTreeItemId
GetFirstVisibleItem() const;
318 // get the next visible item: item must be visible itself!
319 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
320 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
321 // get the previous visible item: item must be visible itself!
322 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
327 // add the root node to the tree
328 wxTreeItemId
AddRoot(const wxString
& text
,
329 int image
= -1, int selectedImage
= -1,
330 wxTreeItemData
*data
= NULL
);
332 // insert a new item in as the first child of the parent
333 wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
334 const wxString
& text
,
335 int image
= -1, int selectedImage
= -1,
336 wxTreeItemData
*data
= NULL
);
338 // insert a new item after a given one
339 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
340 const wxTreeItemId
& idPrevious
,
341 const wxString
& text
,
342 int image
= -1, int selectedImage
= -1,
343 wxTreeItemData
*data
= NULL
);
345 // insert a new item in as the last child of the parent
346 wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
347 const wxString
& text
,
348 int image
= -1, int selectedImage
= -1,
349 wxTreeItemData
*data
= NULL
);
351 // delete this item and associated data if any
352 void Delete(const wxTreeItemId
& item
);
353 // delete all items from the tree
354 void DeleteAllItems();
357 void Expand(const wxTreeItemId
& item
);
358 // collapse the item without removing its children
359 void Collapse(const wxTreeItemId
& item
);
360 // collapse the item and remove all children
361 void CollapseAndReset(const wxTreeItemId
& item
);
362 // toggles the current state
363 void Toggle(const wxTreeItemId
& item
);
365 // remove the selection from currently selected item (if any)
368 void SelectItem(const wxTreeItemId
& item
);
369 // make sure this item is visible (expanding the parent item and/or
370 // scrolling to this item if necessary)
371 void EnsureVisible(const wxTreeItemId
& item
);
372 // scroll to this item (but don't expand its parent)
373 void ScrollTo(const wxTreeItemId
& item
);
375 // start editing the item label: this (temporarily) replaces the item
376 // with a one line edit control. The item will be selected if it hadn't
377 // been before. textCtrlClass parameter allows you to create an edit
378 // control of arbitrary user-defined class deriving from wxTextCtrl.
379 wxTextCtrl
* EditLabel(const wxTreeItemId
& item
,
380 wxClassInfo
* textCtrlClass
= CLASSINFO(wxTextCtrl
));
381 // returns the same pointer as StartEdit() if the item is being edited,
382 // NULL otherwise (it's assumed that no more than one item may be
383 // edited simultaneously)
384 wxTextCtrl
* GetEditControl() const;
385 // end editing and accept or discard the changes to item label
386 void EndEditLabel(const wxTreeItemId
& item
, bool discardChanges
= FALSE
);
388 // sort the children of this item using the specified callback function
389 // (it should return -1, 0 or +1 as usual), if it's not specified
390 // alphabetical comparaison is performed.
392 // NB: this function is not reentrant!
393 void SortChildren(const wxTreeItemId
& item
,
394 wxTreeItemCmpFunc
*cmpFunction
= NULL
);
396 void OnPaint( wxPaintEvent
&event
);
397 void OnSetFocus( wxFocusEvent
&event
);
398 void OnKillFocus( wxFocusEvent
&event
);
399 void OnChar( wxKeyEvent
&event
);
400 void OnMouse( wxMouseEvent
&event
);
401 void OnIdle( wxIdleEvent
&event
);
404 wxGenericTreeItem
*m_anchor
;
405 wxGenericTreeItem
*m_current
;
408 int m_xScroll
,m_yScroll
;
409 unsigned int m_indent
;
412 wxBrush
*m_hilightBrush
;
413 wxImageList
*m_imageListNormal
,
416 // the common part of all ctors
420 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
422 const wxString
& text
,
423 int image
, int selectedImage
,
424 wxTreeItemData
*data
);
426 void AdjustMyScrollbars();
427 void PaintLevel( wxGenericTreeItem
*item
, wxDC
& dc
, int level
, int &y
);
428 void PaintItem( wxGenericTreeItem
*item
, wxDC
& dc
);
430 void CalculateLevel( wxGenericTreeItem
*item
, wxDC
&dc
, int level
, int &y
);
431 void CalculatePositions();
433 void RefreshSubtree( wxGenericTreeItem
*item
);
434 void RefreshLine( wxGenericTreeItem
*item
);
437 DECLARE_EVENT_TABLE()
438 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
441 #endif // _GENERIC_TREECTRL_H_