]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/treectrl.h
Add wxRichMessageDialog class.
[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$
526954c5 6// Licence: wxWindows licence
23324ae1
FM
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 309 virtual wxTextCtrl *EditLabel(const wxTreeItemId& item,
b19b28c8 310 wxClassInfo* textCtrlClass = wxCLASSINFO(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
5708ae18
VZ
440
441 /**
442 Clears the currently focused item
443
444 @since 2.9.1
445 */
446 virtual void ClearFocusedItem();
447
448 /**
449 Sets the currently focused item.
450
451 @param item
452 The item to make the current one. It must be valid.
453 @since 2.9.1
454 */
455 virtual void SetFocusedItem(const wxTreeItemId& item);
456
457
23324ae1
FM
458 /**
459 Returns the normal image list.
460 */
328f5751 461 wxImageList* GetImageList() const;
23324ae1
FM
462
463 /**
464 Returns the current tree control indentation.
465 */
cfbe5614 466 virtual unsigned int GetIndent() const;
23324ae1
FM
467
468 /**
469 Returns the background colour of the item.
470 */
adaaa686 471 virtual wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
23324ae1 472
23324ae1 473 /**
7977b62a 474 Returns the tree item data associated with the item.
23324ae1 475
483724a1 476 @see wxTreeItemData
23324ae1 477
483724a1
FM
478 @beginWxPythonOnly
479 wxPython provides the following shortcut method:
480 @li GetPyData(item): Returns the Python Object associated with the
481 wxTreeItemData for the given item Id.
482 @endWxPythonOnly
1058f652
MB
483
484 @beginWxPerlOnly
485 wxPerl provides the following shortcut method:
486 - GetPlData(item): returns the Perl data
487 associated with the Wx::TreeItemData. It is just the same as
488 tree->GetItemData(item)->GetData().
489 @endWxPerlOnly
483724a1 490 */
adaaa686 491 virtual wxTreeItemData* GetItemData(const wxTreeItemId& item) const;
7977b62a
BP
492
493 /**
494 Returns the font of the item label.
495 */
adaaa686 496 virtual wxFont GetItemFont(const wxTreeItemId& item) const;
23324ae1
FM
497
498 /**
4cc4bfaf 499 Gets the specified item image. The value of @a which may be:
7977b62a
BP
500 - ::wxTreeItemIcon_Normal: to get the normal item image.
501 - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the
502 image which is shown when the item is currently selected).
503 - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes
504 sense for items which have children - then this image is shown when
505 the item is expanded and the normal image is shown when it is
506 collapsed).
507 - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image
508 (which is shown when an expanded item is currently selected).
23324ae1 509 */
fadc2df6
FM
510 virtual int GetItemImage(const wxTreeItemId& item,
511 wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
23324ae1
FM
512
513 /**
514 Returns the item's parent.
515 */
adaaa686 516 virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
23324ae1 517
03966fcb
RR
518 /**
519 Gets the specified item state.
520 */
521 int GetItemState(const wxTreeItemId& item) const;
522
23324ae1
FM
523 /**
524 Returns the item label.
525 */
adaaa686 526 virtual wxString GetItemText(const wxTreeItemId& item) const;
23324ae1
FM
527
528 /**
529 Returns the colour of the item label.
530 */
adaaa686 531 virtual wxColour GetItemTextColour(const wxTreeItemId& item) const;
23324ae1
FM
532
533 /**
7977b62a
BP
534 Returns the last child of the item (or an invalid tree item if this item
535 has no children).
3c4f71cc 536
7977b62a 537 @see GetFirstChild(), GetNextSibling(), GetLastChild()
23324ae1 538 */
adaaa686 539 virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
23324ae1
FM
540
541 /**
7977b62a
BP
542 Returns the next child; call GetFirstChild() for the first child. For
543 this enumeration function you must pass in a 'cookie' parameter which is
544 opaque for the application but is necessary for the library to make
545 these functions reentrant (i.e. allow more than one enumeration on one
546 and the same object simultaneously). The cookie passed to
547 GetFirstChild() and GetNextChild() should be the same.
548
23324ae1 549 Returns an invalid tree item if there are no further children.
3c4f71cc 550
7977b62a
BP
551 @beginWxPythonOnly
552 In wxPython the returned wxTreeItemId and the new cookie value are both
553 returned as a tuple containing the two values.
554 @endWxPythonOnly
555
1058f652
MB
556 @beginWxPerlOnly
557 In wxPerl this method returns a 2-element list
558 (item, cookie) instead of modifying its parameters.
559 @endWxPerlOnly
560
4cc4bfaf 561 @see GetFirstChild()
23324ae1 562 */
fadc2df6
FM
563 virtual wxTreeItemId GetNextChild(const wxTreeItemId& item,
564 wxTreeItemIdValue& cookie) const;
23324ae1
FM
565
566 /**
7977b62a
BP
567 Returns the next sibling of the specified item; call GetPrevSibling()
568 for the previous sibling.
569
23324ae1 570 Returns an invalid tree item if there are no further siblings.
3c4f71cc 571
4cc4bfaf 572 @see GetPrevSibling()
23324ae1 573 */
adaaa686 574 virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
23324ae1
FM
575
576 /**
7977b62a
BP
577 Returns the next visible item or an invalid item if this item is the
578 last visible one.
579
580 @note The @a item itself must be visible.
23324ae1 581 */
adaaa686 582 virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
23324ae1
FM
583
584 /**
7977b62a
BP
585 Returns the previous sibling of the specified item; call
586 GetNextSibling() for the next sibling.
587
23324ae1 588 Returns an invalid tree item if there are no further children.
3c4f71cc 589
4cc4bfaf 590 @see GetNextSibling()
23324ae1 591 */
adaaa686 592 virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
23324ae1
FM
593
594 /**
7977b62a
BP
595 Returns the previous visible item or an invalid item if this item is the
596 first visible one.
597
598 @note The @a item itself must be visible.
23324ae1 599 */
adaaa686 600 virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
23324ae1
FM
601
602 /**
7977b62a
BP
603 Returns @true if the control will use a quick calculation for the best
604 size, looking only at the first and last items. The default is @false.
3c4f71cc 605
4cc4bfaf 606 @see SetQuickBestSize()
23324ae1 607 */
328f5751 608 bool GetQuickBestSize() const;
23324ae1
FM
609
610 /**
611 Returns the root item for the tree control.
612 */
adaaa686 613 virtual wxTreeItemId GetRootItem() const;
23324ae1
FM
614
615 /**
7977b62a
BP
616 Returns the selection, or an invalid item if there is no selection. This
617 function only works with the controls without @c wxTR_MULTIPLE style,
febebac1
VZ
618 use GetSelections() for the controls which do have this style
619 or, if a single item is wanted, use GetFocusedItem().
23324ae1 620 */
adaaa686 621 virtual wxTreeItemId GetSelection() const;
23324ae1
FM
622
623 /**
7977b62a
BP
624 Fills the array of tree items passed in with the currently selected
625 items. This function can be called only if the control has the @c
626 wxTR_MULTIPLE style.
627
23324ae1 628 Returns the number of selected items.
03966fcb 629
7977b62a
BP
630 @beginWxPythonOnly
631 The wxPython version of this method accepts no parameters and returns a
632 Python list of @ref wxTreeItemId "wxTreeItemId"s.
633 @endWxPythonOnly
1058f652
MB
634
635 @beginWxPerlOnly
636 In wxPerl this method takes no parameters and returns a list of
637 @c Wx::TreeItemId.
638 @endWxPerlOnly
23324ae1 639 */
cfbe5614 640 virtual size_t GetSelections(wxArrayTreeItemIds& selection) const;
23324ae1
FM
641
642 /**
7977b62a
BP
643 Returns the state image list (from which application-defined state
644 images are taken).
23324ae1 645 */
328f5751 646 wxImageList* GetStateImageList() const;
23324ae1
FM
647
648 /**
7977b62a
BP
649 Calculates which (if any) item is under the given @a point, returning
650 the tree item id at this point plus extra information @a flags. @a flags
651 is a bitlist of the following:
652
653 - @c wxTREE_HITTEST_ABOVE: Above the client area.
654 - @c wxTREE_HITTEST_BELOW: Below the client area.
655 - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item.
656 - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item.
657 - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item.
6873eb5b
FM
658 - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an item.
659 - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
7977b62a
BP
660 - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item.
661 - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view
6873eb5b 662 item that is in a user-defined state.
7977b62a
BP
663 - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
664 - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
03966fcb 665
7977b62a
BP
666 @beginWxPythonOnly
667 In wxPython both the wxTreeItemId and the flags are returned as a tuple.
668 @endWxPythonOnly
1058f652
MB
669
670 @beginWxPerlOnly
671 In wxPerl this method only takes the @a point parameter
672 and returns a 2-element list (item, flags).
673 @endWxPerlOnly
23324ae1 674 */
328f5751 675 wxTreeItemId HitTest(const wxPoint& point, int& flags) const;
23324ae1 676
7977b62a 677
23324ae1 678 /**
7977b62a
BP
679 Inserts an item after a given one (@a previous).
680
681 The @a image and @a selImage parameters are an index within the normal
682 image list specifying the image to use for unselected and selected
683 items, respectively. If @a image -1 and @a selImage is -1, the same
684 image is used for both selected and unselected items.
23324ae1
FM
685 */
686 wxTreeItemId InsertItem(const wxTreeItemId& parent,
687 const wxTreeItemId& previous,
688 const wxString& text,
689 int image = -1,
690 int selImage = -1,
4cc4bfaf 691 wxTreeItemData* data = NULL);
7977b62a
BP
692
693 /**
694 Inserts an item before one identified
695 by its position (@a before). @a before must be less than the number of
696 children.
697
698 The @a image and @a selImage parameters are an index within the normal
699 image list specifying the image to use for unselected and selected
700 items, respectively. If @a image -1 and @a selImage is -1, the same
701 image is used for both selected and unselected items.
702
703 @beginWxPythonOnly
704 In wxPython, this form of this method is called @c InsertItemBefore().
705 @endWxPythonOnly
706 */
7c913512
FM
707 wxTreeItemId InsertItem(const wxTreeItemId& parent,
708 size_t before,
709 const wxString& text,
710 int image = -1,
711 int selImage = -1,
4cc4bfaf 712 wxTreeItemData* data = NULL);
23324ae1
FM
713
714 /**
715 Returns @true if the given item is in bold state.
7977b62a
BP
716
717 @see SetItemBold()
23324ae1 718 */
adaaa686 719 virtual bool IsBold(const wxTreeItemId& item) const;
23324ae1
FM
720
721 /**
7977b62a
BP
722 Returns @true if the control is empty (i.e. has no items, even no root
723 one).
23324ae1 724 */
328f5751 725 bool IsEmpty() const;
23324ae1
FM
726
727 /**
7977b62a
BP
728 Returns @true if the item is expanded (only makes sense if it has
729 children).
23324ae1 730 */
adaaa686 731 virtual bool IsExpanded(const wxTreeItemId& item) const;
23324ae1
FM
732
733 /**
734 Returns @true if the item is selected.
735 */
adaaa686 736 virtual bool IsSelected(const wxTreeItemId& item) const;
23324ae1
FM
737
738 /**
739 Returns @true if the item is visible on the screen.
740 */
adaaa686 741 virtual bool IsVisible(const wxTreeItemId& item) const;
23324ae1
FM
742
743 /**
744 Returns @true if the item has children.
745 */
adaaa686 746 virtual bool ItemHasChildren(const wxTreeItemId& item) const;
23324ae1
FM
747
748 /**
7977b62a
BP
749 Override this function in the derived class to change the sort order of
750 the items in the tree control. The function should return a negative,
751 zero or positive value if the first item is less than, equal to or
752 greater than the second one.
753
b19b28c8
FM
754 Please note that you @b must use wxRTTI macros wxDECLARE_DYNAMIC_CLASS()
755 and wxIMPLEMENT_DYNAMIC_CLASS() if you override this function because
7977b62a
BP
756 otherwise the base class considers that it is not overridden and uses
757 the default comparison, i.e. sorts the items alphabetically, which
23324ae1 758 allows it optimize away the calls to the virtual function completely.
7977b62a
BP
759
760 @see SortChildren()
23324ae1 761 */
fadc2df6
FM
762 virtual int OnCompareItems(const wxTreeItemId& item1,
763 const wxTreeItemId& item2);
23324ae1
FM
764
765 /**
7977b62a
BP
766 Appends an item as the first child of @a parent, return a new item id.
767
768 The @a image and @a selImage parameters are an index within the normal
769 image list specifying the image to use for unselected and selected
770 items, respectively. If @a image -1 and @a selImage is -1, the same
771 image is used for both selected and unselected items.
23324ae1
FM
772 */
773 wxTreeItemId PrependItem(const wxTreeItemId& parent,
774 const wxString& text,
775 int image = -1,
776 int selImage = -1,
4cc4bfaf 777 wxTreeItemData* data = NULL);
23324ae1
FM
778
779 /**
780 Scrolls the specified item into view.
781 */
adaaa686 782 virtual void ScrollTo(const wxTreeItemId& item);
23324ae1
FM
783
784 /**
7977b62a
BP
785 Selects the given item. In multiple selection controls, can be also used
786 to deselect a currently selected item if the value of @a select is
787 @false.
23324ae1 788 */
adaaa686 789 virtual void SelectItem(const wxTreeItemId& item, bool select = true);
23324ae1
FM
790
791 /**
7977b62a
BP
792 Sets the buttons image list (from which application-defined button
793 images are taken).
794
795 The button images assigned with this method will @b not be deleted by
796 @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself.
797 Setting or assigning the button image list enables the display of image
798 buttons. Once enabled, the only way to disable the display of button
799 images is to set the button image list to @NULL.
800
801 @note This function is only available in the generic version.
802
803 @see AssignButtonsImageList().
23324ae1
FM
804 */
805 void SetButtonsImageList(wxImageList* imageList);
806
807 /**
7977b62a
BP
808 Sets the normal image list. The image list assigned with this method
809 will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you
810 must delete it yourself.
811
812 @see AssignImageList().
23324ae1 813 */
adaaa686 814 virtual void SetImageList(wxImageList* imageList);
23324ae1
FM
815
816 /**
817 Sets the indentation for the tree control.
818 */
cfbe5614 819 virtual void SetIndent(unsigned int indent);
23324ae1
FM
820
821 /**
822 Sets the colour of the item's background.
823 */
fadc2df6
FM
824 virtual void SetItemBackgroundColour(const wxTreeItemId& item,
825 const wxColour& col);
23324ae1
FM
826
827 /**
7977b62a
BP
828 Makes item appear in bold font if @a bold parameter is @true or resets
829 it to the normal state.
830
831 @see IsBold()
23324ae1 832 */
adaaa686 833 virtual void SetItemBold(const wxTreeItemId& item, bool bold = true);
23324ae1 834
7977b62a
BP
835 /**
836 Sets the item client data.
837
727539d8
VZ
838 Notice that the client data previously associated with the @a item (if
839 any) is @em not freed by this function and so calling this function
840 multiple times for the same item will result in memory leaks unless you
841 delete the old item data pointer yourself.
842
7977b62a
BP
843 @beginWxPythonOnly
844 - @b SetPyData( @a item, @c obj): Associate the given Python Object with
845 the wxTreeItemData for the given item Id.
846 @endWxPythonOnly
847
1058f652
MB
848 @beginWxPerlOnly
849 wxPerl provides the following shortcut method:
850 - SetPlData(item, data): sets the Perl data
851 associated with the @c Wx::TreeItemData. It is just the same as
852 tree->GetItemData(item)->SetData(data).
853 @endWxPerlOnly
7977b62a 854 */
adaaa686 855 virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
7977b62a
BP
856
857
23324ae1
FM
858 /**
859 Gives the item the visual feedback for Drag'n'Drop actions, which is
860 useful if something is dragged from the outside onto the tree control
861 (as opposed to a DnD operation within the tree control, which already
862 is implemented internally).
863 */
fadc2df6
FM
864 virtual void SetItemDropHighlight(const wxTreeItemId& item,
865 bool highlight = true);
23324ae1
FM
866
867 /**
7977b62a
BP
868 Sets the item's font. All items in the tree should have the same height
869 to avoid text clipping, so the fonts height should be the same for all
870 of them, although font attributes may vary.
3c4f71cc 871
4cc4bfaf 872 @see SetItemBold()
23324ae1 873 */
adaaa686 874 virtual void SetItemFont(const wxTreeItemId& item, const wxFont& font);
23324ae1
FM
875
876 /**
877 Force appearance of the button next to the item. This is useful to
878 allow the user to expand the items which don't have any children now,
879 but instead adding them only when needed, thus minimizing memory
880 usage and loading time.
881 */
fadc2df6
FM
882 virtual void SetItemHasChildren(const wxTreeItemId& item,
883 bool hasChildren = true);
23324ae1
FM
884
885 /**
7977b62a
BP
886 Sets the specified item's image. See GetItemImage() for the description
887 of the @a which parameter.
23324ae1 888 */
fadc2df6
FM
889 virtual void SetItemImage(const wxTreeItemId& item, int image,
890 wxTreeItemIcon which = wxTreeItemIcon_Normal);
23324ae1 891
03966fcb
RR
892 /**
893 Sets the specified item state. The value of @a state may be:
809ca837
RR
894 - @c wxTREE_ITEMSTATE_NONE: to disable the item state (the state image will
895 be not displayed).
896 - @c wxTREE_ITEMSTATE_NEXT: to set the next item state.
897 - @c wxTREE_ITEMSTATE_PREV: to set the previous item state.
03966fcb
RR
898 */
899 void SetItemState(const wxTreeItemId& item, int state);
900
23324ae1
FM
901 /**
902 Sets the item label.
903 */
adaaa686 904 virtual void SetItemText(const wxTreeItemId& item, const wxString& text);
23324ae1
FM
905
906 /**
907 Sets the colour of the item's text.
908 */
fadc2df6
FM
909 virtual void SetItemTextColour(const wxTreeItemId& item,
910 const wxColour& col);
23324ae1
FM
911
912 /**
7977b62a
BP
913 If @true is passed, specifies that the control will use a quick
914 calculation for the best size, looking only at the first and last items.
915 Otherwise, it will look at all items. The default is @false.
3c4f71cc 916
4cc4bfaf 917 @see GetQuickBestSize()
23324ae1
FM
918 */
919 void SetQuickBestSize(bool quickBestSize);
920
921 /**
7977b62a
BP
922 Sets the state image list (from which application-defined state images
923 are taken). Image list assigned with this method will @b not be deleted
924 by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it
925 yourself.
926
927 @see AssignStateImageList().
23324ae1 928 */
adaaa686 929 virtual void SetStateImageList(wxImageList* imageList);
23324ae1
FM
930
931 /**
7977b62a
BP
932 Sets the mode flags associated with the display of the tree control. The
933 new mode takes effect immediately.
934
935 @note Generic only; MSW ignores changes.
23324ae1
FM
936 */
937 void SetWindowStyle(long styles);
938
939 /**
7977b62a
BP
940 Sorts the children of the given item using OnCompareItems().
941 You should override that method to change the sort order (the default is
942 ascending case-sensitive alphabetical order).
3c4f71cc 943
4cc4bfaf 944 @see wxTreeItemData, OnCompareItems()
23324ae1 945 */
adaaa686 946 virtual void SortChildren(const wxTreeItemId& item);
23324ae1
FM
947
948 /**
949 Toggles the given item between collapsed and expanded states.
950 */
adaaa686 951 virtual void Toggle(const wxTreeItemId& item);
23324ae1
FM
952
953 /**
954 Toggles the given item between selected and unselected states. For
955 multiselection controls only.
956 */
957 void ToggleItemSelection(const wxTreeItemId& item);
958
959 /**
960 Removes the selection from the currently selected item (if any).
961 */
adaaa686 962 virtual void Unselect();
23324ae1
FM
963
964 /**
7977b62a
BP
965 This function either behaves the same as Unselect() if the control
966 doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
967 items if it does have this style.
23324ae1 968 */
adaaa686 969 virtual void UnselectAll();
23324ae1
FM
970
971 /**
972 Unselects the given item. This works in multiselection controls only.
973 */
974 void UnselectItem(const wxTreeItemId& item);
5cb3a695
VZ
975
976 /**
977 Select all the immediate children of the given parent.
978
979 This function can be used with multiselection controls only.
980
981 @since 2.9.1
982 */
983 virtual void SelectChildren(const wxTreeItemId& parent);
23324ae1
FM
984};
985
986
e54c96f1 987
23324ae1
FM
988/**
989 @class wxTreeEvent
7c913512 990
7977b62a
BP
991 A tree event holds information about events associated with wxTreeCtrl
992 objects.
993
994 To process input from a tree control, use these event handler macros to
995 direct input to member functions that take a wxTreeEvent argument.
996
997 @beginEventTable{wxTreeEvent}
998 @event{EVT_TREE_BEGIN_DRAG(id, func)}
a1e92028
VZ
999 Begin dragging with the left mouse button. If you want to enable
1000 left-dragging you need to intercept this event and explicitely call
1001 wxTreeEvent::Allow(), as it's vetoed by default. Also notice that the
1002 control must have an associated image list (see SetImageList()) to
1003 drag its items under MSW.
7977b62a 1004 @event{EVT_TREE_BEGIN_RDRAG(id, func)}
a1e92028
VZ
1005 Begin dragging with the right mouse button. If you want to enable
1006 right-dragging you need to intercept this event and explicitely call
1007 wxTreeEvent::Allow(), as it's vetoed by default.
7977b62a
BP
1008 @event{EVT_TREE_END_DRAG(id, func)}
1009 End dragging with the left or right mouse button.
1010 @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
1011 Begin editing a label. This can be prevented by calling Veto().
1012 @event{EVT_TREE_END_LABEL_EDIT(id, func)}
1013 Finish editing a label. This can be prevented by calling Veto().
1014 @event{EVT_TREE_DELETE_ITEM(id, func)}
1015 Delete an item.
1016 @event{EVT_TREE_GET_INFO(id, func)}
1017 Request information from the application.
1018 @event{EVT_TREE_SET_INFO(id, func)}
1019 Information is being supplied.
1020 @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
1021 The item has been activated, i.e. chosen by double clicking it with
1022 mouse or from keyboard.
1023 @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
1024 The item has been collapsed.
1025 @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
1026 The item is being collapsed. This can be prevented by calling Veto().
1027 @event{EVT_TREE_ITEM_EXPANDED(id, func)}
1028 The item has been expanded.
1029 @event{EVT_TREE_ITEM_EXPANDING(id, func)}
1030 The item is being expanded. This can be prevented by calling Veto().
1031 @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
1032 The user has clicked the item with the right mouse button.
1033 @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
1034 The user has clicked the item with the middle mouse button.
1035 @event{EVT_TREE_SEL_CHANGED(id, func)}
1036 Selection has changed.
1037 @event{EVT_TREE_SEL_CHANGING(id, func)}
1038 Selection is changing. This can be prevented by calling Veto().
1039 @event{EVT_TREE_KEY_DOWN(id, func)}
1040 A key has been pressed.
1041 @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
1042 The opportunity to set the item tooltip is being given to the
1043 application (call SetToolTip()). Windows only.
1044 @event{EVT_TREE_ITEM_MENU(id, func)}
1045 The context menu for the selected item has been requested, either by a
1046 right click or by using the menu key.
1047 @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
809ca837 1048 The state image has been clicked.
7977b62a 1049 @endEventTable
7c913512 1050
23324ae1
FM
1051 @library{wxbase}
1052 @category{events}
7c913512 1053
e54c96f1 1054 @see wxTreeCtrl
23324ae1
FM
1055*/
1056class wxTreeEvent : public wxNotifyEvent
1057{
1058public:
1059 /**
23324ae1
FM
1060 Constructor, used by wxWidgets itself only.
1061 */
cfbe5614
FM
1062 wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree,
1063 const wxTreeItemId& item = wxTreeItemId());
23324ae1
FM
1064
1065 /**
1066 Returns the item (valid for all events).
1067 */
328f5751 1068 wxTreeItemId GetItem() const;
23324ae1
FM
1069
1070 /**
7977b62a
BP
1071 Returns the key code if the event is a key event. Use GetKeyEvent() to
1072 get the values of the modifier keys for this event (i.e. Shift or Ctrl).
23324ae1 1073 */
328f5751 1074 int GetKeyCode() const;
23324ae1
FM
1075
1076 /**
6873eb5b 1077 Returns the key event for @c EVT_TREE_KEY_DOWN events.
23324ae1 1078 */
cfbe5614 1079 const wxKeyEvent& GetKeyEvent() const;
23324ae1
FM
1080
1081 /**
1082 Returns the label if the event is a begin or end edit label event.
1083 */
cfbe5614 1084 const wxString& GetLabel() const;
23324ae1
FM
1085
1086 /**
6873eb5b
FM
1087 Returns the old item index (valid for @c EVT_TREE_ITEM_CHANGING and
1088 @c EVT_TREE_ITEM_CHANGED events).
23324ae1 1089 */
328f5751 1090 wxTreeItemId GetOldItem() const;
23324ae1
FM
1091
1092 /**
1093 Returns the position of the mouse pointer if the event is a drag or
1094 menu-context event.
7977b62a
BP
1095
1096 In both cases the position is in client coordinates - i.e. relative to
1097 the wxTreeCtrl window (so that you can pass it directly to e.g.
1098 wxWindow::PopupMenu()).
23324ae1 1099 */
328f5751 1100 wxPoint GetPoint() const;
23324ae1
FM
1101
1102 /**
7977b62a 1103 Returns @true if the label edit was cancelled. This should be called
6873eb5b 1104 from within an @c EVT_TREE_END_LABEL_EDIT handler.
23324ae1 1105 */
328f5751 1106 bool IsEditCancelled() const;
23324ae1
FM
1107
1108 /**
6873eb5b 1109 Set the tooltip for the item (valid for @c EVT_TREE_ITEM_GETTOOLTIP
7977b62a 1110 events). Windows only.
23324ae1
FM
1111 */
1112 void SetToolTip(const wxString& tooltip);
1113};