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