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 // Start editing the item label: this (temporarily) replaces the item
285 // with a one line edit control. The item will be selected if it hadn't
287 void EditLabel( const wxTreeItemId
& item
) { Edit( item
); }
288 void Edit( const wxTreeItemId
& item
);
291 // this function is called to compare 2 items and should return -1, 0
292 // or +1 if the first item is less than, equal to or greater than the
293 // second one. The base class version performs alphabetic comparaison
294 // of item labels (GetText)
295 virtual int OnCompareItems(const wxTreeItemId
& item1
,
296 const wxTreeItemId
& item2
);
297 // sort the children of this item using OnCompareItems
299 // NB: this function is not reentrant and not MT-safe (FIXME)!
300 void SortChildren(const wxTreeItemId
& item
);
302 // deprecated functions: use Set/GetItemImage directly
303 // get the selected item image
304 int GetItemSelectedImage(const wxTreeItemId
& item
) const
305 { return GetItemImage(item
, wxTreeItemIcon_Selected
); }
306 // set the selected item image
307 void SetItemSelectedImage(const wxTreeItemId
& item
, int image
)
308 { SetItemImage(item
, image
, wxTreeItemIcon_Selected
); }
310 // implementation only from now on
313 void OnPaint( wxPaintEvent
&event
);
314 void OnSetFocus( wxFocusEvent
&event
);
315 void OnKillFocus( wxFocusEvent
&event
);
316 void OnChar( wxKeyEvent
&event
);
317 void OnMouse( wxMouseEvent
&event
);
318 void OnIdle( wxIdleEvent
&event
);
320 // implementation helpers
321 void SendDeleteEvent(wxGenericTreeItem
*itemBeingDeleted
);
323 void DrawBorder(const wxTreeItemId
& item
);
324 void DrawLine(const wxTreeItemId
& item
, bool below
);
327 friend class wxGenericTreeItem
;
328 friend class wxTreeRenameTimer
;
329 friend class wxTreeTextCtrl
;
334 wxGenericTreeItem
*m_anchor
;
335 wxGenericTreeItem
*m_current
, *m_key_current
, *m_currentEdit
;
338 int m_xScroll
,m_yScroll
;
339 unsigned int m_indent
;
340 unsigned int m_spacing
;
343 wxBrush
*m_hilightBrush
;
344 wxImageList
*m_imageListNormal
,
349 bool m_isDragging
; // true between BEGIN/END drag events
350 wxGenericTreeItem
*m_dropTarget
;
351 wxCursor m_oldCursor
; // cursor is changed while dragging
352 wxGenericTreeItem
*m_oldSelection
;
354 wxTimer
*m_renameTimer
;
356 bool m_lastOnSame
; // last click on the same item as prev
357 wxString m_renameRes
;
359 // the common part of all ctors
363 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
365 const wxString
& text
,
366 int image
, int selectedImage
,
367 wxTreeItemData
*data
);
369 void AdjustMyScrollbars();
370 int GetLineHeight(wxGenericTreeItem
*item
) const;
371 void PaintLevel( wxGenericTreeItem
*item
, wxDC
& dc
, int level
, int &y
);
372 void PaintItem( wxGenericTreeItem
*item
, wxDC
& dc
);
374 void CalculateLevel( wxGenericTreeItem
*item
, wxDC
&dc
, int level
, int &y
);
375 void CalculatePositions();
376 void CalculateSize( wxGenericTreeItem
*item
, wxDC
&dc
);
378 void RefreshSubtree( wxGenericTreeItem
*item
);
379 void RefreshLine( wxGenericTreeItem
*item
);
381 void OnRenameTimer();
382 void OnRenameAccept();
384 void FillArray(wxGenericTreeItem
*, wxArrayTreeItemIds
&) const;
385 void SelectItemRange( wxGenericTreeItem
*item1
, wxGenericTreeItem
*item2
);
386 bool TagAllChildrenUntilLast(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
387 bool TagNextChildren(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
388 void UnselectAllChildren( wxGenericTreeItem
*item
);
390 void DrawDropEffect(wxGenericTreeItem
*item
);
393 DECLARE_EVENT_TABLE()
394 DECLARE_DYNAMIC_CLASS(wxGenericTreeCtrl
)
397 #if !defined(__WXMSW__) || defined(__WIN16__)
399 * wxTreeCtrl has to be a real class or we have problems with
400 * the run-time information.
403 class WXDLLEXPORT wxTreeCtrl
: public wxGenericTreeCtrl
406 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
410 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
411 const wxPoint
& pos
= wxDefaultPosition
,
412 const wxSize
& size
= wxDefaultSize
,
413 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
414 const wxValidator
&validator
= wxDefaultValidator
,
415 const wxString
& name
= wxTreeCtrlNameStr
)
417 Create(parent
, id
, pos
, size
, style
, validator
, name
);
424 #endif // _GENERIC_TREECTRL_H_