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