1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/generic/treectlg.h
3 // Purpose: wxTreeCtrl class
4 // Author: Robert Roebling
8 // Copyright: (c) 1997,1998 Robert Roebling
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _GENERIC_TREECTRL_H_
13 #define _GENERIC_TREECTRL_H_
17 #include "wx/scrolwin.h"
19 #include "wx/imaglist.h"
21 // -----------------------------------------------------------------------------
22 // forward declaration
23 // -----------------------------------------------------------------------------
25 class WXDLLEXPORT wxGenericTreeItem
;
27 class WXDLLEXPORT wxTreeItemData
;
29 class WXDLLEXPORT wxTreeRenameTimer
;
30 class WXDLLEXPORT wxTreeFindTimer
;
31 class WXDLLEXPORT wxTreeTextCtrl
;
32 class WXDLLEXPORT wxTextCtrl
;
34 // -----------------------------------------------------------------------------
35 // wxGenericTreeCtrl - the tree control
36 // -----------------------------------------------------------------------------
38 class WXDLLEXPORT wxGenericTreeCtrl
: public wxScrolledWindow
43 wxGenericTreeCtrl() { Init(); }
45 wxGenericTreeCtrl(wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
46 const wxPoint
& pos
= wxDefaultPosition
,
47 const wxSize
& size
= wxDefaultSize
,
48 long style
= wxTR_DEFAULT_STYLE
,
49 const wxValidator
&validator
= wxDefaultValidator
,
50 const wxString
& name
= wxTreeCtrlNameStr
)
53 Create(parent
, id
, pos
, size
, style
, validator
, name
);
56 virtual ~wxGenericTreeCtrl();
58 bool Create(wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
59 const wxPoint
& pos
= wxDefaultPosition
,
60 const wxSize
& size
= wxDefaultSize
,
61 long style
= wxTR_DEFAULT_STYLE
,
62 const wxValidator
&validator
= wxDefaultValidator
,
63 const wxString
& name
= wxTreeCtrlNameStr
);
68 // get the total number of items in the control
69 size_t GetCount() const;
71 // indent is the number of pixels the children are indented relative to
72 // the parents position. SetIndent() also redraws the control
74 unsigned int GetIndent() const { return m_indent
; }
75 void SetIndent(unsigned int indent
);
77 // spacing is the number of pixels between the start and the Text
78 unsigned int GetSpacing() const { return m_spacing
; }
79 void SetSpacing(unsigned int spacing
);
81 // image list: these functions allow to associate an image list with
82 // the control and retrieve it. Note that when assigned with
83 // SetImageList, the control does _not_ delete
84 // the associated image list when it's deleted in order to allow image
85 // lists to be shared between different controls. If you use
86 // AssignImageList, the control _does_ delete the image list.
88 // The normal image list is for the icons which correspond to the
89 // normal tree item state (whether it is selected or not).
90 // Additionally, the application might choose to show a state icon
91 // which corresponds to an app-defined item state (for example,
92 // checked/unchecked) which are taken from the state image list.
93 virtual wxImageList
*GetImageList() const;
94 virtual wxImageList
*GetStateImageList() const;
95 virtual wxImageList
*GetButtonsImageList() const;
97 virtual void SetImageList(wxImageList
*imageList
);
98 virtual void SetStateImageList(wxImageList
*imageList
);
99 virtual void SetButtonsImageList(wxImageList
*imageList
);
100 virtual void AssignImageList(wxImageList
*imageList
);
101 virtual void AssignStateImageList(wxImageList
*imageList
);
102 virtual void AssignButtonsImageList(wxImageList
*imageList
);
104 virtual void SetDropEffectAboveItem( bool above
= false ) { m_dropEffectAboveItem
= above
; }
105 virtual bool GetDropEffectAboveItem() const { return m_dropEffectAboveItem
; }
107 // Functions to work with tree ctrl items.
112 // retrieve item's label
113 wxString
GetItemText(const wxTreeItemId
& item
) const;
114 // get one of the images associated with the item (normal by default)
115 virtual int GetItemImage(const wxTreeItemId
& item
,
116 wxTreeItemIcon which
= wxTreeItemIcon_Normal
) const;
117 // get the data associated with the item
118 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
120 // get the item's text colour
121 wxColour
GetItemTextColour(const wxTreeItemId
& item
) const;
123 // get the item's background colour
124 wxColour
GetItemBackgroundColour(const wxTreeItemId
& item
) const;
126 // get the item's font
127 wxFont
GetItemFont(const wxTreeItemId
& item
) const;
133 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
134 // get one of the images associated with the item (normal by default)
135 virtual void SetItemImage(const wxTreeItemId
& item
, int image
,
136 wxTreeItemIcon which
= wxTreeItemIcon_Normal
);
137 // associate some data with the item
138 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
140 // force appearance of [+] button near the item. This is useful to
141 // allow the user to expand the items which don't have any children now
142 // - but instead add them only when needed, thus minimizing memory
143 // usage and loading time.
144 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= true);
146 // the item will be shown in bold
147 void SetItemBold(const wxTreeItemId
& item
, bool bold
= true);
149 // the item will be shown with a drop highlight
150 void SetItemDropHighlight(const wxTreeItemId
& item
, bool highlight
= true);
152 // set the item's text colour
153 void SetItemTextColour(const wxTreeItemId
& item
, const wxColour
& col
);
155 // set the item's background colour
156 void SetItemBackgroundColour(const wxTreeItemId
& item
, const wxColour
& col
);
158 // set the item's font (should be of the same height for all items)
159 void SetItemFont(const wxTreeItemId
& item
, const wxFont
& font
);
161 // set the window font
162 virtual bool SetFont( const wxFont
&font
);
164 // set the styles. No need to specify a GetWindowStyle here since
165 // the base wxWindow member function will do it for us
166 void SetWindowStyle(const long styles
);
168 // item status inquiries
169 // ---------------------
171 // is the item visible (it might be outside the view or not expanded)?
172 bool IsVisible(const wxTreeItemId
& item
) const;
173 // does the item has any children?
174 bool HasChildren(const wxTreeItemId
& item
) const
175 { return ItemHasChildren(item
); }
176 bool ItemHasChildren(const wxTreeItemId
& item
) const;
177 // is the item expanded (only makes sense if HasChildren())?
178 bool IsExpanded(const wxTreeItemId
& item
) const;
179 // is this item currently selected (the same as has focus)?
180 bool IsSelected(const wxTreeItemId
& item
) const;
181 // is item text in bold font?
182 bool IsBold(const wxTreeItemId
& item
) const;
183 // does the layout include space for a button?
185 // number of children
186 // ------------------
188 // if 'recursively' is false, only immediate children count, otherwise
189 // the returned number is the number of all items in this branch
190 size_t GetChildrenCount(const wxTreeItemId
& item
,
191 bool recursively
= true) const;
196 // wxTreeItemId.IsOk() will return false if there is no such item
198 // get the root tree item
199 wxTreeItemId
GetRootItem() const { return m_anchor
; }
201 // get the item currently selected (may return NULL if no selection)
202 wxTreeItemId
GetSelection() const { return m_current
; }
204 // get the items currently selected, return the number of such item
205 size_t GetSelections(wxArrayTreeItemIds
&) const;
207 // get the parent of this item (may return NULL if root)
208 wxTreeItemId
GetItemParent(const wxTreeItemId
& item
) const;
210 // for this enumeration function you must pass in a "cookie" parameter
211 // which is opaque for the application but is necessary for the library
212 // to make these functions reentrant (i.e. allow more than one
213 // enumeration on one and the same object simultaneously). Of course,
214 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
217 // get the first child of this item
218 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
,
219 wxTreeItemIdValue
& cookie
) const;
220 // get the next child
221 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
,
222 wxTreeItemIdValue
& cookie
) const;
223 // get the last child of this item - this method doesn't use cookies
224 wxTreeItemId
GetLastChild(const wxTreeItemId
& item
) const;
226 // get the next sibling of this item
227 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
228 // get the previous sibling
229 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
231 // get first visible item
232 wxTreeItemId
GetFirstVisibleItem() const;
233 // get the next visible item: item must be visible itself!
234 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
235 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
236 // get the previous visible item: item must be visible itself!
237 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
239 // Only for internal use right now, but should probably be public
240 wxTreeItemId
GetNext(const wxTreeItemId
& item
) const;
245 // add the root node to the tree
246 virtual wxTreeItemId
AddRoot(const wxString
& text
,
247 int image
= -1, int selectedImage
= -1,
248 wxTreeItemData
*data
= NULL
);
250 // insert a new item in as the first child of the parent
251 virtual wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
252 const wxString
& text
,
253 int image
= -1, int selectedImage
= -1,
254 wxTreeItemData
*data
= NULL
);
256 // insert a new item after a given one
257 virtual wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
258 const wxTreeItemId
& idPrevious
,
259 const wxString
& text
,
260 int image
= -1, int selectedImage
= -1,
261 wxTreeItemData
*data
= NULL
);
263 // insert a new item before the one with the given index
264 virtual wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
266 const wxString
& text
,
267 int image
= -1, int selectedImage
= -1,
268 wxTreeItemData
*data
= NULL
);
270 // insert a new item in as the last child of the parent
271 virtual wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
272 const wxString
& text
,
273 int image
= -1, int selectedImage
= -1,
274 wxTreeItemData
*data
= NULL
);
276 // delete this item and associated data if any
277 void Delete(const wxTreeItemId
& item
);
278 // delete all children (but don't delete the item itself)
279 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
280 void DeleteChildren(const wxTreeItemId
& item
);
281 // delete all items from the tree
282 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
283 void DeleteAllItems();
286 void Expand(const wxTreeItemId
& item
);
287 // expand this item and all subitems recursively
288 void ExpandAll(const wxTreeItemId
& item
);
289 // collapse the item without removing its children
290 void Collapse(const wxTreeItemId
& item
);
291 // collapse the item and remove all children
292 void CollapseAndReset(const wxTreeItemId
& item
);
293 // toggles the current state
294 void Toggle(const wxTreeItemId
& item
);
296 // remove the selection from currently selected item (if any)
298 // or from the given one (multiselect mode only)
299 void UnselectItem(const wxTreeItemId
& item
) { SelectItem(item
, false); }
303 void SelectItem(const wxTreeItemId
& item
, bool select
= true);
304 // toggle the item selection
305 void ToggleItemSelection(const wxTreeItemId
& item
)
307 SelectItem(item
, !IsSelected(item
));
310 // make sure this item is visible (expanding the parent item and/or
311 // scrolling to this item if necessary)
312 void EnsureVisible(const wxTreeItemId
& item
);
313 // scroll to this item (but don't expand its parent)
314 void ScrollTo(const wxTreeItemId
& item
);
315 void AdjustMyScrollbars();
317 // The first function is more portable (because easier to implement
318 // on other platforms), but the second one returns some extra info.
319 wxTreeItemId
HitTest(const wxPoint
& point
)
320 { int dummy
; return HitTest(point
, dummy
); }
321 wxTreeItemId
HitTest(const wxPoint
& point
, int& flags
);
323 // get the bounding rectangle of the item (or of its label only)
324 bool GetBoundingRect(const wxTreeItemId
& item
,
326 bool textOnly
= false) const;
328 // Start editing the item label: this (temporarily) replaces the item
329 // with a one line edit control. The item will be selected if it hadn't
331 void EditLabel( const wxTreeItemId
& item
) { Edit( item
); }
332 void Edit( const wxTreeItemId
& item
);
333 // returns a pointer to the text edit control if the item is being
334 // edited, NULL otherwise (it's assumed that no more than one item may
335 // be edited simultaneously)
336 wxTextCtrl
* GetEditControl() const;
339 // this function is called to compare 2 items and should return -1, 0
340 // or +1 if the first item is less than, equal to or greater than the
341 // second one. The base class version performs alphabetic comparaison
342 // of item labels (GetText)
343 virtual int OnCompareItems(const wxTreeItemId
& item1
,
344 const wxTreeItemId
& item2
);
345 // sort the children of this item using OnCompareItems
347 // NB: this function is not reentrant and not MT-safe (FIXME)!
348 void SortChildren(const wxTreeItemId
& item
);
350 #if WXWIN_COMPATIBILITY_2_4
351 // deprecated functions: use Set/GetItemImage directly
352 wxDEPRECATED( int GetItemSelectedImage(const wxTreeItemId
& item
) const );
353 wxDEPRECATED( void SetItemSelectedImage(const wxTreeItemId
& item
, int image
) );
355 // use the versions taking wxTreeItemIdValue cookies (note that
356 // GetNextChild() is not inside wxDEPRECATED on purpose, as otherwise we
357 // get twice as many warnings without any added benefit: it is always used
358 // with GetFirstChild() anyhow)
359 wxDEPRECATED( wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
,
360 long& cookie
) const );
361 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
,
363 #endif // WXWIN_COMPATIBILITY_2_4
365 virtual bool ShouldInheritColours() const { return false; }
367 // implementation only from now on
369 // overridden base class virtuals
370 virtual bool SetBackgroundColour(const wxColour
& colour
);
371 virtual bool SetForegroundColour(const wxColour
& colour
);
373 virtual void Freeze();
377 void OnPaint( wxPaintEvent
&event
);
378 void OnSetFocus( wxFocusEvent
&event
);
379 void OnKillFocus( wxFocusEvent
&event
);
380 void OnChar( wxKeyEvent
&event
);
381 void OnMouse( wxMouseEvent
&event
);
382 void OnGetToolTip( wxTreeEvent
&event
);
383 void OnInternalIdle( );
385 virtual wxSize
DoGetBestSize() const;
387 virtual wxVisualAttributes
GetDefaultAttributes() const
389 return GetClassDefaultAttributes(GetWindowVariant());
392 static wxVisualAttributes
393 GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
395 // implementation helpers
397 friend class wxGenericTreeItem
;
398 friend class wxTreeRenameTimer
;
399 friend class wxTreeFindTimer
;
400 friend class wxTreeTextCtrl
;
405 wxGenericTreeItem
*m_anchor
;
406 wxGenericTreeItem
*m_current
,
408 // A hint to select a parent item after deleting a child
410 unsigned short m_indent
;
411 unsigned short m_spacing
;
414 wxBrush
*m_hilightBrush
,
415 *m_hilightUnfocusedBrush
;
418 bool m_ownsImageListNormal
,
419 m_ownsImageListState
,
420 m_ownsImageListButtons
;
421 bool m_isDragging
; // true between BEGIN/END drag events
422 bool m_lastOnSame
; // last click on the same item as prev
423 wxImageList
*m_imageListNormal
,
430 wxGenericTreeItem
*m_dropTarget
;
431 wxCursor m_oldCursor
; // cursor is changed while dragging
432 wxGenericTreeItem
*m_oldSelection
;
433 wxGenericTreeItem
*m_underMouse
; // for visual effects
434 wxTreeTextCtrl
*m_textCtrl
;
436 wxTimer
*m_renameTimer
;
438 // incremental search data
439 wxString m_findPrefix
;
440 wxTimer
*m_findTimer
;
442 bool m_dropEffectAboveItem
;
444 // the common part of all ctors
448 void SendDeleteEvent(wxGenericTreeItem
*itemBeingDeleted
);
450 void DrawBorder(const wxTreeItemId
& item
);
451 void DrawLine(const wxTreeItemId
& item
, bool below
);
452 void DrawDropEffect(wxGenericTreeItem
*item
);
454 void DoSelectItem(const wxTreeItemId
& id
,
455 bool unselect_others
= true,
456 bool extended_select
= false);
458 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
460 const wxString
& text
,
461 int image
, int selectedImage
,
462 wxTreeItemData
*data
);
464 // called by wxTextTreeCtrl when it marks itself for deletion
465 void ResetTextControl();
467 // find the first item starting with the given prefix after the given item
468 wxTreeItemId
FindItem(const wxTreeItemId
& id
, const wxString
& prefix
) const;
470 bool HasButtons() const { return HasFlag(wxTR_HAS_BUTTONS
); }
472 void CalculateLineHeight();
473 int GetLineHeight(wxGenericTreeItem
*item
) const;
474 void PaintLevel( wxGenericTreeItem
*item
, wxDC
& dc
, int level
, int &y
);
475 void PaintItem( wxGenericTreeItem
*item
, wxDC
& dc
);
477 void CalculateLevel( wxGenericTreeItem
*item
, wxDC
&dc
, int level
, int &y
);
478 void CalculatePositions();
479 void CalculateSize( wxGenericTreeItem
*item
, wxDC
&dc
);
481 void RefreshSubtree( wxGenericTreeItem
*item
);
482 void RefreshLine( wxGenericTreeItem
*item
);
484 // redraw all selected items
485 void RefreshSelected();
487 // RefreshSelected() recursive helper
488 void RefreshSelectedUnder(wxGenericTreeItem
*item
);
490 void OnRenameTimer();
491 bool OnRenameAccept(wxGenericTreeItem
*item
, const wxString
& value
);
492 void OnRenameCancelled(wxGenericTreeItem
*item
);
494 void FillArray(wxGenericTreeItem
*, wxArrayTreeItemIds
&) const;
495 void SelectItemRange( wxGenericTreeItem
*item1
, wxGenericTreeItem
*item2
);
496 bool TagAllChildrenUntilLast(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
497 bool TagNextChildren(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
498 void UnselectAllChildren( wxGenericTreeItem
*item
);
499 void ChildrenClosing(wxGenericTreeItem
* item
);
502 DECLARE_EVENT_TABLE()
503 DECLARE_DYNAMIC_CLASS(wxGenericTreeCtrl
)
504 DECLARE_NO_COPY_CLASS(wxGenericTreeCtrl
)
507 #if !defined(__WXMSW__) || defined(__WXUNIVERSAL__)
509 * wxTreeCtrl has to be a real class or we have problems with
510 * the run-time information.
513 class WXDLLEXPORT wxTreeCtrl
: public wxGenericTreeCtrl
515 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
520 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
521 const wxPoint
& pos
= wxDefaultPosition
,
522 const wxSize
& size
= wxDefaultSize
,
523 long style
= wxTR_DEFAULT_STYLE
,
524 const wxValidator
&validator
= wxDefaultValidator
,
525 const wxString
& name
= wxTreeCtrlNameStr
)
526 : wxGenericTreeCtrl(parent
, id
, pos
, size
, style
, validator
, name
)
530 #endif // !__WXMSW__ || __WXUNIVERSAL__
532 #endif // wxUSE_TREECTRL
534 #endif // _GENERIC_TREECTRL_H_