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