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_
15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16 #pragma interface "treectlg.h"
21 #include "wx/scrolwin.h"
23 #include "wx/imaglist.h"
25 // -----------------------------------------------------------------------------
26 // forward declaration
27 // -----------------------------------------------------------------------------
29 class WXDLLEXPORT wxGenericTreeItem
;
31 class WXDLLEXPORT wxTreeItemData
;
33 class WXDLLEXPORT wxTreeRenameTimer
;
34 class WXDLLEXPORT wxTreeFindTimer
;
35 class WXDLLEXPORT wxTreeTextCtrl
;
36 class WXDLLEXPORT wxTextCtrl
;
38 // -----------------------------------------------------------------------------
39 // wxGenericTreeCtrl - the tree control
40 // -----------------------------------------------------------------------------
42 class WXDLLEXPORT wxGenericTreeCtrl
: public wxScrolledWindow
47 wxGenericTreeCtrl() { Init(); }
49 wxGenericTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
50 const wxPoint
& pos
= wxDefaultPosition
,
51 const wxSize
& size
= wxDefaultSize
,
52 long style
= wxTR_DEFAULT_STYLE
,
53 const wxValidator
&validator
= wxDefaultValidator
,
54 const wxString
& name
= wxTreeCtrlNameStr
)
57 Create(parent
, id
, pos
, size
, style
, validator
, name
);
60 virtual ~wxGenericTreeCtrl();
62 bool Create(wxWindow
*parent
, wxWindowID id
= -1,
63 const wxPoint
& pos
= wxDefaultPosition
,
64 const wxSize
& size
= wxDefaultSize
,
65 long style
= wxTR_DEFAULT_STYLE
,
66 const wxValidator
&validator
= wxDefaultValidator
,
67 const wxString
& name
= wxTreeCtrlNameStr
);
72 // get the total number of items in the control
73 size_t GetCount() const;
75 // indent is the number of pixels the children are indented relative to
76 // the parents position. SetIndent() also redraws the control
78 unsigned int GetIndent() const { return m_indent
; }
79 void SetIndent(unsigned int indent
);
81 // spacing is the number of pixels between the start and the Text
82 unsigned int GetSpacing() const { return m_spacing
; }
83 void SetSpacing(unsigned int spacing
);
85 // image list: these functions allow to associate an image list with
86 // the control and retrieve it. Note that when assigned with
87 // SetImageList, the control does _not_ delete
88 // the associated image list when it's deleted in order to allow image
89 // lists to be shared between different controls. If you use
90 // AssignImageList, the control _does_ delete the image list.
92 // The normal image list is for the icons which correspond to the
93 // normal tree item state (whether it is selected or not).
94 // Additionally, the application might choose to show a state icon
95 // which corresponds to an app-defined item state (for example,
96 // checked/unchecked) which are taken from the state image list.
97 wxImageList
*GetImageList() const;
98 wxImageList
*GetStateImageList() const;
99 wxImageList
*GetButtonsImageList() const;
101 void SetImageList(wxImageList
*imageList
);
102 void SetStateImageList(wxImageList
*imageList
);
103 void SetButtonsImageList(wxImageList
*imageList
);
104 void AssignImageList(wxImageList
*imageList
);
105 void AssignStateImageList(wxImageList
*imageList
);
106 void AssignButtonsImageList(wxImageList
*imageList
);
108 // Functions to work with tree ctrl items.
113 // retrieve item's label
114 wxString
GetItemText(const wxTreeItemId
& item
) const;
115 // get one of the images associated with the item (normal by default)
116 int GetItemImage(const wxTreeItemId
& item
,
117 wxTreeItemIcon which
= wxTreeItemIcon_Normal
) const;
118 // get the data associated with the item
119 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
121 // get the item's text colour
122 wxColour
GetItemTextColour(const wxTreeItemId
& item
) const;
124 // get the item's background colour
125 wxColour
GetItemBackgroundColour(const wxTreeItemId
& item
) const;
127 // get the item's font
128 wxFont
GetItemFont(const wxTreeItemId
& item
) const;
134 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
135 // get one of the images associated with the item (normal by default)
136 void SetItemImage(const wxTreeItemId
& item
, int image
,
137 wxTreeItemIcon which
= wxTreeItemIcon_Normal
);
138 // associate some data with the item
139 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
141 // force appearance of [+] button near the item. This is useful to
142 // allow the user to expand the items which don't have any children now
143 // - but instead add them only when needed, thus minimizing memory
144 // usage and loading time.
145 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= TRUE
);
147 // the item will be shown in bold
148 void SetItemBold(const wxTreeItemId
& item
, bool bold
= TRUE
);
150 // set the item's text colour
151 void SetItemTextColour(const wxTreeItemId
& item
, const wxColour
& col
);
153 // set the item's background colour
154 void SetItemBackgroundColour(const wxTreeItemId
& item
, const wxColour
& col
);
156 // set the item's font (should be of the same height for all items)
157 void SetItemFont(const wxTreeItemId
& item
, const wxFont
& font
);
159 // set the window font
160 virtual bool SetFont( const wxFont
&font
);
162 // set the styles. No need to specify a GetWindowStyle here since
163 // the base wxWindow member function will do it for us
164 void SetWindowStyle(const long styles
);
166 // item status inquiries
167 // ---------------------
169 // is the item visible (it might be outside the view or not expanded)?
170 bool IsVisible(const wxTreeItemId
& item
) const;
171 // does the item has any children?
172 bool HasChildren(const wxTreeItemId
& item
) const
173 { return ItemHasChildren(item
); }
174 bool ItemHasChildren(const wxTreeItemId
& item
) const;
175 // is the item expanded (only makes sense if HasChildren())?
176 bool IsExpanded(const wxTreeItemId
& item
) const;
177 // is this item currently selected (the same as has focus)?
178 bool IsSelected(const wxTreeItemId
& item
) const;
179 // is item text in bold font?
180 bool IsBold(const wxTreeItemId
& item
) const;
181 // does the layout include space for a button?
183 // number of children
184 // ------------------
186 // if 'recursively' is FALSE, only immediate children count, otherwise
187 // the returned number is the number of all items in this branch
188 size_t GetChildrenCount(const wxTreeItemId
& item
, bool recursively
= TRUE
);
193 // wxTreeItemId.IsOk() will return FALSE if there is no such item
195 // get the root tree item
196 wxTreeItemId
GetRootItem() const { return m_anchor
; }
198 // get the item currently selected (may return NULL if no selection)
199 wxTreeItemId
GetSelection() const { return m_current
; }
201 // get the items currently selected, return the number of such item
202 size_t GetSelections(wxArrayTreeItemIds
&) const;
204 // get the parent of this item (may return NULL if root)
205 wxTreeItemId
GetItemParent(const wxTreeItemId
& item
) const;
207 #if WXWIN_COMPATIBILITY_2_2
208 // deprecated: Use GetItemParent instead.
209 wxTreeItemId
GetParent(const wxTreeItemId
& item
) const
210 { return GetItemParent( item
); }
212 // Expose the base class method hidden by the one above.
213 wxWindow
*GetParent() const { return wxScrolledWindow::GetParent(); }
214 #endif // WXWIN_COMPATIBILITY_2_2
216 // for this enumeration function you must pass in a "cookie" parameter
217 // which is opaque for the application but is necessary for the library
218 // to make these functions reentrant (i.e. allow more than one
219 // enumeration on one and the same object simultaneously). Of course,
220 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
223 // get the first child of this item
224 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
,
225 wxTreeItemIdValue
& cookie
) const;
226 // get the next child
227 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
,
228 wxTreeItemIdValue
& cookie
) const;
229 // get the last child of this item - this method doesn't use cookies
230 wxTreeItemId
GetLastChild(const wxTreeItemId
& item
) const;
232 // get the next sibling of this item
233 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
234 // get the previous sibling
235 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
237 // get first visible item
238 wxTreeItemId
GetFirstVisibleItem() const;
239 // get the next visible item: item must be visible itself!
240 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
241 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
242 // get the previous visible item: item must be visible itself!
243 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
245 // Only for internal use right now, but should probably be public
246 wxTreeItemId
GetNext(const wxTreeItemId
& item
) const;
251 // add the root node to the tree
252 wxTreeItemId
AddRoot(const wxString
& text
,
253 int image
= -1, int selectedImage
= -1,
254 wxTreeItemData
*data
= NULL
);
256 // insert a new item in as the first child of the parent
257 wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
258 const wxString
& text
,
259 int image
= -1, int selectedImage
= -1,
260 wxTreeItemData
*data
= NULL
);
262 // insert a new item after a given one
263 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
264 const wxTreeItemId
& idPrevious
,
265 const wxString
& text
,
266 int image
= -1, int selectedImage
= -1,
267 wxTreeItemData
*data
= NULL
);
269 // insert a new item before the one with the given index
270 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
272 const wxString
& text
,
273 int image
= -1, int selectedImage
= -1,
274 wxTreeItemData
*data
= NULL
);
276 // insert a new item in as the last child of the parent
277 wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
278 const wxString
& text
,
279 int image
= -1, int selectedImage
= -1,
280 wxTreeItemData
*data
= NULL
);
282 // delete this item and associated data if any
283 void Delete(const wxTreeItemId
& item
);
284 // delete all children (but don't delete the item itself)
285 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
286 void DeleteChildren(const wxTreeItemId
& item
);
287 // delete all items from the tree
288 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
289 void DeleteAllItems();
292 void Expand(const wxTreeItemId
& item
);
293 // expand this item and all subitems recursively
294 void ExpandAll(const wxTreeItemId
& item
);
295 // collapse the item without removing its children
296 void Collapse(const wxTreeItemId
& item
);
297 // collapse the item and remove all children
298 void CollapseAndReset(const wxTreeItemId
& item
);
299 // toggles the current state
300 void Toggle(const wxTreeItemId
& item
);
302 // remove the selection from currently selected item (if any)
304 // or from the given one (multiselect mode only)
305 void UnselectItem(const wxTreeItemId
& item
) { SelectItem(item
, false); }
309 void SelectItem(const wxTreeItemId
& item
, bool select
= true);
310 // toggle the item selection
311 void ToggleItemSelection(const wxTreeItemId
& item
)
313 SelectItem(item
, !IsSelected(item
));
316 // make sure this item is visible (expanding the parent item and/or
317 // scrolling to this item if necessary)
318 void EnsureVisible(const wxTreeItemId
& item
);
319 // scroll to this item (but don't expand its parent)
320 void ScrollTo(const wxTreeItemId
& item
);
321 void AdjustMyScrollbars();
323 // The first function is more portable (because easier to implement
324 // on other platforms), but the second one returns some extra info.
325 wxTreeItemId
HitTest(const wxPoint
& point
)
326 { int dummy
; return HitTest(point
, dummy
); }
327 wxTreeItemId
HitTest(const wxPoint
& point
, int& flags
);
329 // get the bounding rectangle of the item (or of its label only)
330 bool GetBoundingRect(const wxTreeItemId
& item
,
332 bool textOnly
= FALSE
) const;
334 // Start editing the item label: this (temporarily) replaces the item
335 // with a one line edit control. The item will be selected if it hadn't
337 void EditLabel( const wxTreeItemId
& item
) { Edit( item
); }
338 void Edit( const wxTreeItemId
& item
);
339 // returns a pointer to the text edit control if the item is being
340 // edited, NULL otherwise (it's assumed that no more than one item may
341 // be edited simultaneously)
342 wxTextCtrl
* GetEditControl() const;
345 // this function is called to compare 2 items and should return -1, 0
346 // or +1 if the first item is less than, equal to or greater than the
347 // second one. The base class version performs alphabetic comparaison
348 // of item labels (GetText)
349 virtual int OnCompareItems(const wxTreeItemId
& item1
,
350 const wxTreeItemId
& item2
);
351 // sort the children of this item using OnCompareItems
353 // NB: this function is not reentrant and not MT-safe (FIXME)!
354 void SortChildren(const wxTreeItemId
& item
);
356 #if WXWIN_COMPATIBILITY_2_4
357 // deprecated functions: use Set/GetItemImage directly
358 int GetItemSelectedImage(const wxTreeItemId
& item
) const
359 { return GetItemImage(item
, wxTreeItemIcon_Selected
); }
360 void SetItemSelectedImage(const wxTreeItemId
& item
, int image
)
361 { SetItemImage(item
, image
, wxTreeItemIcon_Selected
); }
363 // use the versions taking wxTreeItemIdValue cookies (note that
364 // GetNextChild() is not inside wxDEPRECATED on purpose, as otherwise we
365 // get twice as many warnings without any added benefit: it is always used
366 // with GetFirstChild() anyhow)
367 wxDEPRECATED( wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
,
368 long& cookie
) const );
369 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
,
371 #endif // WXWIN_COMPATIBILITY_2_4
373 virtual bool ShouldInheritColours() const { return false; }
375 // implementation only from now on
377 // overridden base class virtuals
378 virtual bool SetBackgroundColour(const wxColour
& colour
);
379 virtual bool SetForegroundColour(const wxColour
& colour
);
382 void OnPaint( wxPaintEvent
&event
);
383 void OnSetFocus( wxFocusEvent
&event
);
384 void OnKillFocus( wxFocusEvent
&event
);
385 void OnChar( wxKeyEvent
&event
);
386 void OnMouse( wxMouseEvent
&event
);
387 void OnGetToolTip( wxTreeEvent
&event
);
388 void OnInternalIdle( );
390 // implementation helpers
392 friend class wxGenericTreeItem
;
393 friend class wxTreeRenameTimer
;
394 friend class wxTreeFindTimer
;
395 friend class wxTreeTextCtrl
;
400 wxGenericTreeItem
*m_anchor
;
401 wxGenericTreeItem
*m_current
,
403 // A hint to select a parent item after deleting a child
405 unsigned short m_indent
;
406 unsigned short m_spacing
;
409 wxBrush
*m_hilightBrush
,
410 *m_hilightUnfocusedBrush
;
413 bool m_ownsImageListNormal
,
414 m_ownsImageListState
,
415 m_ownsImageListButtons
;
416 bool m_isDragging
; // true between BEGIN/END drag events
417 bool m_lastOnSame
; // last click on the same item as prev
418 wxImageList
*m_imageListNormal
,
424 wxGenericTreeItem
*m_dropTarget
;
425 wxCursor m_oldCursor
; // cursor is changed while dragging
426 wxGenericTreeItem
*m_oldSelection
;
427 wxGenericTreeItem
*m_underMouse
; // for visual effects
428 wxTreeTextCtrl
*m_textCtrl
;
430 wxTimer
*m_renameTimer
;
432 // incremental search data
433 wxString m_findPrefix
;
434 wxTimer
*m_findTimer
;
436 // the common part of all ctors
440 void SendDeleteEvent(wxGenericTreeItem
*itemBeingDeleted
);
442 void DrawBorder(const wxTreeItemId
& item
);
443 void DrawLine(const wxTreeItemId
& item
, bool below
);
444 void DrawDropEffect(wxGenericTreeItem
*item
);
446 void DoSelectItem(const wxTreeItemId
& id
,
447 bool unselect_others
= TRUE
,
448 bool extended_select
= FALSE
);
450 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
452 const wxString
& text
,
453 int image
, int selectedImage
,
454 wxTreeItemData
*data
);
456 // called by wxTextTreeCtrl when it marks itself for deletion
457 void ResetTextControl();
459 // find the first item starting with the given prefix after the given item
460 wxTreeItemId
FindItem(const wxTreeItemId
& id
, const wxString
& prefix
) const;
462 bool HasButtons() const { return HasFlag(wxTR_HAS_BUTTONS
); }
464 void CalculateLineHeight();
465 int GetLineHeight(wxGenericTreeItem
*item
) const;
466 void PaintLevel( wxGenericTreeItem
*item
, wxDC
& dc
, int level
, int &y
);
467 void PaintItem( wxGenericTreeItem
*item
, wxDC
& dc
);
469 void CalculateLevel( wxGenericTreeItem
*item
, wxDC
&dc
, int level
, int &y
);
470 void CalculatePositions();
471 void CalculateSize( wxGenericTreeItem
*item
, wxDC
&dc
);
473 void RefreshSubtree( wxGenericTreeItem
*item
);
474 void RefreshLine( wxGenericTreeItem
*item
);
476 // redraw all selected items
477 void RefreshSelected();
479 // RefreshSelected() recursive helper
480 void RefreshSelectedUnder(wxGenericTreeItem
*item
);
482 void OnRenameTimer();
483 bool OnRenameAccept(wxGenericTreeItem
*item
, const wxString
& value
);
484 void OnRenameCancelled(wxGenericTreeItem
*item
);
486 void FillArray(wxGenericTreeItem
*, wxArrayTreeItemIds
&) const;
487 void SelectItemRange( wxGenericTreeItem
*item1
, wxGenericTreeItem
*item2
);
488 bool TagAllChildrenUntilLast(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
489 bool TagNextChildren(wxGenericTreeItem
*crt_item
, wxGenericTreeItem
*last_item
, bool select
);
490 void UnselectAllChildren( wxGenericTreeItem
*item
);
493 DECLARE_EVENT_TABLE()
494 DECLARE_DYNAMIC_CLASS(wxGenericTreeCtrl
)
495 DECLARE_NO_COPY_CLASS(wxGenericTreeCtrl
)
498 #if !defined(__WXMSW__) || defined(__WIN16__) || defined(__WXUNIVERSAL__)
500 * wxTreeCtrl has to be a real class or we have problems with
501 * the run-time information.
504 class WXDLLEXPORT wxTreeCtrl
: public wxGenericTreeCtrl
506 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
511 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= -1,
512 const wxPoint
& pos
= wxDefaultPosition
,
513 const wxSize
& size
= wxDefaultSize
,
514 long style
= wxTR_DEFAULT_STYLE
,
515 const wxValidator
&validator
= wxDefaultValidator
,
516 const wxString
& name
= wxTreeCtrlNameStr
)
517 : wxGenericTreeCtrl(parent
, id
, pos
, size
, style
, validator
, name
)
521 #endif // !__WXMSW__ || __WIN16__ || __WXUNIVERSAL__
523 #endif // wxUSE_TREECTRL
525 #endif // _GENERIC_TREECTRL_H_