don't call wxYield() from EnsureVisible(), this is too dangerous - and unnecessary...
[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}
fb96bc75
VZ
53\twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSED(id, func)}}{The item has been collapsed.}
54\twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSING(id, func)}}{The item is being collapsed. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
55\twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{The item has been expanded.}
56\twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{The item 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
f3539882
VZ
247\perlnote{In wxPerl this method only takes the parameters {\tt item} and
248 {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
249
4fabb575 250\membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
a660d684 251
4fabb575 252\constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = TRUE}}
a660d684 253
4fabb575
JS
254Returns the number of items in the branch. If {\it recursively} is TRUE, returns the total number
255of descendants, otherwise only one level of children is counted.
a660d684
KB
256
257\membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
258
259\constfunc{int}{GetCount}{\void}
260
261Returns the number of items in the control.
262
263\membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
264
265\constfunc{wxTextCtrl\&}{GetEditControl}{\void}
266
267Returns the edit control used to edit a label.
268
4fabb575
JS
269\membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
270
271\constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}}
272
273Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
274
275For this enumeration function you must pass in a `cookie' parameter
276which is opaque for the application but is necessary for the library
277to make these functions reentrant (i.e. allow more than one
278enumeration on one and the same object simultaneously). The cookie passed to
279GetFirstChild and GetNextChild should be the same.
280
ed93168b 281Returns an invalid tree item if there are no further children.
4fabb575
JS
282
283\wxheading{See also}
284
285\helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild}
286
f899db6d
RD
287\pythonnote{In wxPython the returned wxTreeItemId and the new cookie
288value are both returned as a tuple containing the two values.}
289
f3539882
VZ
290\perlnote{In wxPerl this method only takes the {\tt item} parameter, and
291 returns a 2-element list ( item, cookie ).}
292
a660d684
KB
293\membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
294
4fabb575 295\constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
a660d684
KB
296
297Returns the first visible item.
298
299\membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
300
e2b34251 301\constfunc{wxImageList*}{GetImageList}{\void}
a660d684 302
e2b34251 303Returns the normal image list.
a660d684
KB
304
305\membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
306
307\constfunc{int}{GetIndent}{\void}
308
309Returns the current tree control indentation.
310
4fabb575 311\membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
a660d684 312
4fabb575 313\constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
a660d684 314
4fabb575 315Returns the tree item data associated with the item.
a660d684 316
4fabb575 317\wxheading{See also}
a660d684 318
4fabb575 319\helpref{wxTreeItemData}{wxtreeitemdata}
a660d684 320
ecf527c0
JS
321\pythonnote{wxPython provides the following shortcut method:
322
323\indented{2cm}{\begin{twocollist}\itemsep=0pt
c9110876 324\twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
f899db6d
RD
325associated with the wxTreeItemData for the given item Id.}
326\end{twocollist}}
327}
328
f3539882
VZ
329\perlnote{wxPerl provides the following shortcut method:
330\indented{2cm}{
331\begin{twocollist}\itemsep=0pt
332\twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
333associated with the Wx::TreeItemData ( it is just the same as
334tree->GetItemData( item )->GetData(); ).}
335\end{twocollist}}
336}
337
4fabb575 338\membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
a660d684 339
74b31181 340\constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
ecf527c0 341 \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
74b31181
VZ
342
343Gets the specified item image. The value of {\it which} may be:
ecf527c0 344
74b31181
VZ
345\begin{itemize}\itemsep=0pt
346\item{wxTreeItemIcon\_Normal} to get the normal item image
347\item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
348which is shown when the item is currently selected)
349\item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
350makes sense for items which have children - then this image is shown when the
351item is expanded and the normal image is shown when it is collapsed)
352\item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
353(which is shown when an expanded item is currently selected)
354\end{itemize}
a660d684 355
4fabb575 356\membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
a660d684 357
4fabb575 358\constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
a660d684 359
4fabb575 360Returns the item label.
a660d684 361
978f38c2
VZ
362\membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
363
364\constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
365
ed93168b 366Returns the last child of the item (or an invalid tree item if this item has no children).
978f38c2
VZ
367
368\wxheading{See also}
369
f6bcfd97 370\helpref{GetFirstChild}{wxtreectrlgetfirstchild},
978f38c2
VZ
371\helpref{GetLastChild}{wxtreectrlgetlastchild}
372
4fabb575 373\membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
a660d684 374
4fabb575 375\constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}}
a660d684 376
4fabb575 377Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
a660d684 378
4fabb575
JS
379For this enumeration function you must pass in a `cookie' parameter
380which is opaque for the application but is necessary for the library
381to make these functions reentrant (i.e. allow more than one
382enumeration on one and the same object simultaneously). The cookie passed to
383GetFirstChild and GetNextChild should be the same.
a660d684 384
ed93168b 385Returns an invalid tree item if there are no further children.
a660d684 386
4fabb575 387\wxheading{See also}
a660d684 388
4fabb575 389\helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
a660d684 390
f899db6d
RD
391\pythonnote{In wxPython the returned wxTreeItemId and the new cookie
392value are both returned as a tuple containing the two values.}
393
f3539882
VZ
394\perlnote{In wxPerl this method returns a 2-element list
395 ( item, cookie ), instead of modifying its parameters.}
396
4fabb575 397\membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
a660d684 398
4fabb575 399\constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
a660d684 400
4fabb575 401Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
a660d684 402
ed93168b 403Returns an invalid tree item if there are no further siblings.
a660d684 404
4fabb575
JS
405\wxheading{See also}
406
407\helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
408
409\membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
410
411\constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
a660d684
KB
412
413Returns the next visible item.
414
415\membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent}
416
4fabb575 417\constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}
a660d684
KB
418
419Returns the item's parent.
420
c9110876 421\pythonnote{This method is named {\tt GetItemParent} to avoid a name
874a1686
RD
422clash with wxWindow::GetParent.}
423
4fabb575
JS
424\membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
425
426\constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
427
428Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
429
ed93168b 430Returns an invalid tree item if there are no further children.
4fabb575
JS
431
432\wxheading{See also}
433
434\helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
435
436\membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
437
438\constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
439
440Returns the previous visible item.
441
a660d684
KB
442\membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
443
4fabb575 444\constfunc{wxTreeItemId}{GetRootItem}{\void}
a660d684
KB
445
446Returns the root item for the tree control.
447
ed93168b 448\membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
4fabb575 449
ed93168b 450\constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
4fabb575 451
f6bcfd97 452Gets the selected item image (this function is obsolete, use
b2cf617c 453{\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
4fabb575 454
a660d684
KB
455\membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
456
4fabb575 457\constfunc{wxTreeItemId}{GetSelection}{\void}
a660d684 458
ed93168b 459Returns the selection, or an invalid item if there is no selection.
f6bcfd97 460This function only works with the controls without wxTR\_MULTIPLE style, use
9dfbf520
VZ
461\helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
462this style.
463
464\membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
465
466\constfunc{size\_t}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
467
468Fills the array of tree items passed in with the currently selected items. This
469function can be called only if the control has the wxTR\_MULTIPLE style.
470
471Returns the number of selected items.
a660d684 472
76e1c2de 473\pythonnote{The wxPython version of this method accepts no parameters
ecf527c0 474and returns a Python list of {\tt wxTreeItemId}s.}
76e1c2de 475
f3539882
VZ
476\perlnote{In wxPerl this method takes no parameters and returns a list of
477 {\tt Wx::TreeItemId}s.}
478
e2b34251
JS
479\membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
480
481\constfunc{wxImageList*}{GetStateImageList}{\void}
482
483Returns the state image list (from which application-defined state images are taken).
484
a660d684
KB
485\membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
486
aa9fb2be 487\func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
a660d684 488
f6bcfd97
BP
489Calculates which (if any) item is under the given point, returning the tree item
490id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
a660d684
KB
491
492\twocolwidtha{5cm}
493\begin{twocollist}\itemsep=0pt
494\twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
495\twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
496\twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
497\twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
498\twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
499\twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
500\twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
501\twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
502\twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
503\twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
504\twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
505\end{twocollist}
506
aa9fb2be
RD
507\pythonnote{in wxPython both the wxTreeItemId and the flags are
508returned as a tuple.}
509
f3539882
VZ
510\perlnote{In wxPerl this method only takes the {\tt point} parameter
511 and returns a 2-element list ( item, flags ).}
512
a660d684
KB
513\membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
514
4fabb575
JS
515\func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
516 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
a660d684 517
f2593d0d
RR
518\func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
519 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
520
521Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
a660d684
KB
522
523If {\it image} > -1 and {\it selImage} is -1, the same image is used for
524both selected and unselected items.
525
f6bcfd97
BP
526\pythonnote{The second form of this method is called
527\tt{InsertItemBefore} in wxPython.}
528
ed93168b
VZ
529\membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
530
531\constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
532
533Returns TRUE if the given item is in bold state.
534
535See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
536
4fabb575
JS
537\membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
538
539\constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
540
541Returns TRUE if the item is expanded (only makes sense if it has children).
542
543\membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
544
545\constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
546
547Returns TRUE if the item is selected.
548
549\membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
550
551\constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
552
553Returns TRUE if the item is visible (it might be outside the view, or not expanded).
554
a660d684
KB
555\membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
556
4fabb575 557\constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
a660d684
KB
558
559Returns TRUE if the item has children.
560
ed93168b
VZ
561\membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
562
563\func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
564
565Override this function in the derived class to change the sort order of the
566items in the tree control. The function should return a negative, zero or
567positive value if the first item is less than, equal to or greater than the
568second one.
569
570The base class version compares items alphabetically.
571
572See also: \helpref{SortChildren}{wxtreectrlsortchildren}
573
4fabb575
JS
574\membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
575
576\func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
577 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
578
579Appends an item as the first child of {\it parent}, return a new item id.
580
581If {\it image} > -1 and {\it selImage} is -1, the same image is used for
582both selected and unselected items.
583
a660d684
KB
584\membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
585
4fabb575 586\func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
a660d684 587
4fabb575 588Scrolls the specified item into view.
a660d684
KB
589
590\membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
591
4fabb575 592\func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}}
a660d684
KB
593
594Selects the given item.
595
596\membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
597
598\func{void}{SetIndent}{\param{int }{indent}}
599
600Sets the indentation for the tree control.
601
602\membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
603
e2b34251 604\func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
a660d684 605
46cd520d
VS
606Sets the normal image list. Image list assigned with this method will
607{\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
608
609See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
610
a660d684 611
9ec64fa7
VZ
612\membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
613
614\func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
615
616Sets the colour of the items background.
617
ed93168b
VZ
618\membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
619
620\func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = TRUE}}
621
622Makes item appear in bold font if {\it bold} parameter is TRUE or resets it to
623the normal state.
624
625See also: \helpref{IsBold}{wxtreectrlisbold}
626
4fabb575 627\membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
a660d684 628
4fabb575 629\func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
a660d684 630
4fabb575 631Sets the item client data.
a660d684 632
f899db6d 633\pythonnote{wxPython provides the following shortcut method:\par
ecf527c0 634\indented{2cm}{\begin{twocollist}\itemsep=0pt
c9110876 635\twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
f899db6d
RD
636Object with the wxTreeItemData for the given item Id.}
637\end{twocollist}}
638}
639
f3539882
VZ
640\perlnote{wxPerl provides the following shortcut method:
641\indented{2cm}{
642\begin{twocollist}\itemsep=0pt
643\twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
644associated with the Wx::TreeItemData ( it is just the same as
645tree->GetItemData( item )->SetData( data ); ).}
646\end{twocollist}}
647}
648
9ec64fa7
VZ
649\membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
650
651\func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
652
653Sets the items font. All items in the tree should have the same height to avoid
654text clipping, so the fonts height should be the same for all of them,
655although font attributes may vary.
656
657\wxheading{See also}
658
659\helpref{SetItemBold}{wxtreectrlsetitembold}
660
4fabb575 661\membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
a660d684 662
4fabb575 663\func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = TRUE}}
a660d684 664
4fabb575
JS
665Force appearance of the button next to the item. This is useful to
666allow the user to expand the items which don't have any children now,
667but instead adding them only when needed, thus minimizing memory
668usage and loading time.
a660d684
KB
669
670\membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
671
74b31181 672\func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
ecf527c0 673 \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
a660d684 674
f6bcfd97 675Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
b2cf617c 676for the description of the {\it which} parameter.
a660d684 677
4fabb575 678\membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
a660d684 679
4fabb575 680\func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
a660d684 681
b2cf617c 682Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
a660d684
KB
683
684\membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
685
4fabb575 686\func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
a660d684
KB
687
688Sets the item label.
689
9ec64fa7
VZ
690\membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
691
692\func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
693
694Sets the colour of the items text.
695
e2b34251
JS
696\membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
697
698\func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
699
700Sets the state image list (from which application-defined state images are taken).
46cd520d
VS
701Image list assigned with this method will
702{\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
703
704See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
e2b34251 705
4fabb575 706\membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
a660d684 707
ed93168b 708\func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
a660d684 709
f6bcfd97 710Sorts the children of the given item using
ed93168b 711\helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
b2cf617c 712should override that method to change the sort order (the default is ascending
ed93168b 713alphabetical order).
4fabb575
JS
714
715\wxheading{See also}
716
ed93168b 717\helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
4fabb575
JS
718
719\membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
720
721\func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
722
723Toggles the given item between collapsed and expanded states.
724
725\membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
726
727\func{void}{Unselect}{\void}
728
729Removes the selection from the currently selected item (if any).
730
9dfbf520
VZ
731\membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
732
733\func{void}{UnselectAll}{\void}
734
f6bcfd97 735This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
9dfbf520
VZ
736if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
737all items if it does have this style.
738
4fabb575
JS
739\section{\class{wxTreeItemData}}\label{wxtreeitemdata}
740
741wxTreeItemData is some (arbitrary) user class associated with some item. The
742main advantage of having this class (compared to the old untyped interface) is
743that wxTreeItemData's are destroyed automatically by the tree and, as this
744class has virtual dtor, it means that the memory will be automatically
745freed. We don't just use wxObject instead of wxTreeItemData because
746the size of this class is critical: in any real application, each tree leaf
747will have wxTreeItemData associated with it and number of leaves may be
748quite big.
749
750Because the objects of this class are deleted by the tree, they should
751always be allocated on the heap.
752
753\wxheading{Derived from}
754
755wxTreeItemId
756
954b8ae6
JS
757\wxheading{Include files}
758
759<wx/treectrl.h>
760
4fabb575
JS
761\wxheading{See also}
762
763\helpref{wxTreeCtrl}{wxtreectrl}
764
765\latexignore{\rtfignore{\wxheading{Members}}}
766
767\membersection{wxTreeItemData::wxTreeItemData}\label{wxtreeitemdataconstr}
768
769\func{}{wxTreeItemData}{\void}
770
771Default constructor.
772
f899db6d
RD
773\pythonnote{The wxPython version of this constructor optionally
774accepts any Python object as a parameter. This object is then
775associated with the tree item using the wxTreeItemData as a
776container.
777
778In addition, the following methods are added in wxPython for accessing
ecf527c0
JS
779the object:
780
781\indented{2cm}{\begin{twocollist}\itemsep=0pt
c9110876
VS
782\twocolitem{{\bf GetData()}}{Returns a reference to the Python Object}
783\twocolitem{{\bf SetData(obj)}}{Associates a new Python Object with the
f899db6d
RD
784wxTreeItemData}
785\end{twocollist}}
786}
787
f3539882
VZ
788\perlnote{In wxPerl the constructor accepts as parameter an optional scalar,
789 and stores it as client data. You may retrieve this data by calling
790 {\bf GetData()}, and set it by callling {\bf SetData( data ).}
791}
f899db6d 792
4fabb575
JS
793\membersection{wxTreeItemData::\destruct{wxTreeItemData}}
794
795\func{void}{\destruct{wxTreeItemData}}{\void}
796
797Virtual destructor.
798
799\membersection{wxTreeItemData::GetId}\label{wxtreeitemdatagetid}
800
801\func{const wxTreeItem\&}{GetId}{\void}
802
803Returns the item associated with this node.
804
805\membersection{wxTreeItemData::SetId}\label{wxtreeitemdatasetid}
a660d684 806
4fabb575 807\func{void}{SetId}{\param{const wxTreeItemId\&}{ id}}
a660d684 808
4fabb575 809Sets the item associated with this node.
a660d684 810