1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/palmos/treectrl.h
3 // Purpose: wxTreeCtrl class
4 // Author: William Osborne - minimal working wxPalmOS port
8 // Copyright: (c) William Osborne
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_TREECTRL_H_
13 #define _WX_TREECTRL_H_
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
19 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
20 #pragma interface "treectrl.h"
25 #include "wx/textctrl.h"
26 #include "wx/dynarray.h"
27 #include "wx/treebase.h"
28 #include "wx/hashmap.h"
31 class WXDLLEXPORT wxImageList
;
32 class WXDLLEXPORT wxDragImage
;
33 struct WXDLLEXPORT wxTreeViewItem
;
35 // NB: all the following flags are for compatbility only and will be removed in the
38 // flags for deprecated `Expand(int action)'
42 wxTREE_EXPAND_COLLAPSE
,
43 wxTREE_EXPAND_COLLAPSE_RESET
,
47 // flags for deprecated InsertItem() variant (their values are the same as of
48 // TVI_FIRST and TVI_LAST)
49 #define wxTREE_INSERT_FIRST 0xFFFF0001
50 #define wxTREE_INSERT_LAST 0xFFFF0002
52 // hash storing attributes for our items
53 WX_DECLARE_EXPORTED_VOIDPTR_HASH_MAP(wxTreeItemAttr
*, wxMapTreeAttr
);
55 // ----------------------------------------------------------------------------
57 // ----------------------------------------------------------------------------
59 class WXDLLEXPORT wxTreeCtrl
: public wxControl
64 wxTreeCtrl() { Init(); }
66 wxTreeCtrl(wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
67 const wxPoint
& pos
= wxDefaultPosition
,
68 const wxSize
& size
= wxDefaultSize
,
69 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
70 const wxValidator
& validator
= wxDefaultValidator
,
71 const wxString
& name
= wxTreeCtrlNameStr
)
73 Create(parent
, id
, pos
, size
, style
, validator
, name
);
76 virtual ~wxTreeCtrl();
78 bool Create(wxWindow
*parent
, wxWindowID id
= wxID_ANY
,
79 const wxPoint
& pos
= wxDefaultPosition
,
80 const wxSize
& size
= wxDefaultSize
,
81 long style
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
,
82 const wxValidator
& validator
= wxDefaultValidator
,
83 const wxString
& name
= wxTreeCtrlNameStr
);
88 // get the total number of items in the control
89 size_t GetCount() const;
91 // indent is the number of pixels the children are indented relative to
92 // the parents position. SetIndent() also redraws the control
94 unsigned int GetIndent() const;
95 void SetIndent(unsigned int indent
);
97 // spacing is the number of pixels between the start and the Text
98 unsigned int GetSpacing() const { return 18; } // return wxGTK default
99 void SetSpacing(unsigned int WXUNUSED(spacing
)) { }
101 // image list: these functions allow to associate an image list with
102 // the control and retrieve it. Note that the control does _not_ delete
103 // the associated image list when it's deleted in order to allow image
104 // lists to be shared between different controls.
106 // The normal image list is for the icons which correspond to the
107 // normal tree item state (whether it is selected or not).
108 // Additionally, the application might choose to show a state icon
109 // which corresponds to an app-defined item state (for example,
110 // checked/unchecked) which are taken from the state image list.
111 wxImageList
*GetImageList() const;
112 wxImageList
*GetStateImageList() const;
114 void SetImageList(wxImageList
*imageList
);
115 void SetStateImageList(wxImageList
*imageList
);
116 void AssignImageList(wxImageList
*imageList
);
117 void AssignStateImageList(wxImageList
*imageList
);
119 // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
120 // member functions of wxTreeItem because they must know the tree the item
121 // belongs to for Windows implementation and storing the pointer to
122 // wxTreeCtrl in each wxTreeItem is just too much waste.
127 // retrieve items label
128 wxString
GetItemText(const wxTreeItemId
& item
) const;
129 // get one of the images associated with the item (normal by default)
130 int GetItemImage(const wxTreeItemId
& item
,
131 wxTreeItemIcon which
= wxTreeItemIcon_Normal
) const;
132 // get the data associated with the item
133 wxTreeItemData
*GetItemData(const wxTreeItemId
& item
) const;
135 // get the item's text colour
136 wxColour
GetItemTextColour(const wxTreeItemId
& item
) const;
138 // get the item's background colour
139 wxColour
GetItemBackgroundColour(const wxTreeItemId
& item
) const;
141 // get the item's font
142 wxFont
GetItemFont(const wxTreeItemId
& item
) const;
148 void SetItemText(const wxTreeItemId
& item
, const wxString
& text
);
149 // get one of the images associated with the item (normal by default)
150 void SetItemImage(const wxTreeItemId
& item
, int image
,
151 wxTreeItemIcon which
= wxTreeItemIcon_Normal
);
152 // associate some data with the item
153 void SetItemData(const wxTreeItemId
& item
, wxTreeItemData
*data
);
155 // force appearance of [+] button near the item. This is useful to
156 // allow the user to expand the items which don't have any children now
157 // - but instead add them only when needed, thus minimizing memory
158 // usage and loading time.
159 void SetItemHasChildren(const wxTreeItemId
& item
, bool has
= true);
161 // the item will be shown in bold
162 void SetItemBold(const wxTreeItemId
& item
, bool bold
= true);
164 // the item will be shown with a drop highlight
165 void SetItemDropHighlight(const wxTreeItemId
& item
, bool highlight
= true);
167 // set the items text colour
168 void SetItemTextColour(const wxTreeItemId
& item
, const wxColour
& col
);
170 // set the items background colour
171 void SetItemBackgroundColour(const wxTreeItemId
& item
, const wxColour
& col
);
173 // set the items font (should be of the same height for all items)
174 void SetItemFont(const wxTreeItemId
& item
, const wxFont
& font
);
176 // item status inquiries
177 // ---------------------
179 // is the item visible (it might be outside the view or not expanded)?
180 bool IsVisible(const wxTreeItemId
& item
) const;
181 // does the item has any children?
182 bool ItemHasChildren(const wxTreeItemId
& item
) const;
183 // is the item expanded (only makes sense if HasChildren())?
184 bool IsExpanded(const wxTreeItemId
& item
) const;
185 // is this item currently selected (the same as has focus)?
186 bool IsSelected(const wxTreeItemId
& item
) const;
187 // is item text in bold font?
188 bool IsBold(const wxTreeItemId
& item
) const;
190 // number of children
191 // ------------------
193 // if 'recursively' is false, only immediate children count, otherwise
194 // the returned number is the number of all items in this branch
195 size_t GetChildrenCount(const wxTreeItemId
& item
,
196 bool recursively
= true) const;
201 // wxTreeItemId.IsOk() will return false if there is no such item
203 // get the root tree item
204 wxTreeItemId
GetRootItem() const;
206 // get the item currently selected (may return NULL if no selection)
207 wxTreeItemId
GetSelection() const;
209 // get the items currently selected, return the number of such item
211 // NB: this operation is expensive and can take a long time for a
212 // control with a lot of items (~ O(number of items)).
213 size_t GetSelections(wxArrayTreeItemIds
& selections
) const;
215 // get the parent of this item (may return NULL if root)
216 wxTreeItemId
GetItemParent(const wxTreeItemId
& item
) const;
218 // for this enumeration function you must pass in a "cookie" parameter
219 // which is opaque for the application but is necessary for the library
220 // to make these functions reentrant (i.e. allow more than one
221 // enumeration on one and the same object simultaneously). Of course,
222 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
225 // get the first child of this item
226 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
,
227 wxTreeItemIdValue
& cookie
) const;
228 // get the next child
229 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
,
230 wxTreeItemIdValue
& cookie
) const;
231 // get the last child of this item - this method doesn't use cookies
232 wxTreeItemId
GetLastChild(const wxTreeItemId
& item
) const;
234 // get the next sibling of this item
235 wxTreeItemId
GetNextSibling(const wxTreeItemId
& item
) const;
236 // get the previous sibling
237 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& item
) const;
239 // get first visible item
240 wxTreeItemId
GetFirstVisibleItem() const;
241 // get the next visible item: item must be visible itself!
242 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
243 wxTreeItemId
GetNextVisible(const wxTreeItemId
& item
) const;
244 // get the previous visible item: item must be visible itself!
245 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& item
) const;
250 // add the root node to the tree
251 wxTreeItemId
AddRoot(const wxString
& text
,
252 int image
= -1, int selectedImage
= -1,
253 wxTreeItemData
*data
= NULL
);
255 // insert a new item in as the first child of the parent
256 wxTreeItemId
PrependItem(const wxTreeItemId
& parent
,
257 const wxString
& text
,
258 int image
= -1, int selectedImage
= -1,
259 wxTreeItemData
*data
= NULL
);
261 // insert a new item after a given one
262 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
263 const wxTreeItemId
& idPrevious
,
264 const wxString
& text
,
265 int image
= -1, int selectedImage
= -1,
266 wxTreeItemData
*data
= NULL
);
268 // insert a new item before the one with the given index
269 wxTreeItemId
InsertItem(const wxTreeItemId
& parent
,
271 const wxString
& text
,
272 int image
= -1, int selectedImage
= -1,
273 wxTreeItemData
*data
= NULL
);
275 // insert a new item in as the last child of the parent
276 wxTreeItemId
AppendItem(const wxTreeItemId
& parent
,
277 const wxString
& text
,
278 int image
= -1, int selectedImage
= -1,
279 wxTreeItemData
*data
= NULL
);
281 // delete this item and associated data if any
282 void Delete(const wxTreeItemId
& item
);
283 // delete all children (but don't delete the item itself)
284 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
285 void DeleteChildren(const wxTreeItemId
& item
);
286 // delete all items from the tree
287 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
288 void DeleteAllItems();
291 void Expand(const wxTreeItemId
& item
);
292 // collapse the item without removing its children
293 void Collapse(const wxTreeItemId
& item
);
294 // collapse the item and remove all children
295 void CollapseAndReset(const wxTreeItemId
& item
);
296 // toggles the current state
297 void Toggle(const wxTreeItemId
& item
);
299 // remove the selection from currently selected item (if any)
301 // unselect all items (only makes sense for multiple selection control)
304 void SelectItem(const wxTreeItemId
& item
, bool select
= true);
305 // unselect this item
306 void UnselectItem(const wxTreeItemId
& item
);
307 // toggle item selection
308 void ToggleItemSelection(const wxTreeItemId
& 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
);
316 // start editing the item label: this (temporarily) replaces the item
317 // with a one line edit control. The item will be selected if it hadn't
318 // been before. textCtrlClass parameter allows you to create an edit
319 // control of arbitrary user-defined class deriving from wxTextCtrl.
320 wxTextCtrl
* EditLabel(const wxTreeItemId
& item
,
321 wxClassInfo
* textCtrlClass
= CLASSINFO(wxTextCtrl
));
322 // returns the same pointer as StartEdit() if the item is being edited,
323 // NULL otherwise (it's assumed that no more than one item may be
324 // edited simultaneously)
325 wxTextCtrl
* GetEditControl() const;
326 // end editing and accept or discard the changes to item label
327 void EndEditLabel(const wxTreeItemId
& item
, bool discardChanges
= false);
330 // this function is called to compare 2 items and should return -1, 0
331 // or +1 if the first item is less than, equal to or greater than the
332 // second one. The base class version performs alphabetic comparaison
333 // of item labels (GetText)
334 virtual int OnCompareItems(const wxTreeItemId
& item1
,
335 const wxTreeItemId
& item2
);
336 // sort the children of this item using OnCompareItems
338 // NB: this function is not reentrant and not MT-safe (FIXME)!
339 void SortChildren(const wxTreeItemId
& item
);
344 // determine to which item (if any) belongs the given point (the
345 // coordinates specified are relative to the client area of tree ctrl)
346 // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx
349 // The first function is more portable (because easier to implement
350 // on other platforms), but the second one returns some extra info.
351 wxTreeItemId
HitTest(const wxPoint
& point
)
352 { int dummy
; return HitTest(point
, dummy
); }
353 wxTreeItemId
HitTest(const wxPoint
& point
, int& flags
);
355 // get the bounding rectangle of the item (or of its label only)
356 bool GetBoundingRect(const wxTreeItemId
& item
,
358 bool textOnly
= false) const;
363 virtual bool ShouldInheritColours() const { return false; }
365 virtual wxVisualAttributes
GetDefaultAttributes() const
367 return GetClassDefaultAttributes(GetWindowVariant());
370 static wxVisualAttributes
371 GetClassDefaultAttributes(wxWindowVariant variant
= wxWINDOW_VARIANT_NORMAL
);
373 // override some base class virtuals
374 virtual bool SetBackgroundColour(const wxColour
&colour
);
375 virtual bool SetForegroundColour(const wxColour
&colour
);
377 // get/set the check state for the item (only for wxTR_MULTIPLE)
378 bool IsItemChecked(const wxTreeItemId
& item
) const;
379 void SetItemCheck(const wxTreeItemId
& item
, bool check
= true);
381 // set/get the item state.image (state == -1 means cycle to the next one)
382 void SetState(const wxTreeItemId
& node
, int state
);
383 int GetState(const wxTreeItemId
& node
);
386 // SetImageList helper
387 void SetAnyImageList(wxImageList
*imageList
, int which
);
389 // refresh a single item
390 void RefreshItem(const wxTreeItemId
& item
);
392 wxTextCtrl
*m_textCtrl
; // used while editing the item label
393 wxImageList
*m_imageListNormal
, // images for tree elements
394 *m_imageListState
; // special images for app defined states
395 bool m_ownsImageListNormal
, m_ownsImageListState
;
398 // the common part of all ctors
402 inline bool DoGetItem(wxTreeViewItem
*tvItem
) const;
403 inline void DoSetItem(wxTreeViewItem
*tvItem
);
405 inline void DoExpand(const wxTreeItemId
& item
, int flag
);
407 wxTreeItemId
DoInsertItem(const wxTreeItemId
& parent
,
408 wxTreeItemId hInsertAfter
,
409 const wxString
& text
,
410 int image
, int selectedImage
,
411 wxTreeItemData
*data
);
413 int DoGetItemImageFromData(const wxTreeItemId
& item
,
414 wxTreeItemIcon which
) const;
415 void DoSetItemImageFromData(const wxTreeItemId
& item
,
417 wxTreeItemIcon which
) const;
418 void DoSetItemImages(const wxTreeItemId
& item
, int image
, int imageSel
);
420 void DeleteTextCtrl();
422 // support for additional item images which we implement using
423 // wxTreeItemIndirectData technique
424 void SetIndirectItemData(const wxTreeItemId
& item
,
425 class wxTreeItemIndirectData
*data
);
426 bool HasIndirectData(const wxTreeItemId
& item
) const;
427 bool IsDataIndirect(wxTreeItemData
*data
) const
428 { return data
&& data
->GetId().m_pItem
== 0; }
430 // the hash storing the items attributes (indexed by item ids)
431 wxMapTreeAttr m_attrs
;
433 // true if the hash above is not empty
437 wxDragImage
*m_dragImage
;
439 // Virtual root item, if wxTR_HIDE_ROOT is set.
440 void* m_pVirtualRoot
;
442 // the starting item for selection with Shift
443 wxTreeItemId m_htSelStart
;
445 friend class wxTreeItemIndirectData
;
446 friend class wxTreeSortHelper
;
448 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
449 DECLARE_NO_COPY_CLASS(wxTreeCtrl
)
452 #endif // wxUSE_TREECTRL
454 #endif // _WX_TREECTRL_H_