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 "treectlg.h"
20 #include "wx/string.h"
21 #include "wx/object.h"
23 #include "wx/scrolwin.h"
24 #include "wx/textctrl.h"
26 #include "wx/dynarray.h"
28 #include "wx/treebase.h"
30 // -----------------------------------------------------------------------------
31 // forward declaration
32 // -----------------------------------------------------------------------------
34 class WXDLLEXPORT wxImageList
;
35 class WXDLLEXPORT wxGenericTreeItem
;
37 class WXDLLEXPORT wxTreeItemData
;
39 class WXDLLEXPORT wxTreeRenameTimer
;
40 class WXDLLEXPORT wxTreeTextCtrl
;
42 // -----------------------------------------------------------------------------
43 // wxGenericTreeCtrl - the tree control
44 // -----------------------------------------------------------------------------
46 class WXDLLEXPORT wxGenericTreeCtrl
: public wxScrolledWindow
51 wxGenericTreeCtrl() { Init(); }
53 wxGenericTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
54 const wxPoint
& pos
= wxDefaultPosition
,
55 const wxSize
& size
= wxDefaultSize
,
56 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
57 const wxValidator
&validator
= wxDefaultValidator
,
58 const wxString
& name
= wxTreeCtrlNameStr
)
60 Create(parent
, id
, pos
, size
, style
, validator
, name
);
63 virtual ~wxGenericTreeCtrl();
65 bool Create(wxWindow
*parent
, wxWindowID id
= -1,
66 const wxPoint
& pos
= wxDefaultPosition
,
67 const wxSize
& size
= wxDefaultSize
,
68 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
69 const wxValidator
&validator
= wxDefaultValidator
,
70 const wxString
& name
= wxTreeCtrlNameStr
);
75 // get the total number of items in the control
76 size_t GetCount() const;
78 // indent is the number of pixels the children are indented relative to
79 // the parents position. SetIndent() also redraws the control
81 unsigned int GetIndent() const { return m_indent
; }
82 void SetIndent(unsigned int indent
);
84 // spacing is the number of pixels between the start and the Text
85 unsigned int GetSpacing() const { return m_spacing
; }
86 void SetSpacing(unsigned int spacing
);
88 // image list: these functions allow to associate an image list with
89 // the control and retrieve it. Note that the control does _not_ delete
90 // the associated image list when it's deleted in order to allow image
91 // lists to be shared between different controls.
93 // The normal image list is for the icons which correspond to the
94 // normal tree item state (whether it is selected or not).
95 // Additionally, the application might choose to show a state icon
96 // which corresponds to an app-defined item state (for example,
97 // checked/unchecked) which are taken from the state image list.
98 wxImageList
*GetImageList() const;
99 wxImageList
*GetStateImageList() const;
101 void SetImageList(wxImageList
*imageList
);
102 void SetStateImageList(wxImageList
*imageList
);
104 // Functions to work with tree ctrl items.
109 // retrieve items label
110 wxString
GetItemText(const wxTreeItemId
& item
) const;
111 // get one of the images associated with the item (normal by default)
112 int GetItemImage(const wxTreeItemId
& item
,
113 wxTreeItemIcon which
= wxTreeItemIcon_Normal
) const;
114 // get the data associated with the item
115 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
121 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
122 // get one of the images associated with the item (normal by default)
123 void SetItemImage(const wxTreeItemId
& item
, int image
,
124 wxTreeItemIcon which
= wxTreeItemIcon_Normal
);
125 // associate some data with the item
126 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
128 // force appearance of [+] button near the item. This is useful to
129 // allow the user to expand the items which don't have any children now
130 // - but instead add them only when needed, thus minimizing memory
131 // usage and loading time.
132 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= TRUE
);
134 // the item will be shown in bold
135 void SetItemBold(const wxTreeItemId
& item
, bool bold
= TRUE
);
137 // set the items text colour
138 void SetItemTextColour(const wxTreeItemId
& item
, const wxColour
& col
);
140 // set the items background colour
141 void SetItemBackgroundColour(const wxTreeItemId
& item
, const wxColour
& col
);
143 // set the items font (should be of the same height for all items)
144 void SetItemFont(const wxTreeItemId
& item
, const wxFont
& font
);
146 // item status inquiries
147 // ---------------------
149 // is the item visible (it might be outside the view or not expanded)?
150 bool IsVisible(const wxTreeItemId
& item
) const;
151 // does the item has any children?
152 bool HasChildren(const wxTreeItemId
& item
) const
153 { return ItemHasChildren(item
); }
154 bool ItemHasChildren(const wxTreeItemId
& item
) const;
155 // is the item expanded (only makes sense if HasChildren())?
156 bool IsExpanded(const wxTreeItemId
& item
) const;
157 // is this item currently selected (the same as has focus)?
158 bool IsSelected(const wxTreeItemId
& item
) const;
159 // is item text in bold font?
160 bool IsBold(const wxTreeItemId
& item
) const;
162 // number of children
163 // ------------------
165 // if 'recursively' is FALSE, only immediate children count, otherwise
166 // the returned number is the number of all items in this branch
167 size_t GetChildrenCount(const wxTreeItemId
& item
, bool recursively
= TRUE
);
172 // wxTreeItemId.IsOk() will return FALSE if there is no such item
174 // get the root tree item
175 wxTreeItemId
GetRootItem() const { return m_anchor
; }
177 // get the item currently selected (may return NULL if no selection)
178 wxTreeItemId
GetSelection() const { return m_current
; }
180 // get the items currently selected, return the number of such item
181 size_t GetSelections(wxArrayTreeItemIds
&) const;
183 // get the parent of this item (may return NULL if root)
184 wxTreeItemId
GetParent(const wxTreeItemId
& item
) const;
186 // for this enumeration function you must pass in a "cookie" parameter
187 // which is opaque for the application but is necessary for the library
188 // to make these functions reentrant (i.e. allow more than one
189 // enumeration on one and the same object simultaneously). Of course,
190 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
193 // get the first child of this item
194 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
, long& cookie
) const;
195 // get the next child
196 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
, long& cookie
) const;
197 // get the last child of this item - this method doesn't use cookies
198 wxTreeItemId
GetLastChild(const wxTreeItemId
& item
) const;
200 // get the next sibling of this item
201 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
202 // get the previous sibling
203 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
205 // get first visible item
206 wxTreeItemId
GetFirstVisibleItem() const;
207 // get the next visible item: item must be visible itself!
208 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
209 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
210 // get the previous visible item: item must be visible itself!
211 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
216 // add the root node to the tree
217 wxTreeItemId
AddRoot(const wxString
& text
,
218 int image
= -1, int selectedImage
= -1,
219 wxTreeItemData
*data
= NULL
);
221 // insert a new item in as the first child of the parent
222 wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
223 const wxString
& text
,
224 int image
= -1, int selectedImage
= -1,
225 wxTreeItemData
*data
= NULL
);
227 // insert a new item after a given one
228 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
229 const wxTreeItemId
& idPrevious
,
230 const wxString
& text
,
231 int image
= -1, int selectedImage
= -1,
232 wxTreeItemData
*data
= NULL
);
234 // insert a new item before the one with the given index
235 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
237 const wxString
& text
,
238 int image
= -1, int selectedImage
= -1,
239 wxTreeItemData
*data
= NULL
);
241 // insert a new item in as the last child of the parent
242 wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
243 const wxString
& text
,
244 int image
= -1, int selectedImage
= -1,
245 wxTreeItemData
*data
= NULL
);
247 // delete this item and associated data if any
248 void Delete(const wxTreeItemId
& item
);
249 // delete all children (but don't delete the item itself)
250 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
251 void DeleteChildren(const wxTreeItemId
& item
);
252 // delete all items from the tree
253 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
254 void DeleteAllItems();
257 void Expand(const wxTreeItemId
& item
);
258 // expand this item and all subitems recursively
259 void ExpandAll(const wxTreeItemId
& item
);
260 // collapse the item without removing its children
261 void Collapse(const wxTreeItemId
& item
);
262 // collapse the item and remove all children
263 void CollapseAndReset(const wxTreeItemId
& item
);
264 // toggles the current state
265 void Toggle(const wxTreeItemId
& item
);
267 // remove the selection from currently selected item (if any)
271 void SelectItem(const wxTreeItemId
& item
, bool unselect_others
=TRUE
, bool extended_select
=FALSE
);
272 // make sure this item is visible (expanding the parent item and/or
273 // scrolling to this item if necessary)
274 void EnsureVisible(const wxTreeItemId
& item
);
275 // scroll to this item (but don't expand its parent)
276 void ScrollTo(const wxTreeItemId
& item
);
278 // The first function is more portable (because easier to implement
279 // on other platforms), but the second one returns some extra info.
280 wxTreeItemId
HitTest(const wxPoint
& point
)
281 { int dummy
; return HitTest(point
, dummy
); }
282 wxTreeItemId
HitTest(const wxPoint
& point
, int& flags
);
284 // get the bounding rectangle of the item (or of its label only)
285 bool GetBoundingRect(const wxTreeItemId
& item
,
287 bool textOnly
= FALSE
) const;
289 // Start editing the item label: this (temporarily) replaces the item
290 // with a one line edit control. The item will be selected if it hadn't
292 void EditLabel( const wxTreeItemId
& item
) { Edit( item
); }
293 void Edit( const wxTreeItemId
& item
);
296 // this function is called to compare 2 items and should return -1, 0
297 // or +1 if the first item is less than, equal to or greater than the
298 // second one. The base class version performs alphabetic comparaison
299 // of item labels (GetText)
300 virtual int OnCompareItems(const wxTreeItemId
& item1
,
301 const wxTreeItemId
& item2
);
302 // sort the children of this item using OnCompareItems
304 // NB: this function is not reentrant and not MT-safe (FIXME)!
305 void SortChildren(const wxTreeItemId
& item
);
307 // deprecated functions: use Set/GetItemImage directly
308 // get the selected item image
309 int GetItemSelectedImage(const wxTreeItemId
& item
) const
310 { return GetItemImage(item
, wxTreeItemIcon_Selected
); }
311 // set the selected item image
312 void SetItemSelectedImage(const wxTreeItemId
& item
, int image
)
313 { SetItemImage(item
, image
, wxTreeItemIcon_Selected
); }
315 // implementation only from now on
318 void OnPaint( wxPaintEvent
&event
);
319 void OnSetFocus( wxFocusEvent
&event
);
320 void OnKillFocus( wxFocusEvent
&event
);
321 void OnChar( wxKeyEvent
&event
);
322 void OnMouse( wxMouseEvent
&event
);
323 void OnIdle( wxIdleEvent
&event
);
325 // implementation helpers
326 void SendDeleteEvent(wxGenericTreeItem
*itemBeingDeleted
);
328 void DrawBorder(const wxTreeItemId
& item
);
329 void DrawLine(const wxTreeItemId
& item
, bool below
);
332 friend class wxGenericTreeItem
;
333 friend class wxTreeRenameTimer
;
334 friend class wxTreeTextCtrl
;
339 wxGenericTreeItem
*m_anchor
;
340 wxGenericTreeItem
*m_current
, *m_key_current
, *m_currentEdit
;
343 int m_xScroll
,m_yScroll
;
344 unsigned int m_indent
;
345 unsigned int m_spacing
;
348 wxBrush
*m_hilightBrush
;
349 wxImageList
*m_imageListNormal
,
354 bool m_isDragging
; // true between BEGIN/END drag events
355 wxGenericTreeItem
*m_dropTarget
;
356 wxCursor m_oldCursor
; // cursor is changed while dragging
357 wxGenericTreeItem
*m_oldSelection
;
359 wxTimer
*m_renameTimer
;
361 bool m_lastOnSame
; // last click on the same item as prev
362 wxString m_renameRes
;
364 // the common part of all ctors
368 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
370 const wxString
& text
,
371 int image
, int selectedImage
,
372 wxTreeItemData
*data
);
374 void AdjustMyScrollbars();
375 int GetLineHeight(wxGenericTreeItem
*item
) const;
376 void PaintLevel( wxGenericTreeItem
*item
, wxDC
& dc
, int level
, int &y
);
377 void PaintItem( wxGenericTreeItem
*item
, wxDC
& dc
);
379 void CalculateLevel( wxGenericTreeItem
*item
, wxDC
&dc
, int level
, int &y
);
380 void CalculatePositions();
381 void CalculateSize( wxGenericTreeItem
*item
, wxDC
&dc
);
383 void RefreshSubtree( wxGenericTreeItem
*item
);
384 void RefreshLine( wxGenericTreeItem
*item
);
386 void OnRenameTimer();
387 void OnRenameAccept();
389 void FillArray(wxGenericTreeItem
*, wxArrayTreeItemIds
&) const;
390 void SelectItemRange( wxGenericTreeItem
*item1
, wxGenericTreeItem
*item2
);
391 bool TagAllChildrenUntilLast(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
392 bool TagNextChildren(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
393 void UnselectAllChildren( wxGenericTreeItem
*item
);
395 void DrawDropEffect(wxGenericTreeItem
*item
);
398 DECLARE_EVENT_TABLE()
399 DECLARE_DYNAMIC_CLASS(wxGenericTreeCtrl
)
402 #if !defined(__WXMSW__) || defined(__WIN16__)
404 * wxTreeCtrl has to be a real class or we have problems with
405 * the run-time information.
408 class WXDLLEXPORT wxTreeCtrl
: public wxGenericTreeCtrl
411 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
415 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
416 const wxPoint
& pos
= wxDefaultPosition
,
417 const wxSize
& size
= wxDefaultSize
,
418 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
419 const wxValidator
&validator
= wxDefaultValidator
,
420 const wxString
& name
= wxTreeCtrlNameStr
)
422 Create(parent
, id
, pos
, size
, style
, validator
, name
);
429 #endif // _GENERIC_TREECTRL_H_