]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/treectrl.tex
Two more typos.
[wxWidgets.git] / docs / latex / wx / treectrl.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: treectrl.tex
3 %% Purpose: wxTreeCtrl documentation
4 %% Author: wxWidgets Team
5 %% Modified by:
6 %% Created:
7 %% RCS-ID: $Id$
8 %% Copyright: (c) wxWidgets Team
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxTreeCtrl}}\label{wxtreectrl}
13
14 A tree control presents information as a hierarchy, with items that may be expanded
15 to show further items. Items in a tree control are referenced by wxTreeItemId handles,
16 which may be tested for validity by calling wxTreeItemId::IsOk.
17
18 To intercept events from a tree control, use the event table macros described in \helpref{wxTreeEvent}{wxtreeevent}.
19
20 \wxheading{Derived from}
21
22 \helpref{wxControl}{wxcontrol}\\
23 \helpref{wxWindow}{wxwindow}\\
24 \helpref{wxEvtHandler}{wxevthandler}\\
25 \helpref{wxObject}{wxobject}
26
27 \wxheading{Include files}
28
29 <wx/treectrl.h>
30
31 \wxheading{Window styles}
32
33 \twocolwidtha{5cm}
34 \begin{twocollist}\itemsep=0pt
35 \twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style
36 if you wish the user to be able to edit labels in the tree control.}
37 \twocolitem{\windowstyle{wxTR\_NO\_BUTTONS}}{For convenience
38 to document that no buttons are to be drawn.}
39 \twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style
40 to show + and - buttons to the left of parent items.}
41 \twocolitem{\windowstyle{wxTR\_NO\_LINES}}{Use this style
42 to hide vertical level connectors.}
43 \twocolitem{\windowstyle{wxTR\_FULL\_ROW\_HIGHLIGHT}}{Use this style to have the background
44 colour and the selection highlight extend over the entire horizontal
45 row of the tree control window. (This flag is ignored under Windows unless you
46 specify wxTR\_NO\_LINES as well.) }
47 \twocolitem{\windowstyle{wxTR\_LINES\_AT\_ROOT}}{Use this style
48 to show lines between root nodes.
49 Only applicable if wxTR\_HIDE\_ROOT is set and wxTR\_NO\_LINES is not set.}
50 \twocolitem{\windowstyle{wxTR\_HIDE\_ROOT}}{Use this style
51 to suppress the display of the root node,
52 effectively causing the first-level nodes
53 to appear as a series of root nodes.}
54 \twocolitem{\windowstyle{wxTR\_ROW\_LINES}}{Use this style
55 to draw a contrasting border between displayed rows.}
56 \twocolitem{\windowstyle{wxTR\_HAS\_VARIABLE\_ROW\_HEIGHT}}{Use this style
57 to cause row heights to be just big enough to fit the content.
58 If not set, all rows use the largest row height.
59 The default is that this flag is unset.
60 Generic only.}
61 \twocolitem{\windowstyle{wxTR\_SINGLE}}{For convenience
62 to document that only one item may be selected at a time.
63 Selecting another item causes the current selection, if any,
64 to be deselected. This is the default.}
65 \twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style
66 to allow a range of items to be selected.
67 If a second range is selected, the current range, if any, is deselected.}
68 \twocolitem{\windowstyle{wxTR\_EXTENDED}}{Use this style
69 to allow disjoint items to be selected. (Only partially implemented; may not work in all cases.)}
70 \twocolitem{\windowstyle{wxTR\_DEFAULT\_STYLE}}{The set of flags that are
71 closest to the defaults for the native control for a particular toolkit.}
72 \end{twocollist}
73
74 See also \helpref{window styles overview}{windowstyles}.
75
76 \wxheading{Event handling}
77
78 To process input from a tree control, use these event handler macros to direct input to member
79 functions that take a \helpref{wxTreeEvent}{wxtreeevent} argument.
80
81 \twocolwidtha{7cm}
82 \begin{twocollist}\itemsep=0pt
83 \twocolitem{{\bf EVT\_TREE\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
84 \twocolitem{{\bf EVT\_TREE\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
85 \twocolitem{{\bf EVT\_TREE\_END\_DRAG(id, func)}}{End dragging with the left or right mouse button.}
86 \twocolitem{{\bf EVT\_TREE\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
87 \twocolitem{{\bf EVT\_TREE\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
88 \twocolitem{{\bf EVT\_TREE\_DELETE\_ITEM(id, func)}}{Delete an item.}
89 \twocolitem{{\bf EVT\_TREE\_GET\_INFO(id, func)}}{Request information from the application.}
90 \twocolitem{{\bf EVT\_TREE\_SET\_INFO(id, func)}}{Information is being supplied.}
91 \twocolitem{{\bf EVT\_TREE\_ITEM\_ACTIVATED(id, func)}}{The item has been activated, i.e. chosen by double clicking it with mouse or from keyboard}
92 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSED(id, func)}}{The item has been collapsed.}
93 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSING(id, func)}}{The item is being collapsed. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
94 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{The item has been expanded.}
95 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{The item is being expanded. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
96 \twocolitem{{\bf EVT\_TREE\_ITEM\_RIGHT\_CLICK(id, func)}}{The user has clicked the item with the right mouse button.}
97 \twocolitem{{\bf EVT\_TREE\_ITEM\_MIDDLE\_CLICK(id, func)}}{The user has clicked the item with the middle mouse button.}
98 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGED(id, func)}}{Selection has changed.}
99 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGING(id, func)}}{Selection is changing. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
100 \twocolitem{{\bf EVT\_TREE\_KEY\_DOWN(id, func)}}{A key has been pressed.}
101 \twocolitem{{\bf EVT\_TREE\_ITEM\_GETTOOLTIP(id, func)}}{The opportunity to set the item tooltip
102 is being given to the application (call wxTreeEvent::SetToolTip). Windows only.}
103 \twocolitem{{\bf EVT\_TREE\_ITEM\_MENU(id, func)}}{The context menu for the selected item has been requested, either by a right click or by using the menu key.}
104 \twocolitem{{\bf EVT\_TREE\_STATE\_IMAGE\_CLICK(id, func)}}{The state image has been clicked. Windows only.}
105 \end{twocollist}
106
107 \wxheading{See also}
108
109 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp
110 \helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent}
111
112 \wxheading{Win32 notes}
113
114 wxTreeCtrl class uses the standard common treeview control under Win32
115 implemented in the system library {\tt comctl32.dll}. Some versions of this
116 library are known to have bugs with handling the tree control colours: the
117 usual symptom is that the expanded items leave black (or otherwise incorrectly
118 coloured) background behind them, especially for the controls using non-default background colour. The recommended solution is to upgrade the {\tt comctl32.dll}
119 to a newer version: see
120 \urlref{http://www.microsoft.com/downloads/release.asp?ReleaseID=11916}{http://www.microsoft.com/downloads/release.asp?ReleaseID=11916}.
121
122 \latexignore{\rtfignore{\wxheading{Members}}}
123
124
125 \membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr}
126
127 \func{}{wxTreeCtrl}{\void}
128
129 Default constructor.
130
131 \func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
132 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
133 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
134
135 Constructor, creating and showing a tree control.
136
137 \wxheading{Parameters}
138
139 \docparam{parent}{Parent window. Must not be {\tt NULL}.}
140
141 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
142
143 \docparam{pos}{Window position.}
144
145 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
146 appropriately.}
147
148 \docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.}
149
150 \docparam{validator}{Window validator.}
151
152 \docparam{name}{Window name.}
153
154 \wxheading{See also}
155
156 \helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator}
157
158
159 \membersection{wxTreeCtrl::\destruct{wxTreeCtrl}}\label{wxtreectrldtor}
160
161 \func{void}{\destruct{wxTreeCtrl}}{\void}
162
163 Destructor, destroying the list control.
164
165
166 \membersection{wxTreeCtrl::AddRoot}\label{wxtreectrladdroot}
167
168 \func{wxTreeItemId}{AddRoot}{\param{const wxString\&}{ text},
169 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
170
171 Adds the root node to the tree, returning the new item.
172
173 The {\it image} and {\it selImage} parameters are an index within
174 the normal image list specifying the image to use for unselected and
175 selected items, respectively.
176 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
177 both selected and unselected items.
178
179
180 \membersection{wxTreeCtrl::AppendItem}\label{wxtreectrlappenditem}
181
182 \func{wxTreeItemId}{AppendItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
183 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
184
185 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
186
187 The {\it image} and {\it selImage} parameters are an index within
188 the normal image list specifying the image to use for unselected and
189 selected items, respectively.
190 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
191 both selected and unselected items.
192
193
194 \membersection{wxTreeCtrl::AssignButtonsImageList}\label{wxtreectrlassignbuttonsimagelist}
195
196 \func{void}{AssignButtonsImageList}{\param{wxImageList*}{ imageList}}
197
198 Sets the buttons image list. The button images assigned with this method will
199 be automatically deleted by wxTreeCtrl as appropriate
200 (i.e. it takes ownership of the list).
201
202 Setting or assigning the button image list enables the display of image buttons.
203 Once enabled, the only way to disable the display of button images is to set
204 the button image list to {\tt NULL}.
205
206 This function is only available in the generic version.
207
208 See also \helpref{SetButtonsImageList}{wxtreectrlsetbuttonsimagelist}.
209
210
211 \membersection{wxTreeCtrl::AssignImageList}\label{wxtreectrlassignimagelist}
212
213 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
214
215 Sets the normal image list. Image list assigned with this method will
216 be automatically deleted by wxTreeCtrl as appropriate
217 (i.e. it takes ownership of the list).
218
219 See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
220
221
222 \membersection{wxTreeCtrl::AssignStateImageList}\label{wxtreectrlassignstateimagelist}
223
224 \func{void}{AssignStateImageList}{\param{wxImageList*}{ imageList}}
225
226 Sets the state image list. Image list assigned with this method will
227 be automatically deleted by wxTreeCtrl as appropriate
228 (i.e. it takes ownership of the list).
229
230 See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
231
232
233
234 \membersection{wxTreeCtrl::Collapse}\label{wxtreectrlcollapse}
235
236 \func{void}{Collapse}{\param{const wxTreeItemId\&}{ item}}
237
238 Collapses the given item.
239
240
241 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
242
243 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}
244
245 Collapses the given item and removes all children.
246
247
248 \membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate}
249
250 \func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
251 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
252 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
253
254 Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details.
255
256
257 \membersection{wxTreeCtrl::Delete}\label{wxtreectrldelete}
258
259 \func{void}{Delete}{\param{const wxTreeItemId\&}{ item}}
260
261 Deletes the specified item. A {\tt EVT\_TREE\_DELETE\_ITEM} event will be
262 generated.
263
264 This function may cause a subsequent call to GetNextChild to fail.
265
266
267 \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems}
268
269 \func{void}{DeleteAllItems}{\void}
270
271 Deletes all items in the control. Note that this may not generate
272 {\tt EVT\_TREE\_DELETE\_ITEM} events under some Windows versions although
273 normally such event is generated for each removed item.
274
275
276 \membersection{wxTreeCtrl::DeleteChildren}\label{wxtreectrldeletechildren}
277
278 \func{void}{DeleteChildren}{\param{const wxTreeItemId\& }{item}}
279
280 Deletes all children of the given item (but not the item itself). Note that
281 this will {\bf not} generate any events unlike
282 \helpref{Delete}{wxtreectrldelete} method.
283
284 If you have called \helpref{wxTreeCtrl::SetItemHasChildren}{wxtreectrlsetitemhaschildren}, you
285 may need to call it again since {\it DeleteChildren} does not automatically
286 clear the setting.
287
288
289 \membersection{wxTreeCtrl::EditLabel}\label{wxtreectrleditlabel}
290
291 \func{void}{EditLabel}{\param{const wxTreeItemId\&}{ item}}
292
293 Starts editing the label of the given item. This function generates a
294 EVT\_TREE\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
295 text control will appear for in-place editing.
296
297 If the user changed the label (i.e. s/he does not press ESC or leave
298 the text control without changes, a EVT\_TREE\_END\_LABEL\_EDIT event
299 will be sent which can be vetoed as well.
300
301 \wxheading{See also}
302
303 \helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel},
304 \helpref{wxTreeEvent}{wxtreeevent}
305
306
307 \membersection{wxTreeCtrl::EndEditLabel}\label{wxtreectrlendeditlabel}
308
309 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
310
311 Ends label editing. If {\it cancelEdit} is {\tt true}, the edit will be cancelled.
312
313 This function is currently supported under Windows only.
314
315 \wxheading{See also}
316
317 \helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}
318
319
320 \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible}
321
322 \func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}}
323
324 Scrolls and/or expands items to ensure that the given item is visible.
325
326
327 \membersection{wxTreeCtrl::Expand}\label{wxtreectrlexpand}
328
329 \func{void}{Expand}{\param{const wxTreeItemId\&}{ item}}
330
331 Expands the given item.
332
333
334 \membersection{wxTreeCtrl::ExpandAll}\label{wxtreectrlexpandall}
335
336 \func{void}{Expand}{\void}
337
338 Expands all items in the tree.
339
340
341 \membersection{wxTreeCtrl::ExpandAllChildren}\label{wxtreectrlexpandallchildren}
342
343 \func{void}{ExpandAllChildren}{\param{const wxTreeItemId\&}{ item}}
344
345 Expands the given item and all its children recursively.
346
347
348 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
349
350 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = {\tt false}}}
351
352 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is {\tt true},
353 only the rectangle around the item's label will be returned, otherwise the
354 item's image is also taken into account.
355
356 The return value is {\tt true} if the rectangle was successfully retrieved or {\tt false}
357 if it was not (in this case {\it rect} is not changed) -- for example, if the
358 item is currently invisible.
359
360 Notice that the rectangle coordinates are logical, not physical ones. So, for
361 example, the x coordinate may be negative if the tree has a horizontal
362 scrollbar and its position is not $0$.
363
364 \pythonnote{The wxPython version of this method requires only the
365 {\tt item} and {\tt textOnly} parameters. The return value is either a
366 {\tt wxRect} object or {\tt None}.}
367
368 \perlnote{In wxPerl this method only takes the parameters {\tt item} and
369 {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
370
371
372 \membersection{wxTreeCtrl::GetButtonsImageList}\label{wxtreectrlgetbuttonsimagelist}
373
374 \constfunc{wxImageList*}{GetButtonsImageList}{\void}
375
376 Returns the buttons image list (from which application-defined button images are taken).
377
378 This function is only available in the generic version.
379
380
381 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
382
383 \constfunc{unsigned int}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = {\tt true}}}
384
385 Returns the number of items in the branch. If {\it recursively} is {\tt true}, returns the total number
386 of descendants, otherwise only one level of children is counted.
387
388
389 \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
390
391 \constfunc{unsigned int}{GetCount}{\void}
392
393 Returns the number of items in the control.
394
395
396 \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
397
398 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
399
400 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
401 if no label is being edited.
402
403 {\bf NB:} It is currently only implemented for wxMSW.
404
405
406 \membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
407
408 \constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
409
410 Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
411
412 For this enumeration function you must pass in a `cookie' parameter
413 which is opaque for the application but is necessary for the library
414 to make these functions reentrant (i.e. allow more than one
415 enumeration on one and the same object simultaneously). The cookie passed to
416 GetFirstChild and GetNextChild should be the same variable.
417
418 Returns an invalid tree item (i.e. IsOk() returns {\tt false}) if there are no further children.
419
420 \wxheading{See also}
421
422 \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild},
423 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
424
425 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
426 value are both returned as a tuple containing the two values.}
427
428 \perlnote{In wxPerl this method only takes the {\tt item} parameter, and
429 returns a 2-element list {\tt ( item, cookie )}.}
430
431
432 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
433
434 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
435
436 Returns the first visible item.
437
438
439 \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
440
441 \constfunc{wxImageList*}{GetImageList}{\void}
442
443 Returns the normal image list.
444
445
446 \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
447
448 \constfunc{int}{GetIndent}{\void}
449
450 Returns the current tree control indentation.
451
452
453 \membersection{wxTreeCtrl::GetItemBackgroundColour}\label{wxtreectrlgetitembackgroundcolour}
454
455 \constfunc{wxColour}{GetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}}
456
457 Returns the background colour of the item.
458
459
460 \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
461
462 \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
463
464 Returns the tree item data associated with the item.
465
466 \wxheading{See also}
467
468 \helpref{wxTreeItemData}{wxtreeitemdata}
469
470 \pythonnote{wxPython provides the following shortcut method:
471
472 \indented{2cm}{\begin{twocollist}\itemsep=0pt
473 \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
474 associated with the wxTreeItemData for the given item Id.}
475 \end{twocollist}}
476 }%
477
478 \perlnote{wxPerl provides the following shortcut method:
479 \indented{2cm}{
480 \begin{twocollist}\itemsep=0pt
481 \twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
482 associated with the Wx::TreeItemData. It is just the same as
483 tree->GetItemData(item)->GetData().}
484 \end{twocollist}}
485 }%
486
487 \membersection{wxTreeCtrl::GetItemFont}\label{wxtreectrlgetitemfont}
488
489 \constfunc{wxFont}{GetItemFont}{\param{const wxTreeItemId\&}{ item}}
490
491 Returns the font of the item label.
492
493
494 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
495
496 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
497 \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
498
499 Gets the specified item image. The value of {\it which} may be:
500
501 \begin{itemize}\itemsep=0pt
502 \item{wxTreeItemIcon\_Normal} to get the normal item image
503 \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
504 which is shown when the item is currently selected)
505 \item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
506 makes sense for items which have children - then this image is shown when the
507 item is expanded and the normal image is shown when it is collapsed)
508 \item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
509 (which is shown when an expanded item is currently selected)
510 \end{itemize}
511
512
513 \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
514
515 \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
516
517 Returns the item label.
518
519
520 \membersection{wxTreeCtrl::GetItemTextColour}\label{wxtreectrlgetitemtextcolour}
521
522 \constfunc{wxColour}{GetItemTextColour}{\param{const wxTreeItemId\&}{ item}}
523
524 Returns the colour of the item label.
525
526
527 \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
528
529 \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
530
531 Returns the last child of the item (or an invalid tree item if this item has no children).
532
533 \wxheading{See also}
534
535 \helpref{GetFirstChild}{wxtreectrlgetfirstchild},
536 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling},
537 \helpref{GetLastChild}{wxtreectrlgetlastchild}
538
539
540 \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
541
542 \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
543
544 Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
545
546 For this enumeration function you must pass in a `cookie' parameter
547 which is opaque for the application but is necessary for the library
548 to make these functions reentrant (i.e. allow more than one
549 enumeration on one and the same object simultaneously). The cookie passed to
550 GetFirstChild and GetNextChild should be the same.
551
552 Returns an invalid tree item if there are no further children.
553
554 \wxheading{See also}
555
556 \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
557
558 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
559 value are both returned as a tuple containing the two values.}
560
561 \perlnote{In wxPerl this method returns a 2-element list
562 {\tt ( item, cookie )}, instead of modifying its parameters.}
563
564
565 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
566
567 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
568
569 Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
570
571 Returns an invalid tree item if there are no further siblings.
572
573 \wxheading{See also}
574
575 \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
576
577
578 \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
579
580 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
581
582 Returns the next visible item.
583
584
585 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}
586
587 \constfunc{wxTreeItemId}{GetItemParent}{\param{const wxTreeItemId\&}{ item}}
588
589 Returns the item's parent.
590
591
592 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
593
594 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
595
596 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
597
598 Returns an invalid tree item if there are no further children.
599
600 \wxheading{See also}
601
602 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
603
604
605 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
606
607 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
608
609 Returns the previous visible item.
610
611
612 \membersection{wxTreeCtrl::GetQuickBestSize}\label{wxtreectrlgetquickbestsize}
613
614 \constfunc{bool}{GetQuickBestSize}{\void}
615
616 Returns true if the control will use a quick calculation for the best size,
617 looking only at the first and last items. The default is false.
618
619 \wxheading{See also}
620
621 \helpref{wxTreeCtrl::SetQuickBestSize}{wxtreectrlsetquickbestsize}
622
623
624 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
625
626 \constfunc{wxTreeItemId}{GetRootItem}{\void}
627
628 Returns the root item for the tree control.
629
630
631 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
632
633 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
634
635 Gets the selected item image (this function is obsolete, use
636 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
637
638
639 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
640
641 \constfunc{wxTreeItemId}{GetSelection}{\void}
642
643 Returns the selection, or an invalid item if there is no selection.
644 This function only works with the controls without wxTR\_MULTIPLE style, use
645 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
646 this style.
647
648
649 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
650
651 \constfunc{unsigned int}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
652
653 Fills the array of tree items passed in with the currently selected items. This
654 function can be called only if the control has the wxTR\_MULTIPLE style.
655
656 Returns the number of selected items.
657
658 \pythonnote{The wxPython version of this method accepts no parameters
659 and returns a Python list of {\tt wxTreeItemId}s.}
660
661 \perlnote{In wxPerl this method takes no parameters and returns a list of
662 {\tt Wx::TreeItemId}s.}
663
664
665 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
666
667 \constfunc{wxImageList*}{GetStateImageList}{\void}
668
669 Returns the state image list (from which application-defined state images are taken).
670
671
672 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
673
674 \constfunc{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
675
676 Calculates which (if any) item is under the given point, returning the tree item
677 id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
678
679 \twocolwidtha{5cm}
680 \begin{twocollist}\itemsep=0pt
681 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
682 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
683 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
684 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
685 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
686 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
687 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
688 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
689 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
690 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
691 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
692 \end{twocollist}
693
694 \pythonnote{in wxPython both the wxTreeItemId and the flags are
695 returned as a tuple.}
696
697 \perlnote{In wxPerl this method only takes the {\tt point} parameter
698 and returns a 2-element list {\tt ( item, flags )}.}
699
700
701 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
702
703 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
704 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
705
706 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
707 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
708
709 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
710 {\it before} must be less than the number of children.
711
712 The {\it image} and {\it selImage} parameters are an index within
713 the normal image list specifying the image to use for unselected and
714 selected items, respectively.
715 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
716 both selected and unselected items.
717
718 \pythonnote{The second form of this method is called
719 {\tt InsertItemBefore} in wxPython.}
720
721
722 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
723
724 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
725
726 Returns {\tt true} if the given item is in bold state.
727
728 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
729
730
731 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
732
733 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
734
735 Returns {\tt true} if the item is expanded (only makes sense if it has children).
736
737
738 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
739
740 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
741
742 Returns {\tt true} if the item is selected.
743
744
745 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
746
747 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
748
749 Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
750
751
752 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
753
754 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
755
756 Returns {\tt true} if the item has children.
757
758
759 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
760
761 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
762
763 Override this function in the derived class to change the sort order of the
764 items in the tree control. The function should return a negative, zero or
765 positive value if the first item is less than, equal to or greater than the
766 second one.
767
768 The base class version compares items alphabetically.
769
770 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
771
772
773 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
774
775 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
776 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
777
778 Appends an item as the first child of {\it parent}, return a new item id.
779
780 The {\it image} and {\it selImage} parameters are an index within
781 the normal image list specifying the image to use for unselected and
782 selected items, respectively.
783 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
784 both selected and unselected items.
785
786
787 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
788
789 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
790
791 Scrolls the specified item into view.
792
793
794 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
795
796 \func{void}{SelectItem}{\param{const wxTreeItemId\&}{ item}, \param{bool }{select = \true}}
797
798 Selects the given item. In multiple selection controls, can be also used to
799 deselect a currently selected item if the value of \arg{select} is false.
800
801
802 \membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
803
804 \func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
805
806 Sets the buttons image list (from which application-defined button images are taken).
807 The button images assigned with this method will
808 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
809
810 Setting or assigning the button image list enables the display of image buttons.
811 Once enabled, the only way to disable the display of button images is to set
812 the button image list to {\tt NULL}.
813
814 This function is only available in the generic version.
815
816 See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
817
818
819 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
820
821 \func{void}{SetIndent}{\param{int }{indent}}
822
823 Sets the indentation for the tree control.
824
825
826 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
827
828 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
829
830 Sets the normal image list. Image list assigned with this method will
831 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
832
833 See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
834
835
836
837 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
838
839 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
840
841 Sets the colour of the item's background.
842
843
844 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
845
846 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
847
848 Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
849 the normal state.
850
851 See also: \helpref{IsBold}{wxtreectrlisbold}
852
853
854 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
855
856 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
857
858 Sets the item client data.
859
860 \pythonnote{wxPython provides the following shortcut method:\par
861 \indented{2cm}{\begin{twocollist}\itemsep=0pt
862 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
863 Object with the wxTreeItemData for the given item Id.}
864 \end{twocollist}}
865 }%
866
867 \perlnote{wxPerl provides the following shortcut method:
868 \indented{2cm}{
869 \begin{twocollist}\itemsep=0pt
870 \twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
871 associated with the Wx::TreeItemData. It is just the same as
872 tree->GetItemData(item)->SetData(data).}
873 \end{twocollist}}
874 }%
875
876 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
877
878 \func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = {\tt true}}}
879
880 Gives the item the visual feedback for Drag'n'Drop actions, which is
881 useful if something is dragged from the outside onto the tree control
882 (as opposed to a DnD operation within the tree control, which already
883 is implemented internally).
884
885 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
886
887 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
888
889 Sets the item's font. All items in the tree should have the same height to avoid
890 text clipping, so the fonts height should be the same for all of them,
891 although font attributes may vary.
892
893 \wxheading{See also}
894
895 \helpref{SetItemBold}{wxtreectrlsetitembold}
896
897
898 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
899
900 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
901
902 Force appearance of the button next to the item. This is useful to
903 allow the user to expand the items which don't have any children now,
904 but instead adding them only when needed, thus minimizing memory
905 usage and loading time.
906
907
908 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
909
910 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
911 \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
912
913 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
914 for the description of the {\it which} parameter.
915
916
917 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
918
919 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
920
921 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
922
923
924 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
925
926 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
927
928 Sets the item label.
929
930
931 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
932
933 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
934
935 Sets the colour of the item's text.
936
937
938 \membersection{wxTreeCtrl::SetQuickBestSize}\label{wxtreectrlsetquickbestsize}
939
940 \func{void}{SetQuickBestSize}{\param{bool}{ quickBestSize}}
941
942 If true is passed, specifies that the control will use a quick calculation for the best size,
943 looking only at the first and last items. Otherwise, it will look at all items.
944 The default is false.
945
946 \wxheading{See also}
947
948 \helpref{wxTreeCtrl::GetQuickBestSize}{wxtreectrlgetquickbestsize}
949
950
951 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
952
953 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
954
955 Sets the state image list (from which application-defined state images are taken).
956 Image list assigned with this method will
957 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
958
959 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
960
961 \membersection{wxTreeCtrl::SetWindowStyle}\label{wxtreectrlsetwindowstyle}
962
963 \func{void}{SetWindowStyle}{\param{long}{styles}}
964
965 Sets the mode flags associated with the display of the tree control.
966 The new mode takes effect immediately.
967 (Generic only; MSW ignores changes.)
968
969
970 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
971
972 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
973
974 Sorts the children of the given item using
975 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
976 should override that method to change the sort order (the default is ascending
977 case-sensitive alphabetical order).
978
979 \wxheading{See also}
980
981 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
982
983
984 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
985
986 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
987
988 Toggles the given item between collapsed and expanded states.
989
990
991 \membersection{wxTreeCtrl::ToggleItemSelection}\label{wxtreectrltoggleitemselection}
992
993 \func{void}{ToggleItemSelection}{\param{const wxTreeItemId\&}{ item}}
994
995 Toggles the given item between selected and unselected states. For
996 multiselection controls only.
997
998
999 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
1000
1001 \func{void}{Unselect}{\void}
1002
1003 Removes the selection from the currently selected item (if any).
1004
1005
1006 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
1007
1008 \func{void}{UnselectAll}{\void}
1009
1010 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
1011 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
1012 all items if it does have this style.
1013
1014
1015 \membersection{wxTreeCtrl::UnselectItem}\label{wxtreectrlunselectitem}
1016
1017 \func{void}{UnselectItem}{\param{const wxTreeItemId\& }{item}}
1018
1019 Unselects the given item. This works in multiselection controls only.
1020