]> git.saurik.com Git - wxWidgets.git/blob - interface/treectrl.h
use @deprecated doxygen tag, a few other minor corrections (#9564)
[wxWidgets.git] / interface / treectrl.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: treectrl.h
3 // Purpose: interface of wxTreeItemData
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 /**
11 @class wxTreeCtrl
12 @wxheader{treectrl.h}
13
14 A tree control presents information as a hierarchy, with items that may be
15 expanded to show further items. Items in a tree control are referenced by
16 wxTreeItemId handles, which may be tested for validity by calling
17 wxTreeItemId::IsOk().
18
19 A similar control with a fully native implemtation for GTK+ and OS X
20 as well is wxDataViewTreeCtrl.
21
22 To intercept events from a tree control, use the event table macros
23 described in wxTreeEvent.
24
25 @beginStyleTable
26 @style{wxTR_EDIT_LABELS}
27 Use this style if you wish the user to be able to edit labels in the
28 tree control.
29 @style{wxTR_NO_BUTTONS}
30 For convenience to document that no buttons are to be drawn.
31 @style{wxTR_HAS_BUTTONS}
32 Use this style to show + and - buttons to the left of parent items.
33 @style{wxTR_NO_LINES}
34 Use this style to hide vertical level connectors.
35 @style{wxTR_FULL_ROW_HIGHLIGHT}
36 Use this style to have the background colour and the selection highlight
37 extend over the entire horizontal row of the tree control window. (This
38 flag is ignored under Windows unless you specify @c wxTR_NO_LINES as
39 well.)
40 @style{wxTR_LINES_AT_ROOT}
41 Use this style to show lines between root nodes. Only applicable if @c
42 wxTR_HIDE_ROOT is set and @c wxTR_NO_LINES is not set.
43 @style{wxTR_HIDE_ROOT}
44 Use this style to suppress the display of the root node, effectively
45 causing the first-level nodes to appear as a series of root nodes.
46 @style{wxTR_ROW_LINES}
47 Use this style to draw a contrasting border between displayed rows.
48 @style{wxTR_HAS_VARIABLE_ROW_HEIGHT}
49 Use this style to cause row heights to be just big enough to fit the
50 content. If not set, all rows use the largest row height. The default is
51 that this flag is unset. Generic only.
52 @style{wxTR_SINGLE}
53 For convenience to document that only one item may be selected at a
54 time. Selecting another item causes the current selection, if any, to be
55 deselected. This is the default.
56 @style{wxTR_MULTIPLE}
57 Use this style to allow a range of items to be selected. If a second
58 range is selected, the current range, if any, is deselected.
59 @style{wxTR_DEFAULT_STYLE}
60 The set of flags that are closest to the defaults for the native control
61 for a particular toolkit.
62 @endStyleTable
63
64 See also @ref overview_windowstyles.
65
66 @b Win32 @b notes:
67
68 wxTreeCtrl class uses the standard common treeview control under Win32
69 implemented in the system library comctl32.dll. Some versions of this
70 library are known to have bugs with handling the tree control colours: the
71 usual symptom is that the expanded items leave black (or otherwise
72 incorrectly coloured) background behind them, especially for the controls
73 using non-default background colour. The recommended solution is to upgrade
74 the comctl32.dll to a newer version: see
75 http://www.microsoft.com/downloads/details.aspx?familyid=cb2cf3a2-8025-4e8f-8511-9b476a8d35d2
76
77 @library{wxcore}
78 @category{ctrl}
79 <!-- @appearance{treectrl.png} -->
80
81 @see wxDataViewTreeCtrl, wxTreeEvent, wxTreeItemData, @ref overview_treectrl, wxListBox,
82 wxListCtrl, wxImageList
83 */
84 class wxTreeCtrl : public wxControl
85 {
86 public:
87 /**
88 Default Constructor.
89 */
90 wxTreeCtrl();
91
92 /**
93 Constructor, creating and showing a tree control.
94
95 @param parent
96 Parent window. Must not be @NULL.
97 @param id
98 Window identifier. The value @c wxID_ANY indicates a default value.
99 @param pos
100 Window position.
101 @param size
102 Window size. If wxDefaultSize is specified then the window is sized
103 appropriately.
104 @param style
105 Window style. See wxTreeCtrl.
106 @param validator
107 Window validator.
108 @param name
109 Window name.
110
111 @see Create(), wxValidator
112 */
113 wxTreeCtrl(wxWindow* parent, wxWindowID id,
114 const wxPoint& pos = wxDefaultPosition,
115 const wxSize& size = wxDefaultSize,
116 long style = wxTR_HAS_BUTTONS,
117 const wxValidator& validator = wxDefaultValidator,
118 const wxString& name = "treeCtrl");
119
120
121 /**
122 Destructor, destroying the tree control.
123 */
124 ~wxTreeCtrl();
125
126 /**
127 Adds the root node to the tree, returning the new item.
128
129 The @a image and @a selImage parameters are an index within the normal
130 image list specifying the image to use for unselected and selected
131 items, respectively. If @a image -1 and @a selImage is -1, the same
132 image is used for both selected and unselected items.
133 */
134 wxTreeItemId AddRoot(const wxString& text, int image = -1,
135 int selImage = -1,
136 wxTreeItemData* data = NULL);
137
138 /**
139 Appends an item to the end of the branch identified by @a parent, return
140 a new item id.
141
142 The @a image and @a selImage parameters are an index within the normal
143 image list specifying the image to use for unselected and selected
144 items, respectively. If @a image -1 and @a selImage is -1, the same
145 image is used for both selected and unselected items.
146 */
147 wxTreeItemId AppendItem(const wxTreeItemId& parent,
148 const wxString& text,
149 int image = -1,
150 int selImage = -1,
151 wxTreeItemData* data = NULL);
152
153 /**
154 Sets the buttons image list. The button images assigned with this method
155 will be automatically deleted by wxTreeCtrl as appropriate (i.e. it
156 takes ownership of the list).
157
158 Setting or assigning the button image list enables the display of image
159 buttons. Once enabled, the only way to disable the display of button
160 images is to set the button image list to @NULL.
161
162 This function is only available in the generic version.
163
164 @see SetButtonsImageList().
165 */
166 void AssignButtonsImageList(wxImageList* imageList);
167
168 /**
169 Sets the normal image list. The image list assigned with this method
170 will be automatically deleted by wxTreeCtrl as appropriate (i.e. it
171 takes ownership of the list).
172
173 @see SetImageList().
174 */
175 void AssignImageList(wxImageList* imageList);
176
177 /**
178 Sets the state image list. Image list assigned with this method will be
179 automatically deleted by wxTreeCtrl as appropriate (i.e. it takes
180 ownership of the list).
181
182 @see SetStateImageList().
183 */
184 void AssignStateImageList(wxImageList* imageList);
185
186 /**
187 Collapses the given item.
188 */
189 void Collapse(const wxTreeItemId& item);
190
191 /**
192 Collapses the root item.
193
194 @see ExpandAll()
195 */
196 void CollapseAll();
197
198 /**
199 Collapses this item and all of its children, recursively.
200
201 @see ExpandAllChildren()
202 */
203 void CollapseAllChildren(const wxTreeItemId& item);
204
205 /**
206 Collapses the given item and removes all children.
207 */
208 void CollapseAndReset(const wxTreeItemId& item);
209
210 /**
211 Creates the tree control. See wxTreeCtrl::wxTreeCtrl() for further
212 details.
213 */
214 bool Create(wxWindow* parent, wxWindowID id,
215 const wxPoint& pos = wxDefaultPosition,
216 const wxSize& size = wxDefaultSize,
217 long style = wxTR_HAS_BUTTONS,
218 const wxValidator& validator = wxDefaultValidator,
219 const wxString& name = "treeCtrl");
220
221 /**
222 Deletes the specified item. A EVT_TREE_DELETE_ITEM() event will be
223 generated.
224
225 This function may cause a subsequent call to GetNextChild() to fail.
226 */
227 void Delete(const wxTreeItemId& item);
228
229 /**
230 Deletes all items in the control. Note that this may not generate
231 EVT_TREE_DELETE_ITEM() events under some Windows versions although
232 normally such event is generated for each removed item.
233 */
234 void DeleteAllItems();
235
236 /**
237 Deletes all children of the given item (but not the item itself). Note
238 that this will @b not generate any events unlike Delete() method.
239
240 If you have called SetItemHasChildren(), you may need to call it again
241 since DeleteChildren() does not automatically clear the setting.
242 */
243 void DeleteChildren(const wxTreeItemId& item);
244
245 /**
246 Starts editing the label of the given @a item. This function generates a
247 EVT_TREE_BEGIN_LABEL_EDIT() event which can be vetoed so that no text
248 control will appear for in-place editing.
249
250 If the user changed the label (i.e. s/he does not press ESC or leave the
251 text control without changes, a EVT_TREE_END_LABEL_EDIT() event will be
252 sent which can be vetoed as well.
253
254 @see EndEditLabel(), wxTreeEvent
255 */
256 void EditLabel(const wxTreeItemId& item);
257
258 /**
259 Ends label editing. If @a cancelEdit is @true, the edit will be
260 cancelled.
261
262 @note
263 This function is currently supported under Windows only.
264
265 @see EditLabel()
266 */
267 void EndEditLabel(bool cancelEdit);
268
269 /**
270 Scrolls and/or expands items to ensure that the given item is visible.
271 */
272 void EnsureVisible(const wxTreeItemId& item);
273
274 /**
275 Expands the given item.
276 */
277 void Expand(const wxTreeItemId& item);
278
279 /**
280 Expands all items in the tree.
281 */
282 void ExpandAll();
283
284 /**
285 Expands the given item and all its children recursively.
286 */
287 void ExpandAllChildren(const wxTreeItemId& item);
288
289 /**
290 Retrieves the rectangle bounding the @a item. If @a textOnly is @true,
291 only the rectangle around the item's label will be returned, otherwise
292 the item's image is also taken into account.
293
294 The return value is @true if the rectangle was successfully retrieved or
295 @c @false if it was not (in this case @a rect is not changed) -- for
296 example, if the item is currently invisible.
297
298 Notice that the rectangle coordinates are logical, not physical ones.
299 So, for example, the x coordinate may be negative if the tree has a
300 horizontal scrollbar and its position is not 0.
301
302 @beginWxPythonOnly
303 The wxPython version of this method requires only the @a item and @a
304 textOnly parameters. The return value is either a wxRect object or @c
305 None.
306 @endWxPythonOnly
307 */
308 bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect,
309 bool textOnly = false) const;
310
311 /**
312 Returns the buttons image list (from which application-defined button
313 images are taken).
314
315 This function is only available in the generic version.
316 */
317 wxImageList* GetButtonsImageList() const;
318
319 /**
320 Returns the number of items in the branch. If @a recursively is @true,
321 returns the total number of descendants, otherwise only one level of
322 children is counted.
323 */
324 unsigned int GetChildrenCount(const wxTreeItemId& item,
325 bool recursively = true) const;
326
327 /**
328 Returns the number of items in the control.
329 */
330 unsigned int GetCount() const;
331
332 /**
333 Returns the edit control being currently used to edit a label. Returns
334 @NULL if no label is being edited.
335
336 @note This is currently only implemented for wxMSW.
337 */
338 wxTextCtrl* GetEditControl() const;
339
340 /**
341 Returns the first child; call GetNextChild() for the next child.
342
343 For this enumeration function you must pass in a 'cookie' parameter
344 which is opaque for the application but is necessary for the library to
345 make these functions reentrant (i.e. allow more than one enumeration on
346 one and the same object simultaneously). The cookie passed to
347 GetFirstChild() and GetNextChild() should be the same variable.
348
349 Returns an invalid tree item (i.e. wxTreeItemId::IsOk() returns @false)
350 if there are no further children.
351
352 @beginWxPythonOnly
353 In wxPython the returned wxTreeItemId and the new cookie value are both
354 returned as a tuple containing the two values.
355 @endWxPythonOnly
356
357 @see GetNextChild(), GetNextSibling()
358 */
359 wxTreeItemId GetFirstChild(const wxTreeItemId& item,
360 wxTreeItemIdValue& cookie) const;
361
362 /**
363 Returns the first visible item.
364 */
365 wxTreeItemId GetFirstVisibleItem() const;
366
367 /**
368 Returns the normal image list.
369 */
370 wxImageList* GetImageList() const;
371
372 /**
373 Returns the current tree control indentation.
374 */
375 int GetIndent() const;
376
377 /**
378 Returns the background colour of the item.
379 */
380 wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
381
382 /**
383 Returns the tree item data associated with the item.
384
385 @see wxTreeItemData
386
387 @beginWxPythonOnly
388 wxPython provides the following shortcut method:
389 @li GetPyData(item): Returns the Python Object associated with the
390 wxTreeItemData for the given item Id.
391 @endWxPythonOnly
392 */
393 wxTreeItemData* GetItemData(const wxTreeItemId& item) const;
394
395 /**
396 Returns the font of the item label.
397 */
398 wxFont GetItemFont(const wxTreeItemId& item) const;
399
400 /**
401 Gets the specified item image. The value of @a which may be:
402 - ::wxTreeItemIcon_Normal: to get the normal item image.
403 - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the
404 image which is shown when the item is currently selected).
405 - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes
406 sense for items which have children - then this image is shown when
407 the item is expanded and the normal image is shown when it is
408 collapsed).
409 - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image
410 (which is shown when an expanded item is currently selected).
411 */
412 int GetItemImage(const wxTreeItemId& item,
413 wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
414
415 /**
416 Returns the item's parent.
417 */
418 wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
419
420 /**
421 Gets the selected item image (this function is obsolete, use @ref
422 GetItemImage() "GetItemImage"( @a item, ::wxTreeItemIcon_Selected)
423 instead).
424 */
425 int GetItemSelectedImage(const wxTreeItemId& item) const;
426
427 /**
428 Returns the item label.
429 */
430 wxString GetItemText(const wxTreeItemId& item) const;
431
432 /**
433 Returns the colour of the item label.
434 */
435 wxColour GetItemTextColour(const wxTreeItemId& item) const;
436
437 /**
438 Returns the last child of the item (or an invalid tree item if this item
439 has no children).
440
441 @see GetFirstChild(), GetNextSibling(), GetLastChild()
442 */
443 wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
444
445 /**
446 Returns the next child; call GetFirstChild() for the first child. For
447 this enumeration function you must pass in a 'cookie' parameter which is
448 opaque for the application but is necessary for the library to make
449 these functions reentrant (i.e. allow more than one enumeration on one
450 and the same object simultaneously). The cookie passed to
451 GetFirstChild() and GetNextChild() should be the same.
452
453 Returns an invalid tree item if there are no further children.
454
455 @beginWxPythonOnly
456 In wxPython the returned wxTreeItemId and the new cookie value are both
457 returned as a tuple containing the two values.
458 @endWxPythonOnly
459
460 @see GetFirstChild()
461 */
462 wxTreeItemId GetNextChild(const wxTreeItemId& item,
463 wxTreeItemIdValue& cookie) const;
464
465 /**
466 Returns the next sibling of the specified item; call GetPrevSibling()
467 for the previous sibling.
468
469 Returns an invalid tree item if there are no further siblings.
470
471 @see GetPrevSibling()
472 */
473 wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
474
475 /**
476 Returns the next visible item or an invalid item if this item is the
477 last visible one.
478
479 @note The @a item itself must be visible.
480 */
481 wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
482
483 /**
484 Returns the previous sibling of the specified item; call
485 GetNextSibling() for the next sibling.
486
487 Returns an invalid tree item if there are no further children.
488
489 @see GetNextSibling()
490 */
491 wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
492
493 /**
494 Returns the previous visible item or an invalid item if this item is the
495 first visible one.
496
497 @note The @a item itself must be visible.
498 */
499 wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
500
501 /**
502 Returns @true if the control will use a quick calculation for the best
503 size, looking only at the first and last items. The default is @false.
504
505 @see SetQuickBestSize()
506 */
507 bool GetQuickBestSize() const;
508
509 /**
510 Returns the root item for the tree control.
511 */
512 wxTreeItemId GetRootItem() const;
513
514 /**
515 Returns the selection, or an invalid item if there is no selection. This
516 function only works with the controls without @c wxTR_MULTIPLE style,
517 use GetSelections() for the controls which do have this style.
518 */
519 wxTreeItemId GetSelection() const;
520
521 /**
522 Fills the array of tree items passed in with the currently selected
523 items. This function can be called only if the control has the @c
524 wxTR_MULTIPLE style.
525
526 Returns the number of selected items.
527
528 @beginWxPythonOnly
529 The wxPython version of this method accepts no parameters and returns a
530 Python list of @ref wxTreeItemId "wxTreeItemId"s.
531 @endWxPythonOnly
532 */
533 unsigned int GetSelections(wxArrayTreeItemIds& selection) const;
534
535 /**
536 Returns the state image list (from which application-defined state
537 images are taken).
538 */
539 wxImageList* GetStateImageList() const;
540
541 /**
542 Calculates which (if any) item is under the given @a point, returning
543 the tree item id at this point plus extra information @a flags. @a flags
544 is a bitlist of the following:
545
546 - @c wxTREE_HITTEST_ABOVE: Above the client area.
547 - @c wxTREE_HITTEST_BELOW: Below the client area.
548 - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item.
549 - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item.
550 - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item.
551 - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an
552 item.
553 - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with
554 an item.
555 - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item.
556 - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view
557 item that is in a user-defined state.
558 - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
559 - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
560
561 @beginWxPythonOnly
562 In wxPython both the wxTreeItemId and the flags are returned as a tuple.
563 @endWxPythonOnly
564 */
565 wxTreeItemId HitTest(const wxPoint& point, int& flags) const;
566
567
568 /**
569 Inserts an item after a given one (@a previous).
570
571 The @a image and @a selImage parameters are an index within the normal
572 image list specifying the image to use for unselected and selected
573 items, respectively. If @a image -1 and @a selImage is -1, the same
574 image is used for both selected and unselected items.
575 */
576 wxTreeItemId InsertItem(const wxTreeItemId& parent,
577 const wxTreeItemId& previous,
578 const wxString& text,
579 int image = -1,
580 int selImage = -1,
581 wxTreeItemData* data = NULL);
582
583 /**
584 Inserts an item before one identified
585 by its position (@a before). @a before must be less than the number of
586 children.
587
588 The @a image and @a selImage parameters are an index within the normal
589 image list specifying the image to use for unselected and selected
590 items, respectively. If @a image -1 and @a selImage is -1, the same
591 image is used for both selected and unselected items.
592
593 @beginWxPythonOnly
594 In wxPython, this form of this method is called @c InsertItemBefore().
595 @endWxPythonOnly
596 */
597 wxTreeItemId InsertItem(const wxTreeItemId& parent,
598 size_t before,
599 const wxString& text,
600 int image = -1,
601 int selImage = -1,
602 wxTreeItemData* data = NULL);
603
604 /**
605 Returns @true if the given item is in bold state.
606
607 @see SetItemBold()
608 */
609 bool IsBold(const wxTreeItemId& item) const;
610
611 /**
612 Returns @true if the control is empty (i.e. has no items, even no root
613 one).
614 */
615 bool IsEmpty() const;
616
617 /**
618 Returns @true if the item is expanded (only makes sense if it has
619 children).
620 */
621 bool IsExpanded(const wxTreeItemId& item) const;
622
623 /**
624 Returns @true if the item is selected.
625 */
626 bool IsSelected(const wxTreeItemId& item) const;
627
628 /**
629 Returns @true if the item is visible on the screen.
630 */
631 bool IsVisible(const wxTreeItemId& item) const;
632
633 /**
634 Returns @true if the item has children.
635 */
636 bool ItemHasChildren(const wxTreeItemId& item) const;
637
638 /**
639 Override this function in the derived class to change the sort order of
640 the items in the tree control. The function should return a negative,
641 zero or positive value if the first item is less than, equal to or
642 greater than the second one.
643
644 Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS()
645 and IMPLEMENT_DYNAMIC_CLASS() if you override this function because
646 otherwise the base class considers that it is not overridden and uses
647 the default comparison, i.e. sorts the items alphabetically, which
648 allows it optimize away the calls to the virtual function completely.
649
650 @see SortChildren()
651 */
652 int OnCompareItems(const wxTreeItemId& item1,
653 const wxTreeItemId& item2);
654
655 /**
656 Appends an item as the first child of @a parent, return a new item id.
657
658 The @a image and @a selImage parameters are an index within the normal
659 image list specifying the image to use for unselected and selected
660 items, respectively. If @a image -1 and @a selImage is -1, the same
661 image is used for both selected and unselected items.
662 */
663 wxTreeItemId PrependItem(const wxTreeItemId& parent,
664 const wxString& text,
665 int image = -1,
666 int selImage = -1,
667 wxTreeItemData* data = NULL);
668
669 /**
670 Scrolls the specified item into view.
671 */
672 void ScrollTo(const wxTreeItemId& item);
673
674 /**
675 Selects the given item. In multiple selection controls, can be also used
676 to deselect a currently selected item if the value of @a select is
677 @false.
678 */
679 void SelectItem(const wxTreeItemId& item, bool select = true);
680
681 /**
682 Sets the buttons image list (from which application-defined button
683 images are taken).
684
685 The button images assigned with this method will @b not be deleted by
686 @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself.
687 Setting or assigning the button image list enables the display of image
688 buttons. Once enabled, the only way to disable the display of button
689 images is to set the button image list to @NULL.
690
691 @note This function is only available in the generic version.
692
693 @see AssignButtonsImageList().
694 */
695 void SetButtonsImageList(wxImageList* imageList);
696
697 /**
698 Sets the normal image list. The image list assigned with this method
699 will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you
700 must delete it yourself.
701
702 @see AssignImageList().
703 */
704 void SetImageList(wxImageList* imageList);
705
706 /**
707 Sets the indentation for the tree control.
708 */
709 void SetIndent(int indent);
710
711 /**
712 Sets the colour of the item's background.
713 */
714 void SetItemBackgroundColour(const wxTreeItemId& item,
715 const wxColour& col);
716
717 /**
718 Makes item appear in bold font if @a bold parameter is @true or resets
719 it to the normal state.
720
721 @see IsBold()
722 */
723 void SetItemBold(const wxTreeItemId& item, bool bold = true);
724
725 /**
726 Sets the item client data.
727
728 @beginWxPythonOnly
729 - @b SetPyData( @a item, @c obj): Associate the given Python Object with
730 the wxTreeItemData for the given item Id.
731 @endWxPythonOnly
732
733 */
734 void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
735
736
737 /**
738 Gives the item the visual feedback for Drag'n'Drop actions, which is
739 useful if something is dragged from the outside onto the tree control
740 (as opposed to a DnD operation within the tree control, which already
741 is implemented internally).
742 */
743 void SetItemDropHighlight(const wxTreeItemId& item,
744 bool highlight = true);
745
746 /**
747 Sets the item's font. All items in the tree should have the same height
748 to avoid text clipping, so the fonts height should be the same for all
749 of them, although font attributes may vary.
750
751 @see SetItemBold()
752 */
753 void SetItemFont(const wxTreeItemId& item, const wxFont& font);
754
755 /**
756 Force appearance of the button next to the item. This is useful to
757 allow the user to expand the items which don't have any children now,
758 but instead adding them only when needed, thus minimizing memory
759 usage and loading time.
760 */
761 void SetItemHasChildren(const wxTreeItemId& item,
762 bool hasChildren = true);
763
764 /**
765 Sets the specified item's image. See GetItemImage() for the description
766 of the @a which parameter.
767 */
768 void SetItemImage(const wxTreeItemId& item, int image,
769 wxTreeItemIcon which = wxTreeItemIcon_Normal);
770
771 /**
772 Sets the selected item image (this function is obsolete, use @ref
773 SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected )
774 instead).
775 */
776 void SetItemSelectedImage(const wxTreeItemId& item, int selImage);
777
778 /**
779 Sets the item label.
780 */
781 void SetItemText(const wxTreeItemId& item, const wxString& text);
782
783 /**
784 Sets the colour of the item's text.
785 */
786 void SetItemTextColour(const wxTreeItemId& item,
787 const wxColour& col);
788
789 /**
790 If @true is passed, specifies that the control will use a quick
791 calculation for the best size, looking only at the first and last items.
792 Otherwise, it will look at all items. The default is @false.
793
794 @see GetQuickBestSize()
795 */
796 void SetQuickBestSize(bool quickBestSize);
797
798 /**
799 Sets the state image list (from which application-defined state images
800 are taken). Image list assigned with this method will @b not be deleted
801 by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it
802 yourself.
803
804 @see AssignStateImageList().
805 */
806 void SetStateImageList(wxImageList* imageList);
807
808 /**
809 Sets the mode flags associated with the display of the tree control. The
810 new mode takes effect immediately.
811
812 @note Generic only; MSW ignores changes.
813 */
814 void SetWindowStyle(long styles);
815
816 /**
817 Sorts the children of the given item using OnCompareItems().
818 You should override that method to change the sort order (the default is
819 ascending case-sensitive alphabetical order).
820
821 @see wxTreeItemData, OnCompareItems()
822 */
823 void SortChildren(const wxTreeItemId& item);
824
825 /**
826 Toggles the given item between collapsed and expanded states.
827 */
828 void Toggle(const wxTreeItemId& item);
829
830 /**
831 Toggles the given item between selected and unselected states. For
832 multiselection controls only.
833 */
834 void ToggleItemSelection(const wxTreeItemId& item);
835
836 /**
837 Removes the selection from the currently selected item (if any).
838 */
839 void Unselect();
840
841 /**
842 This function either behaves the same as Unselect() if the control
843 doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
844 items if it does have this style.
845 */
846 void UnselectAll();
847
848 /**
849 Unselects the given item. This works in multiselection controls only.
850 */
851 void UnselectItem(const wxTreeItemId& item);
852 };
853
854
855
856 /**
857 @class wxTreeEvent
858 @wxheader{treectrl.h}
859
860 A tree event holds information about events associated with wxTreeCtrl
861 objects.
862
863 To process input from a tree control, use these event handler macros to
864 direct input to member functions that take a wxTreeEvent argument.
865
866 @beginEventTable{wxTreeEvent}
867 @event{EVT_TREE_BEGIN_DRAG(id, func)}
868 Begin dragging with the left mouse button.
869 @event{EVT_TREE_BEGIN_RDRAG(id, func)}
870 Begin dragging with the right mouse button.
871 @event{EVT_TREE_END_DRAG(id, func)}
872 End dragging with the left or right mouse button.
873 @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
874 Begin editing a label. This can be prevented by calling Veto().
875 @event{EVT_TREE_END_LABEL_EDIT(id, func)}
876 Finish editing a label. This can be prevented by calling Veto().
877 @event{EVT_TREE_DELETE_ITEM(id, func)}
878 Delete an item.
879 @event{EVT_TREE_GET_INFO(id, func)}
880 Request information from the application.
881 @event{EVT_TREE_SET_INFO(id, func)}
882 Information is being supplied.
883 @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
884 The item has been activated, i.e. chosen by double clicking it with
885 mouse or from keyboard.
886 @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
887 The item has been collapsed.
888 @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
889 The item is being collapsed. This can be prevented by calling Veto().
890 @event{EVT_TREE_ITEM_EXPANDED(id, func)}
891 The item has been expanded.
892 @event{EVT_TREE_ITEM_EXPANDING(id, func)}
893 The item is being expanded. This can be prevented by calling Veto().
894 @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
895 The user has clicked the item with the right mouse button.
896 @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
897 The user has clicked the item with the middle mouse button.
898 @event{EVT_TREE_SEL_CHANGED(id, func)}
899 Selection has changed.
900 @event{EVT_TREE_SEL_CHANGING(id, func)}
901 Selection is changing. This can be prevented by calling Veto().
902 @event{EVT_TREE_KEY_DOWN(id, func)}
903 A key has been pressed.
904 @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
905 The opportunity to set the item tooltip is being given to the
906 application (call SetToolTip()). Windows only.
907 @event{EVT_TREE_ITEM_MENU(id, func)}
908 The context menu for the selected item has been requested, either by a
909 right click or by using the menu key.
910 @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
911 The state image has been clicked. Windows only.
912 @endEventTable
913
914 @library{wxbase}
915 @category{events}
916
917 @see wxTreeCtrl
918 */
919 class wxTreeEvent : public wxNotifyEvent
920 {
921 public:
922 /**
923 Constructor, used by wxWidgets itself only.
924 */
925 wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree);
926
927 /**
928 Returns the item (valid for all events).
929 */
930 wxTreeItemId GetItem() const;
931
932 /**
933 Returns the key code if the event is a key event. Use GetKeyEvent() to
934 get the values of the modifier keys for this event (i.e. Shift or Ctrl).
935 */
936 int GetKeyCode() const;
937
938 /**
939 Returns the key event for EVT_TREE_KEY_DOWN() events.
940 */
941 const wxKeyEvent GetKeyEvent() const;
942
943 /**
944 Returns the label if the event is a begin or end edit label event.
945 */
946 const wxString GetLabel() const;
947
948 /**
949 Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and
950 EVT_TREE_ITEM_CHANGED() events).
951 */
952 wxTreeItemId GetOldItem() const;
953
954 /**
955 Returns the position of the mouse pointer if the event is a drag or
956 menu-context event.
957
958 In both cases the position is in client coordinates - i.e. relative to
959 the wxTreeCtrl window (so that you can pass it directly to e.g.
960 wxWindow::PopupMenu()).
961 */
962 wxPoint GetPoint() const;
963
964 /**
965 Returns @true if the label edit was cancelled. This should be called
966 from within an EVT_TREE_END_LABEL_EDIT() handler.
967 */
968 bool IsEditCancelled() const;
969
970 /**
971 Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP()
972 events). Windows only.
973 */
974 void SetToolTip(const wxString& tooltip);
975 };
976