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