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