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