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 // -----------------------------------------------------------------------------
28 // -----------------------------------------------------------------------------
30 // values for the `flags' parameter of wxTreeCtrl::HitTest() which determine
31 // where exactly the specified point is situated:
32 static const int wxTREE_HITTEST_NOWHERE
= 0x0004;
33 // on the bitmap associated with an item.
34 static const int wxTREE_HITTEST_ONITEMICON
= 0x0020;
35 // on the label (string) associated with an item.
36 static const int wxTREE_HITTEST_ONITEMLABEL
= 0x0080;
37 // anywhere on the item
38 static const int wxTREE_HITTEST_ONITEM
= wxTREE_HITTEST_ONITEMICON
|
39 wxTREE_HITTEST_ONITEMLABEL
;
41 // -----------------------------------------------------------------------------
42 // forward declaration
43 // -----------------------------------------------------------------------------
46 class wxGenericTreeItem
;
49 typedef int (*wxTreeItemCmpFunc
)(wxTreeItemData
*item1
, wxTreeItemData
*item2
);
51 // -----------------------------------------------------------------------------
52 // wxTreeItemId - unique identifier of a tree element
53 // -----------------------------------------------------------------------------
55 class WXDLLEXPORT wxTreeItemId
57 friend class wxTreeCtrl
;
58 friend class wxTreeEvent
;
61 // 0 is invalid value for HTREEITEM
62 wxTreeItemId() { m_pItem
= 0; }
64 // default copy ctor/assignment operator are ok for us
67 // is this a valid tree item?
68 bool IsOk() const { return m_pItem
!= 0; }
70 // deprecated: only for compatibility
71 wxTreeItemId(long itemId
) { m_pItem
= (wxGenericTreeItem
*)itemId
; }
72 operator long() const { return (long)m_pItem
; }
74 //protected: // not for gcc
75 // for wxTreeCtrl usage only
76 wxTreeItemId(wxGenericTreeItem
*pItem
) { m_pItem
= pItem
; }
78 wxGenericTreeItem
*m_pItem
;
81 // ----------------------------------------------------------------------------
82 // wxTreeItemData is some (arbitrary) user class associated with some item.
84 // Because the objects of this class are deleted by the tree, they should
85 // always be allocated on the heap!
86 // ----------------------------------------------------------------------------
87 class WXDLLEXPORT wxTreeItemData
: public wxClientData
89 friend class wxTreeCtrl
;
91 // creation/destruction
92 // --------------------
96 // default copy ctor/assignment operator are ok
98 // accessor: get the item associated with us
99 const wxTreeItemId
& GetId() const { return m_pItem
; }
100 void SetId(const wxTreeItemId
& id
) { m_pItem
= id
; }
103 wxTreeItemId m_pItem
;
106 // -----------------------------------------------------------------------------
107 // wxTreeEvent - the event generated by the tree control
108 // -----------------------------------------------------------------------------
109 class WXDLLEXPORT wxTreeEvent
: public wxNotifyEvent
111 friend class wxTreeCtrl
;
113 wxTreeEvent(wxEventType commandType
= wxEVT_NULL
, int id
= 0);
116 // get the item on which the operation was performed or the newly
117 // selected item for wxEVT_COMMAND_TREE_SEL_CHANGED/ING events
118 wxTreeItemId
GetItem() const { return m_item
; }
120 // for wxEVT_COMMAND_TREE_SEL_CHANGED/ING events, get the previously
122 wxTreeItemId
GetOldItem() const { return m_itemOld
; }
124 // the point where the mouse was when the drag operation started (for
125 // wxEVT_COMMAND_TREE_BEGIN_(R)DRAG events only)
126 wxPoint
GetPoint() const { return m_pointDrag
; }
128 // keyboard code (for wxEVT_COMMAND_TREE_KEY_DOWN only)
129 int GetCode() const { return m_code
; }
131 // set return code for wxEVT_COMMAND_TREE_ITEM_{EXPAND|COLLAPS}ING events
132 // call this to forbid the change in item status
133 void Veto() { m_code
= TRUE
; }
135 // for implementation usage only
136 bool WasVetoed() const { return m_code
; }
139 // @@ we could save some space by using union here
145 DECLARE_DYNAMIC_CLASS(wxTreeEvent
)
148 typedef void (wxEvtHandler::*wxTreeEventFunction
)(wxTreeEvent
&);
150 // ----------------------------------------------------------------------------
151 // macros for handling tree control events
152 // ----------------------------------------------------------------------------
154 // GetItem() returns the item being dragged, GetPoint() the mouse coords
155 #define EVT_TREE_BEGIN_DRAG(id, fn) { wxEVT_COMMAND_TREE_BEGIN_DRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
156 #define EVT_TREE_BEGIN_RDRAG(id, fn) { wxEVT_COMMAND_TREE_BEGIN_RDRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
158 // GetItem() returns the itme whose label is being edited
159 #define EVT_TREE_BEGIN_LABEL_EDIT(id, fn) { wxEVT_COMMAND_TREE_BEGIN_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
160 #define EVT_TREE_END_LABEL_EDIT(id, fn) { wxEVT_COMMAND_TREE_END_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
162 // provide/update information about GetItem() item
163 #define EVT_TREE_GET_INFO(id, fn) { wxEVT_COMMAND_TREE_GET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
164 #define EVT_TREE_SET_INFO(id, fn) { wxEVT_COMMAND_TREE_SET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
166 // GetItem() is the item being expanded/collapsed, the "ING" versions can use
167 #define EVT_TREE_ITEM_EXPANDED(id, fn) { wxEVT_COMMAND_TREE_ITEM_EXPANDED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
168 #define EVT_TREE_ITEM_EXPANDING(id, fn) { wxEVT_COMMAND_TREE_ITEM_EXPANDING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
169 #define EVT_TREE_ITEM_COLLAPSED(id, fn) { wxEVT_COMMAND_TREE_ITEM_COLLAPSED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
170 #define EVT_TREE_ITEM_COLLAPSING(id, fn) { wxEVT_COMMAND_TREE_ITEM_COLLAPSING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
172 // GetOldItem() is the item which had the selection previously, GetItem() is
173 // the item which acquires selection
174 #define EVT_TREE_SEL_CHANGED(id, fn) { wxEVT_COMMAND_TREE_SEL_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
175 #define EVT_TREE_SEL_CHANGING(id, fn) { wxEVT_COMMAND_TREE_SEL_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
177 // GetCode() returns the key code
178 // NB: this is the only message for which GetItem() is invalid (you may get the
179 // item from GetSelection())
180 #define EVT_TREE_KEY_DOWN(id, fn) { wxEVT_COMMAND_TREE_KEY_DOWN, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
182 // GetItem() returns the item being deleted, the associated data (if any) will
183 // be deleted just after the return of this event handler (if any)
184 #define EVT_TREE_DELETE_ITEM(id, fn) { wxEVT_COMMAND_TREE_DELETE_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, (wxObject *) NULL },
186 // GetItem() returns the item that was activated (double click, enter, space)
187 #define EVT_TREE_ITEM_ACTIVATED(id, fn) { wxEVT_COMMAND_TREE_ITEM_ACTIVATED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxTreeEventFunction) & fn, NULL },
189 // -----------------------------------------------------------------------------
190 // wxTreeCtrl - the tree control
191 // -----------------------------------------------------------------------------
193 class WXDLLEXPORT wxTreeCtrl
: public wxScrolledWindow
198 wxTreeCtrl() { Init(); }
200 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
201 const wxPoint
& pos
= wxDefaultPosition
,
202 const wxSize
& size
= wxDefaultSize
,
203 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
204 const wxValidator
&validator
= wxDefaultValidator
,
205 const wxString
& name
= "wxTreeCtrl")
207 Create(parent
, id
, pos
, size
, style
, validator
, name
);
210 virtual ~wxTreeCtrl();
212 bool Create(wxWindow
*parent
, wxWindowID id
= -1,
213 const wxPoint
& pos
= wxDefaultPosition
,
214 const wxSize
& size
= wxDefaultSize
,
215 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
216 const wxValidator
&validator
= wxDefaultValidator
,
217 const wxString
& name
= "wxTreeCtrl");
222 // get the total number of items in the control
223 size_t GetCount() const;
225 // indent is the number of pixels the children are indented relative to
226 // the parents position. SetIndent() also redraws the control
228 unsigned int GetIndent() const { return m_indent
; }
229 void SetIndent(unsigned int indent
);
231 // image list: these functions allow to associate an image list with
232 // the control and retrieve it. Note that the control does _not_ delete
233 // the associated image list when it's deleted in order to allow image
234 // lists to be shared between different controls.
236 // The normal image list is for the icons which correspond to the
237 // normal tree item state (whether it is selected or not).
238 // Additionally, the application might choose to show a state icon
239 // which corresponds to an app-defined item state (for example,
240 // checked/unchecked) which are taken from the state image list.
241 wxImageList
*GetImageList() const;
242 wxImageList
*GetStateImageList() const;
244 void SetImageList(wxImageList
*imageList
);
245 void SetStateImageList(wxImageList
*imageList
);
247 // Functions to work with tree ctrl items.
252 // retrieve items label
253 wxString
GetItemText(const wxTreeItemId
& item
) const;
254 // get the normal item image
255 int GetItemImage(const wxTreeItemId
& item
) const;
256 // get the selected item image
257 int GetItemSelectedImage(const wxTreeItemId
& item
) const;
258 // get the data associated with the item
259 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
265 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
266 // set the normal item image
267 void SetItemImage(const wxTreeItemId
& item
, int image
);
268 // set the selected item image
269 void SetItemSelectedImage(const wxTreeItemId
& item
, int image
);
270 // associate some data with the item
271 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
273 // force appearance of [+] button near the item. This is useful to
274 // allow the user to expand the items which don't have any children now
275 // - but instead add them only when needed, thus minimizing memory
276 // usage and loading time.
277 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= TRUE
);
279 // the item will be shown in bold
280 void SetItemBold(const wxTreeItemId
& item
, bool bold
= TRUE
);
282 // item status inquiries
283 // ---------------------
285 // is the item visible (it might be outside the view or not expanded)?
286 bool IsVisible(const wxTreeItemId
& item
) const;
287 // does the item has any children?
288 bool HasChildren(const wxTreeItemId
& item
) const
289 { return ItemHasChildren(item
); }
290 bool ItemHasChildren(const wxTreeItemId
& item
) const;
291 // is the item expanded (only makes sense if HasChildren())?
292 bool IsExpanded(const wxTreeItemId
& item
) const;
293 // is this item currently selected (the same as has focus)?
294 bool IsSelected(const wxTreeItemId
& item
) const;
295 // is item text in bold font?
296 bool IsBold(const wxTreeItemId
& item
) const;
298 // number of children
299 // ------------------
301 // if 'recursively' is FALSE, only immediate children count, otherwise
302 // the returned number is the number of all items in this branch
303 size_t GetChildrenCount(const wxTreeItemId
& item
, bool recursively
= TRUE
);
308 // wxTreeItemId.IsOk() will return FALSE if there is no such item
310 // get the root tree item
311 wxTreeItemId
GetRootItem() const { return m_anchor
; }
313 // get the item currently selected (may return NULL if no selection)
314 wxTreeItemId
GetSelection() const { return m_current
; }
316 // get the parent of this item (may return NULL if root)
317 wxTreeItemId
GetParent(const wxTreeItemId
& item
) const;
319 // for this enumeration function you must pass in a "cookie" parameter
320 // which is opaque for the application but is necessary for the library
321 // to make these functions reentrant (i.e. allow more than one
322 // enumeration on one and the same object simultaneously). Of course,
323 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
326 // get the first child of this item
327 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
, long& cookie
) const;
328 // get the next child
329 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
, long& cookie
) const;
331 // get the next sibling of this item
332 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
333 // get the previous sibling
334 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
336 // get first visible item
337 wxTreeItemId
GetFirstVisibleItem() const;
338 // get the next visible item: item must be visible itself!
339 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
340 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
341 // get the previous visible item: item must be visible itself!
342 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
347 // add the root node to the tree
348 wxTreeItemId
AddRoot(const wxString
& text
,
349 int image
= -1, int selectedImage
= -1,
350 wxTreeItemData
*data
= NULL
);
352 // insert a new item in as the first child of the parent
353 wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
354 const wxString
& text
,
355 int image
= -1, int selectedImage
= -1,
356 wxTreeItemData
*data
= NULL
);
358 // insert a new item after a given one
359 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
360 const wxTreeItemId
& idPrevious
,
361 const wxString
& text
,
362 int image
= -1, int selectedImage
= -1,
363 wxTreeItemData
*data
= NULL
);
365 // insert a new item in as the last child of the parent
366 wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
367 const wxString
& text
,
368 int image
= -1, int selectedImage
= -1,
369 wxTreeItemData
*data
= NULL
);
371 // delete this item and associated data if any
372 void Delete(const wxTreeItemId
& item
);
373 // delete all items from the tree
374 void DeleteAllItems();
377 void Expand(const wxTreeItemId
& item
);
378 // collapse the item without removing its children
379 void Collapse(const wxTreeItemId
& item
);
380 // collapse the item and remove all children
381 void CollapseAndReset(const wxTreeItemId
& item
);
382 // toggles the current state
383 void Toggle(const wxTreeItemId
& item
);
385 // remove the selection from currently selected item (if any)
388 void SelectItem(const wxTreeItemId
& item
);
389 // make sure this item is visible (expanding the parent item and/or
390 // scrolling to this item if necessary)
391 void EnsureVisible(const wxTreeItemId
& item
);
392 // scroll to this item (but don't expand its parent)
393 void ScrollTo(const wxTreeItemId
& item
);
395 // The first function is more portable (because easier to implement
396 // on other platforms), but the second one returns some extra info.
397 wxTreeItemId
HitTest(const wxPoint
& point
)
398 { int dummy
; return HitTest(point
, dummy
); }
399 wxTreeItemId
HitTest(const wxPoint
& point
, int& flags
);
401 // start editing the item label: this (temporarily) replaces the item
402 // with a one line edit control. The item will be selected if it hadn't
403 // been before. textCtrlClass parameter allows you to create an edit
404 // control of arbitrary user-defined class deriving from wxTextCtrl.
405 wxTextCtrl
* EditLabel(const wxTreeItemId
& item
,
406 wxClassInfo
* textCtrlClass
= CLASSINFO(wxTextCtrl
));
407 // returns the same pointer as StartEdit() if the item is being edited,
408 // NULL otherwise (it's assumed that no more than one item may be
409 // edited simultaneously)
410 wxTextCtrl
* GetEditControl() const;
411 // end editing and accept or discard the changes to item label
412 void EndEditLabel(const wxTreeItemId
& item
, bool discardChanges
= FALSE
);
414 // sort the children of this item using the specified callback function
415 // (it should return -1, 0 or +1 as usual), if it's not specified
416 // alphabetical comparaison is performed.
418 // NB: this function is not reentrant!
419 void SortChildren(const wxTreeItemId
& item
,
420 wxTreeItemCmpFunc
*cmpFunction
= NULL
);
422 void OnPaint( wxPaintEvent
&event
);
423 void OnSetFocus( wxFocusEvent
&event
);
424 void OnKillFocus( wxFocusEvent
&event
);
425 void OnChar( wxKeyEvent
&event
);
426 void OnMouse( wxMouseEvent
&event
);
427 void OnIdle( wxIdleEvent
&event
);
430 wxGenericTreeItem
*m_anchor
;
431 wxGenericTreeItem
*m_current
;
434 int m_xScroll
,m_yScroll
;
435 unsigned int m_indent
;
438 wxBrush
*m_hilightBrush
;
439 wxImageList
*m_imageListNormal
,
442 // the common part of all ctors
446 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
448 const wxString
& text
,
449 int image
, int selectedImage
,
450 wxTreeItemData
*data
);
452 void AdjustMyScrollbars();
453 void PaintLevel( wxGenericTreeItem
*item
, wxDC
& dc
, int level
, int &y
);
454 void PaintItem( wxGenericTreeItem
*item
, wxDC
& dc
);
456 void CalculateLevel( wxGenericTreeItem
*item
, wxDC
&dc
, int level
, int &y
);
457 void CalculatePositions();
459 void RefreshSubtree( wxGenericTreeItem
*item
);
460 void RefreshLine( wxGenericTreeItem
*item
);
463 DECLARE_EVENT_TABLE()
464 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
467 #endif // _GENERIC_TREECTRL_H_