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