]> git.saurik.com Git - wxWidgets.git/blob - include/wx/msw/treectrl.h
added wxUSE_STDPATHS
[wxWidgets.git] / include / wx / msw / treectrl.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/msw/treectrl.h
3 // Purpose: wxTreeCtrl class
4 // Author: Julian Smart
5 // Modified by: Vadim Zeitlin to be less MSW-specific on 10/10/98
6 // Created: 01/02/97
7 // RCS-ID: $Id$
8 // Copyright: (c) Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_TREECTRL_H_
13 #define _WX_TREECTRL_H_
14
15 // ----------------------------------------------------------------------------
16 // headers
17 // ----------------------------------------------------------------------------
18
19 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
20 #pragma interface "treectrl.h"
21 #endif
22
23 #if wxUSE_TREECTRL
24
25 #include "wx/textctrl.h"
26 #include "wx/dynarray.h"
27 #include "wx/treebase.h"
28 #include "wx/hashmap.h"
29
30 #ifdef __GNUWIN32__
31 // Cygwin windows.h defines these identifiers
32 #undef GetFirstChild
33 #undef GetNextSibling
34 #endif // Cygwin
35
36 // fwd decl
37 class WXDLLEXPORT wxImageList;
38 class WXDLLEXPORT wxDragImage;
39 struct WXDLLEXPORT wxTreeViewItem;
40
41 // NB: all the following flags are for compatbility only and will be removed in the
42 // next versions
43
44 // flags for deprecated `Expand(int action)'
45 enum
46 {
47 wxTREE_EXPAND_EXPAND,
48 wxTREE_EXPAND_COLLAPSE,
49 wxTREE_EXPAND_COLLAPSE_RESET,
50 wxTREE_EXPAND_TOGGLE
51 };
52
53 // flags for deprecated InsertItem() variant (their values are the same as of
54 // TVI_FIRST and TVI_LAST)
55 #define wxTREE_INSERT_FIRST 0xFFFF0001
56 #define wxTREE_INSERT_LAST 0xFFFF0002
57
58 // hash storing attributes for our items
59 WX_DECLARE_EXPORTED_VOIDPTR_HASH_MAP(wxTreeItemAttr *, wxMapTreeAttr);
60
61 // ----------------------------------------------------------------------------
62 // wxTreeCtrl
63 // ----------------------------------------------------------------------------
64
65 class WXDLLEXPORT wxTreeCtrl : public wxControl
66 {
67 public:
68 // creation
69 // --------
70 wxTreeCtrl() { Init(); }
71
72 wxTreeCtrl(wxWindow *parent, wxWindowID id = wxID_ANY,
73 const wxPoint& pos = wxDefaultPosition,
74 const wxSize& size = wxDefaultSize,
75 long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
76 const wxValidator& validator = wxDefaultValidator,
77 const wxString& name = wxTreeCtrlNameStr)
78 {
79 Create(parent, id, pos, size, style, validator, name);
80 }
81
82 virtual ~wxTreeCtrl();
83
84 bool Create(wxWindow *parent, wxWindowID id = wxID_ANY,
85 const wxPoint& pos = wxDefaultPosition,
86 const wxSize& size = wxDefaultSize,
87 long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
88 const wxValidator& validator = wxDefaultValidator,
89 const wxString& name = wxTreeCtrlNameStr);
90
91 // accessors
92 // ---------
93
94 // get the total number of items in the control
95 size_t GetCount() const;
96
97 // indent is the number of pixels the children are indented relative to
98 // the parents position. SetIndent() also redraws the control
99 // immediately.
100 unsigned int GetIndent() const;
101 void SetIndent(unsigned int indent);
102
103 // spacing is the number of pixels between the start and the Text
104 // not implemented under wxMSW
105 unsigned int GetSpacing() const { return 18; } // return wxGTK default
106 void SetSpacing(unsigned int WXUNUSED(spacing)) { }
107
108 // image list: these functions allow to associate an image list with
109 // the control and retrieve it. Note that the control does _not_ delete
110 // the associated image list when it's deleted in order to allow image
111 // lists to be shared between different controls.
112 //
113 // The normal image list is for the icons which correspond to the
114 // normal tree item state (whether it is selected or not).
115 // Additionally, the application might choose to show a state icon
116 // which corresponds to an app-defined item state (for example,
117 // checked/unchecked) which are taken from the state image list.
118 virtual wxImageList *GetImageList() const;
119 virtual wxImageList *GetStateImageList() const;
120
121 virtual void SetImageList(wxImageList *imageList);
122 virtual void SetStateImageList(wxImageList *imageList);
123 virtual void AssignImageList(wxImageList *imageList);
124 virtual void AssignStateImageList(wxImageList *imageList);
125
126 // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
127 // member functions of wxTreeItem because they must know the tree the item
128 // belongs to for Windows implementation and storing the pointer to
129 // wxTreeCtrl in each wxTreeItem is just too much waste.
130
131 // accessors
132 // ---------
133
134 // retrieve items label
135 wxString GetItemText(const wxTreeItemId& item) const;
136 // get one of the images associated with the item (normal by default)
137 virtual int GetItemImage(const wxTreeItemId& item,
138 wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
139 // get the data associated with the item
140 wxTreeItemData *GetItemData(const wxTreeItemId& item) const;
141
142 // get the item's text colour
143 wxColour GetItemTextColour(const wxTreeItemId& item) const;
144
145 // get the item's background colour
146 wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
147
148 // get the item's font
149 wxFont GetItemFont(const wxTreeItemId& item) const;
150
151 // modifiers
152 // ---------
153
154 // set items label
155 void SetItemText(const wxTreeItemId& item, const wxString& text);
156 // get one of the images associated with the item (normal by default)
157 virtual void SetItemImage(const wxTreeItemId& item, int image,
158 wxTreeItemIcon which = wxTreeItemIcon_Normal);
159 // associate some data with the item
160 void SetItemData(const wxTreeItemId& item, wxTreeItemData *data);
161
162 // force appearance of [+] button near the item. This is useful to
163 // allow the user to expand the items which don't have any children now
164 // - but instead add them only when needed, thus minimizing memory
165 // usage and loading time.
166 void SetItemHasChildren(const wxTreeItemId& item, bool has = true);
167
168 // the item will be shown in bold
169 void SetItemBold(const wxTreeItemId& item, bool bold = true);
170
171 // the item will be shown with a drop highlight
172 void SetItemDropHighlight(const wxTreeItemId& item, bool highlight = true);
173
174 // set the items text colour
175 void SetItemTextColour(const wxTreeItemId& item, const wxColour& col);
176
177 // set the items background colour
178 void SetItemBackgroundColour(const wxTreeItemId& item, const wxColour& col);
179
180 // set the items font (should be of the same height for all items)
181 void SetItemFont(const wxTreeItemId& item, const wxFont& font);
182
183 // item status inquiries
184 // ---------------------
185
186 // is the item visible (it might be outside the view or not expanded)?
187 bool IsVisible(const wxTreeItemId& item) const;
188 // does the item has any children?
189 bool ItemHasChildren(const wxTreeItemId& item) const;
190 // is the item expanded (only makes sense if HasChildren())?
191 bool IsExpanded(const wxTreeItemId& item) const;
192 // is this item currently selected (the same as has focus)?
193 bool IsSelected(const wxTreeItemId& item) const;
194 // is item text in bold font?
195 bool IsBold(const wxTreeItemId& item) const;
196
197 // number of children
198 // ------------------
199
200 // if 'recursively' is false, only immediate children count, otherwise
201 // the returned number is the number of all items in this branch
202 size_t GetChildrenCount(const wxTreeItemId& item,
203 bool recursively = true) const;
204
205 // navigation
206 // ----------
207
208 // wxTreeItemId.IsOk() will return false if there is no such item
209
210 // get the root tree item
211 wxTreeItemId GetRootItem() const;
212
213 // get the item currently selected (may return NULL if no selection)
214 wxTreeItemId GetSelection() const;
215
216 // get the items currently selected, return the number of such item
217 //
218 // NB: this operation is expensive and can take a long time for a
219 // control with a lot of items (~ O(number of items)).
220 size_t GetSelections(wxArrayTreeItemIds& selections) const;
221
222 // get the parent of this item (may return NULL if root)
223 wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
224
225 #if WXWIN_COMPATIBILITY_2_2
226 // deprecated: Use GetItemParent instead.
227 wxDEPRECATED( wxTreeItemId GetParent(const wxTreeItemId& item) const);
228
229 // Expose the base class method hidden by the one above. Not deprecatable.
230 wxWindow *GetParent() const { return wxControl::GetParent(); }
231 #endif // WXWIN_COMPATIBILITY_2_2
232
233 // for this enumeration function you must pass in a "cookie" parameter
234 // which is opaque for the application but is necessary for the library
235 // to make these functions reentrant (i.e. allow more than one
236 // enumeration on one and the same object simultaneously). Of course,
237 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
238 // the same!
239
240 // get the first child of this item
241 wxTreeItemId GetFirstChild(const wxTreeItemId& item,
242 wxTreeItemIdValue& cookie) const;
243 // get the next child
244 wxTreeItemId GetNextChild(const wxTreeItemId& item,
245 wxTreeItemIdValue& cookie) const;
246 // get the last child of this item - this method doesn't use cookies
247 wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
248
249 // get the next sibling of this item
250 wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
251 // get the previous sibling
252 wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
253
254 // get first visible item
255 wxTreeItemId GetFirstVisibleItem() const;
256 // get the next visible item: item must be visible itself!
257 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
258 wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
259 // get the previous visible item: item must be visible itself!
260 wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
261
262 // operations
263 // ----------
264
265 // add the root node to the tree
266 virtual wxTreeItemId AddRoot(const wxString& text,
267 int image = -1, int selectedImage = -1,
268 wxTreeItemData *data = NULL);
269
270 // insert a new item in as the first child of the parent
271 virtual wxTreeItemId PrependItem(const wxTreeItemId& parent,
272 const wxString& text,
273 int image = -1, int selectedImage = -1,
274 wxTreeItemData *data = NULL);
275
276 // insert a new item after a given one
277 virtual wxTreeItemId InsertItem(const wxTreeItemId& parent,
278 const wxTreeItemId& idPrevious,
279 const wxString& text,
280 int image = -1, int selectedImage = -1,
281 wxTreeItemData *data = NULL);
282
283 // insert a new item before the one with the given index
284 virtual wxTreeItemId InsertItem(const wxTreeItemId& parent,
285 size_t index,
286 const wxString& text,
287 int image = -1, int selectedImage = -1,
288 wxTreeItemData *data = NULL);
289
290 // insert a new item in as the last child of the parent
291 virtual wxTreeItemId AppendItem(const wxTreeItemId& parent,
292 const wxString& text,
293 int image = -1, int selectedImage = -1,
294 wxTreeItemData *data = NULL);
295
296 // delete this item and associated data if any
297 void Delete(const wxTreeItemId& item);
298 // delete all children (but don't delete the item itself)
299 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
300 void DeleteChildren(const wxTreeItemId& item);
301 // delete all items from the tree
302 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
303 void DeleteAllItems();
304
305 // expand this item
306 void Expand(const wxTreeItemId& item);
307 // collapse the item without removing its children
308 void Collapse(const wxTreeItemId& item);
309 // collapse the item and remove all children
310 void CollapseAndReset(const wxTreeItemId& item);
311 // toggles the current state
312 void Toggle(const wxTreeItemId& item);
313
314 // remove the selection from currently selected item (if any)
315 void Unselect();
316 // unselect all items (only makes sense for multiple selection control)
317 void UnselectAll();
318 // select this item
319 void SelectItem(const wxTreeItemId& item, bool select = true);
320 // unselect this item
321 void UnselectItem(const wxTreeItemId& item);
322 // toggle item selection
323 void ToggleItemSelection(const wxTreeItemId& item);
324
325 // make sure this item is visible (expanding the parent item and/or
326 // scrolling to this item if necessary)
327 void EnsureVisible(const wxTreeItemId& item);
328 // scroll to this item (but don't expand its parent)
329 void ScrollTo(const wxTreeItemId& item);
330
331 // start editing the item label: this (temporarily) replaces the item
332 // with a one line edit control. The item will be selected if it hadn't
333 // been before. textCtrlClass parameter allows you to create an edit
334 // control of arbitrary user-defined class deriving from wxTextCtrl.
335 wxTextCtrl* EditLabel(const wxTreeItemId& item,
336 wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl));
337 // returns the same pointer as StartEdit() if the item is being edited,
338 // NULL otherwise (it's assumed that no more than one item may be
339 // edited simultaneously)
340 wxTextCtrl* GetEditControl() const;
341 // end editing and accept or discard the changes to item label
342 void EndEditLabel(const wxTreeItemId& WXUNUSED(item),
343 bool discardChanges = false)
344 {
345 DoEndEditLabel(discardChanges);
346 }
347
348 // sorting
349 // this function is called to compare 2 items and should return -1, 0
350 // or +1 if the first item is less than, equal to or greater than the
351 // second one. The base class version performs alphabetic comparaison
352 // of item labels (GetText)
353 virtual int OnCompareItems(const wxTreeItemId& item1,
354 const wxTreeItemId& item2);
355 // sort the children of this item using OnCompareItems
356 //
357 // NB: this function is not reentrant and not MT-safe (FIXME)!
358 void SortChildren(const wxTreeItemId& item);
359
360 // helpers
361 // -------
362
363 // determine to which item (if any) belongs the given point (the
364 // coordinates specified are relative to the client area of tree ctrl)
365 // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx
366 // constants.
367 //
368 // The first function is more portable (because easier to implement
369 // on other platforms), but the second one returns some extra info.
370 wxTreeItemId HitTest(const wxPoint& point)
371 { int dummy; return HitTest(point, dummy); }
372 wxTreeItemId HitTest(const wxPoint& point, int& flags);
373
374 // get the bounding rectangle of the item (or of its label only)
375 bool GetBoundingRect(const wxTreeItemId& item,
376 wxRect& rect,
377 bool textOnly = false) const;
378
379 // deprecated
380 // ----------
381
382 #if WXWIN_COMPATIBILITY_2_4
383 // these methods are deprecated and will be removed in future versions of
384 // wxWidgets, they're here for compatibility only, don't use them in new
385 // code (the comments indicate why these methods are now useless and how to
386 // replace them)
387
388 // use Expand, Collapse, CollapseAndReset or Toggle
389 wxDEPRECATED( void ExpandItem(const wxTreeItemId& item, int action) );
390
391 // use AddRoot, PrependItem or AppendItem
392 wxDEPRECATED( wxTreeItemId InsertItem(const wxTreeItemId& parent,
393 const wxString& text,
394 int image = -1, int selImage = -1,
395 long insertAfter = wxTREE_INSERT_LAST) );
396
397 // use Set/GetImageList and Set/GetStateImageList
398 wxDEPRECATED( wxImageList *GetImageList(int) const );
399 wxDEPRECATED( void SetImageList(wxImageList *imageList, int) );
400
401 // use Set/GetItemImage directly
402 wxDEPRECATED( int GetItemSelectedImage(const wxTreeItemId& item) const );
403 wxDEPRECATED( void SetItemSelectedImage(const wxTreeItemId& item, int image) );
404
405 // use the versions taking wxTreeItemIdValue cookies
406 wxDEPRECATED( wxTreeItemId GetFirstChild(const wxTreeItemId& item,
407 long& cookie) const );
408 wxDEPRECATED( wxTreeItemId GetNextChild(const wxTreeItemId& item,
409 long& cookie) const );
410 #endif // WXWIN_COMPATIBILITY_2_4
411
412
413 // implementation
414 // --------------
415
416 virtual bool ShouldInheritColours() const { return false; }
417
418 virtual wxVisualAttributes GetDefaultAttributes() const
419 {
420 return GetClassDefaultAttributes(GetWindowVariant());
421 }
422
423 static wxVisualAttributes
424 GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
425
426
427 virtual WXLRESULT MSWWindowProc(WXUINT nMsg, WXWPARAM wParam, WXLPARAM lParam);
428 virtual bool MSWCommand(WXUINT param, WXWORD id);
429 virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
430
431 // override some base class virtuals
432 virtual bool SetBackgroundColour(const wxColour &colour);
433 virtual bool SetForegroundColour(const wxColour &colour);
434
435 // get/set the check state for the item (only for wxTR_MULTIPLE)
436 bool IsItemChecked(const wxTreeItemId& item) const;
437 void SetItemCheck(const wxTreeItemId& item, bool check = true);
438
439 // set/get the item state.image (state == -1 means cycle to the next one)
440 void SetState(const wxTreeItemId& node, int state);
441 int GetState(const wxTreeItemId& node);
442
443 protected:
444 // SetImageList helper
445 void SetAnyImageList(wxImageList *imageList, int which);
446
447 // refresh a single item
448 void RefreshItem(const wxTreeItemId& item);
449
450 // end edit label
451 void DoEndEditLabel(bool discardChanges = false);
452
453
454 // data used only while editing the item label:
455 wxTextCtrl *m_textCtrl; // text control in which it is edited
456 wxTreeItemId m_idEdited; // the item being edited
457
458 wxImageList *m_imageListNormal, // images for tree elements
459 *m_imageListState; // special images for app defined states
460 bool m_ownsImageListNormal,
461 m_ownsImageListState;
462
463 private:
464 // the common part of all ctors
465 void Init();
466
467 // helper functions
468 inline bool DoGetItem(wxTreeViewItem *tvItem) const;
469 inline void DoSetItem(wxTreeViewItem *tvItem);
470
471 inline void DoExpand(const wxTreeItemId& item, int flag);
472
473 wxTreeItemId DoInsertItem(const wxTreeItemId& parent,
474 wxTreeItemId hInsertAfter,
475 const wxString& text,
476 int image, int selectedImage,
477 wxTreeItemData *data);
478
479 int DoGetItemImageFromData(const wxTreeItemId& item,
480 wxTreeItemIcon which) const;
481 void DoSetItemImageFromData(const wxTreeItemId& item,
482 int image,
483 wxTreeItemIcon which) const;
484 void DoSetItemImages(const wxTreeItemId& item, int image, int imageSel);
485
486 void DeleteTextCtrl();
487
488 // support for additional item images which we implement using
489 // wxTreeItemIndirectData technique - see the comments in msw/treectrl.cpp
490 void SetIndirectItemData(const wxTreeItemId& item,
491 class wxTreeItemIndirectData *data);
492 bool HasIndirectData(const wxTreeItemId& item) const;
493 bool IsDataIndirect(wxTreeItemData *data) const
494 { return data && data->GetId().m_pItem == 0; }
495
496 // the hash storing the items attributes (indexed by item ids)
497 wxMapTreeAttr m_attrs;
498
499 // true if the hash above is not empty
500 bool m_hasAnyAttr;
501
502 // used for dragging
503 wxDragImage *m_dragImage;
504
505 // Virtual root item, if wxTR_HIDE_ROOT is set.
506 void* m_pVirtualRoot;
507
508 // the starting item for selection with Shift
509 wxTreeItemId m_htSelStart;
510
511 friend class wxTreeItemIndirectData;
512 friend class wxTreeSortHelper;
513
514 DECLARE_DYNAMIC_CLASS(wxTreeCtrl)
515 DECLARE_NO_COPY_CLASS(wxTreeCtrl)
516 };
517
518 #endif // wxUSE_TREECTRL
519
520 #endif
521 // _WX_TREECTRL_H_