1 \section{\class{wxTreeCtrl
}}\label{wxtreectrl
}
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 which may be tested for validity by calling wxTreeItemId::IsOk.
7 To intercept events from a tree control, use the event table macros described in
\helpref{wxTreeEvent
}{wxtreeevent
}.
9 \wxheading{Derived from
}
11 \helpref{wxControl
}{wxcontrol
}\\
12 \helpref{wxWindow
}{wxwindow
}\\
13 \helpref{wxEvtHandler
}{wxevthandler
}\\
14 \helpref{wxObject
}{wxobject
}
16 \wxheading{Include files
}
20 \wxheading{Window styles
}
23 \begin{twocollist
}\itemsep=
0pt
24 \twocolitem{\windowstyle{wxTR
\_EDIT\_LABELS}}{Use this style
25 if you wish the user to be able to edit labels in the tree control.
}
26 \twocolitem{\windowstyle{wxTR
\_NO\_BUTTONS}}{For convenience
27 to
document that no buttons are to be drawn.
}
28 \twocolitem{\windowstyle{wxTR
\_HAS\_BUTTONS}}{Use this style
29 to show + and - buttons to the left of parent items.
}
30 \twocolitem{\windowstyle{wxTR
\_TWIST\_BUTTONS}}{Use this style
31 to show Mac-style twister buttons to the left of parent items.
32 If both wxTR
\_HAS\_BUTTONS and wxTR
\_TWIST\_BUTTONS are given,
33 twister buttons are generated. Generic only.
}
34 \twocolitem{\windowstyle{wxTR
\_NO\_LINES}}{Use this style
35 to hide vertical level connectors.
}
36 \twocolitem{\windowstyle{wxTR
\_FULL\_ROW\_HIGHLIGHT}}{Use this style to have the background
37 colour and the selection highlight extend over the entire horizontal
38 row of the tree control window. (This flag is ignored under Windows unless you
39 specify wxTR
\_NO\_LINES as well.)
}
40 \twocolitem{\windowstyle{wxTR
\_LINES\_AT\_ROOT}}{Use this style
41 to show lines between root nodes.
42 Only applicable if wxTR
\_HIDE\_ROOT is set and wxTR
\_NO\_LINES is not set.
}
43 \twocolitem{\windowstyle{wxTR
\_HIDE\_ROOT}}{Use this style
44 to suppress the display of the root node,
45 effectively causing the first-level nodes
46 to appear as a series of root nodes.
}
47 \twocolitem{\windowstyle{wxTR
\_ROW\_LINES}}{Use this style
48 to draw a contrasting border between displayed rows.
}
49 \twocolitem{\windowstyle{wxTR
\_HAS\_VARIABLE\_ROW\_HEIGHT}}{Use this style
50 to cause row heights to be just big enough to fit the content.
51 If not set, all rows use the largest row height.
52 The default is that this flag is unset.
54 \twocolitem{\windowstyle{wxTR
\_SINGLE}}{For convenience
55 to
document that only one item may be selected at a time.
56 Selecting another item causes the current selection, if any,
57 to be deselected. This is the default.
}
58 \twocolitem{\windowstyle{wxTR
\_MULTIPLE}}{Use this style
59 to allow a range of items to be selected.
60 If a second range is selected, the current range, if any, is deselected.
}
61 \twocolitem{\windowstyle{wxTR
\_EXTENDED}}{Use this style
62 to allow disjoint items to be selected. (Only partially implemented; may not work in all cases.)
}
63 \twocolitem{\windowstyle{wxTR
\_DEFAULT\_STYLE}}{The set of flags that are
64 closest to the defaults for the native control for a particular toolkit.
}
67 See also
\helpref{window styles overview
}{windowstyles
}.
69 \wxheading{Event handling
}
71 To process input from a tree control, use these event handler macros to direct input to member
72 functions that take a
\helpref{wxTreeEvent
}{wxtreeevent
} argument.
75 \begin{twocollist
}\itemsep=
0pt
76 \twocolitem{{\bf EVT
\_TREE\_BEGIN\_DRAG(id, func)
}}{Begin dragging with the left mouse button.
}
77 \twocolitem{{\bf EVT
\_TREE\_BEGIN\_RDRAG(id, func)
}}{Begin dragging with the right mouse button.
}
78 \twocolitem{{\bf EVT
\_TREE\_END\_DRAG(id, func)
}}{End dragging with the left or right mouse button.
}
79 \twocolitem{{\bf EVT
\_TREE\_BEGIN\_LABEL\_EDIT(id, func)
}}{Begin editing a label. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
80 \twocolitem{{\bf EVT
\_TREE\_END\_LABEL\_EDIT(id, func)
}}{Finish editing a label. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
81 \twocolitem{{\bf EVT
\_TREE\_DELETE\_ITEM(id, func)
}}{Delete an item.
}
82 \twocolitem{{\bf EVT
\_TREE\_GET\_INFO(id, func)
}}{Request information from the application.
}
83 \twocolitem{{\bf EVT
\_TREE\_SET\_INFO(id, func)
}}{Information is being supplied.
}
84 \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
}
85 \twocolitem{{\bf EVT
\_TREE\_ITEM\_COLLAPSED(id, func)
}}{The item has been collapsed.
}
86 \twocolitem{{\bf EVT
\_TREE\_ITEM\_COLLAPSING(id, func)
}}{The item is being collapsed. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
87 \twocolitem{{\bf EVT
\_TREE\_ITEM\_EXPANDED(id, func)
}}{The item has been expanded.
}
88 \twocolitem{{\bf EVT
\_TREE\_ITEM\_EXPANDING(id, func)
}}{The item is being expanded. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
89 \twocolitem{{\bf EVT
\_TREE\_ITEM\_RIGHT\_CLICK(id, func)
}}{The user has clicked the item with the right mouse button.
}
90 \twocolitem{{\bf EVT
\_TREE\_ITEM\_MIDDLE\_CLICK(id, func)
}}{The user has clicked the item with the middle mouse button.
}
91 \twocolitem{{\bf EVT
\_TREE\_SEL\_CHANGED(id, func)
}}{Selection has changed.
}
92 \twocolitem{{\bf EVT
\_TREE\_SEL\_CHANGING(id, func)
}}{Selection is changing. This can be prevented by calling
\helpref{Veto()
}{wxnotifyeventveto
}.
}
93 \twocolitem{{\bf EVT
\_TREE\_KEY\_DOWN(id, func)
}}{A key has been pressed.
}
94 \twocolitem{{\bf EVT
\_TREE\_ITEM\_GETTOOLTIP(id, func)
}}{The opportunity to set the item tooltip
95 is being given to the application (call wxTreeEvent::SetToolTip). Windows only.
}
100 \helpref{wxTreeItemData
}{wxtreeitemdata
},
\helpref{wxTreeCtrl overview
}{wxtreectrloverview
},
\helpref{wxListBox
}{wxlistbox
},
\helpref{wxListCtrl
}{wxlistctrl
},
\rtfsp
101 \helpref{wxImageList
}{wximagelist
},
\helpref{wxTreeEvent
}{wxtreeevent
}
103 \wxheading{Win32 notes
}
105 wxTreeCtrl class uses the standard common treeview control under Win32
106 implemented in the system library
{\tt comctl32.dll
}. Some versions of this
107 library are known to have bugs with handling the tree control colours: the
108 usual symptom is that the expanded items leave black (or otherwise incorrectly
109 coloured) background behind them, especially for the controls using non
110 default background colour. The recommended solution is to upgrade the
{\tt comctl32.dll
}
111 to a newer version: see
112 \urlref{http://www.microsoft.com/msdownload/ieplatform/ie/comctrlx86.asp
}{http://www.microsoft.com/msdownload/ieplatform/ie/comctrlx86.asp
}.
114 \latexignore{\rtfignore{\wxheading{Members
}}}
117 \membersection{wxTreeCtrl::wxTreeCtrl
}\label{wxtreectrlconstr
}
119 \func{}{wxTreeCtrl
}{\void}
123 \func{}{wxTreeCtrl
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
124 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
125 \param{long
}{ style = wxTR
\_HAS\_BUTTONS},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listCtrl"
}}
127 Constructor, creating and showing a tree control.
129 \wxheading{Parameters
}
131 \docparam{parent
}{Parent window. Must not be
{\tt NULL
}.
}
133 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
135 \docparam{pos
}{Window position.
}
137 \docparam{size
}{Window size. If the default size (-
1, -
1) is specified then the window is sized
140 \docparam{style
}{Window style. See
\helpref{wxTreeCtrl
}{wxtreectrl
}.
}
142 \docparam{validator
}{Window validator.
}
144 \docparam{name
}{Window name.
}
148 \helpref{wxTreeCtrl::Create
}{wxtreectrlcreate
},
\helpref{wxValidator
}{wxvalidator
}
151 \membersection{wxTreeCtrl::
\destruct{wxTreeCtrl
}}\label{wxtreectrldtor
}
153 \func{void
}{\destruct{wxTreeCtrl
}}{\void}
155 Destructor, destroying the list control.
158 \membersection{wxTreeCtrl::AddRoot
}\label{wxtreectrladdroot
}
160 \func{wxTreeItemId
}{AddRoot
}{\param{const wxString\&
}{ text
},
161 \param{int
}{ image = -
1},
\param{int
}{ selImage = -
1},
\param{wxTreeItemData*
}{ data =
{\tt NULL
}}}
163 Adds the root node to the tree, returning the new item.
165 The
{\it image
} and
{\it selImage
} parameters are an index within
166 the normal image list specifying the image to use for unselected and
167 selected items, respectively.
168 If
{\it image
} > -
1 and
{\it selImage
} is -
1, the same image is used for
169 both selected and unselected items.
172 \membersection{wxTreeCtrl::AppendItem
}\label{wxtreectrlappenditem
}
174 \func{wxTreeItemId
}{AppendItem
}{\param{const wxTreeItemId\&
}{parent
},
\param{const wxString\&
}{ text
},
175 \param{int
}{ image = -
1},
\param{int
}{ selImage = -
1},
\param{wxTreeItemData*
}{ data =
{\tt NULL
}}}
177 Appends an item to the end of the branch identified by
{\it parent
}, return a new item id.
179 The
{\it image
} and
{\it selImage
} parameters are an index within
180 the normal image list specifying the image to use for unselected and
181 selected items, respectively.
182 If
{\it image
} > -
1 and
{\it selImage
} is -
1, the same image is used for
183 both selected and unselected items.
186 \membersection{wxTreeCtrl::AssignButtonsImageList
}\label{wxtreectrlassignbuttonsimagelist
}
188 \func{void
}{AssignButtonsImageList
}{\param{wxImageList*
}{ imageList
}}
190 Sets the buttons image list. The button images assigned with this method will
191 be automatically deleted by wxTreeCtrl as appropriate
192 (i.e. it takes ownership of the list).
194 Setting or assigning the button image list enables the display of image buttons.
195 Once enabled, the only way to disable the display of button images is to set
196 the button image list to
{\tt NULL
}.
198 This function is only available in the generic version.
200 See also
\helpref{SetButtonsImageList
}{wxtreectrlsetbuttonsimagelist
}.
203 \membersection{wxTreeCtrl::AssignImageList
}\label{wxtreectrlassignimagelist
}
205 \func{void
}{AssignImageList
}{\param{wxImageList*
}{ imageList
}}
207 Sets the normal image list. Image list assigned with this method will
208 be automatically deleted by wxTreeCtrl as appropriate
209 (i.e. it takes ownership of the list).
211 See also
\helpref{SetImageList
}{wxtreectrlsetimagelist
}.
214 \membersection{wxTreeCtrl::AssignStateImageList
}\label{wxtreectrlassignstateimagelist
}
216 \func{void
}{AssignStateImageList
}{\param{wxImageList*
}{ imageList
}}
218 Sets the state image list. Image list assigned with this method will
219 be automatically deleted by wxTreeCtrl as appropriate
220 (i.e. it takes ownership of the list).
222 See also
\helpref{SetStateImageList
}{wxtreectrlsetstateimagelist
}.
226 \membersection{wxTreeCtrl::Collapse
}\label{wxtreectrlcollapse
}
228 \func{void
}{Collapse
}{\param{const wxTreeItemId\&
}{ item
}}
230 Collapses the given item.
233 \membersection{wxTreeCtrl::CollapseAndReset
}\label{wxtreectrlcollapseandreset
}
235 \func{void
}{CollapseAndReset
}{\param{const wxTreeItemId\&
}{ item
}}
237 Collapses the given item and removes all children.
240 \membersection{wxTreeCtrl::Create
}\label{wxtreectrlcreate
}
242 \func{bool
}{wxTreeCtrl
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
243 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
244 \param{long
}{ style = wxTR
\_HAS\_BUTTONS},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listCtrl"
}}
246 Creates the tree control. See
\helpref{wxTreeCtrl::wxTreeCtrl
}{wxtreectrlconstr
} for further details.
249 \membersection{wxTreeCtrl::Delete
}\label{wxtreectrldelete
}
251 \func{void
}{Delete
}{\param{const wxTreeItemId\&
}{ item
}}
253 Deletes the specified item. A
{\tt EVT
\_TREE\_DELETE\_ITEM} event will be
256 This function may cause a subsequent call to GetNextChild to fail.
259 \membersection{wxTreeCtrl::DeleteAllItems
}\label{wxtreectrldeleteallitems
}
261 \func{void
}{DeleteAllItems
}{\void}
263 Deletes all the items in the control. Note that this may not generate
264 {\tt EVT
\_TREE\_DELETE\_ITEM} events under some Windows versions although
265 normally such event is generated for each removed item.
268 \membersection{wxTreeCtrl::DeleteChildren
}\label{wxtreectrldeletechildren
}
270 \func{void
}{DeleteChildren
}{\param{const wxTreeItemId\&
}{item
}}
272 Deletes all children of the given item (but not the item itself). Note that
273 this will
{\bf not
} generate any events unlike
274 \helpref{Delete
}{wxtreectrldelete
} method.
276 If you have called
\helpref{wxTreeCtrl::SetItemHasChildren
}{wxtreectrlsetitemhaschildren
}, you
277 may need to call it again since
{\it DeleteChildren
} does not automatically
281 \membersection{wxTreeCtrl::EditLabel
}\label{wxtreectrleditlabel
}
283 \func{void
}{EditLabel
}{\param{const wxTreeItemId\&
}{ item
}}
285 Starts editing the label of the given item. This function generates a
286 EVT
\_TREE\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
287 text control will appear for in-place editing.
289 If the user changed the label (i.e. s/he does not press ESC or leave
290 the text control without changes, a EVT
\_TREE\_END\_LABEL\_EDIT event
291 will be sent which can be vetoed as well.
295 \helpref{wxTreeCtrl::EndEditLabel
}{wxtreectrlendeditlabel
},
296 \helpref{wxTreeEvent
}{wxtreeevent
}
299 \membersection{wxTreeCtrl::EndEditLabel
}\label{wxtreectrlendeditlabel
}
301 \func{void
}{EndEditLabel
}{\param{bool
}{cancelEdit
}}
303 Ends label editing. If
{\it cancelEdit
} is
{\tt true
}, the edit will be cancelled.
305 This function is currently supported under Windows only.
309 \helpref{wxTreeCtrl::EditLabel
}{wxtreectrleditlabel
}
312 \membersection{wxTreeCtrl::EnsureVisible
}\label{wxtreectrlensurevisible
}
314 \func{void
}{EnsureVisible
}{\param{const wxTreeItemId\&
}{ item
}}
316 Scrolls and/or expands items to ensure that the given item is visible.
319 \membersection{wxTreeCtrl::Expand
}\label{wxtreectrlexpand
}
321 \func{void
}{Expand
}{\param{const wxTreeItemId\&
}{ item
}}
323 Expands the given item.
326 \membersection{wxTreeCtrl::GetBoundingRect
}\label{wxtreectrlgetitemrect
}
328 \constfunc{bool
}{GetBoundingRect
}{\param{const wxTreeItemId\&
}{ item
},
\param{wxRect\&
}{rect
},
\param{bool
}{textOnly =
{\tt false
}}}
330 Retrieves the rectangle bounding the
{\it item
}. If
{\it textOnly
} is
{\tt true
},
331 only the rectangle around the item's label will be returned, otherwise the
332 item's image is also taken into account.
334 The return value is
{\tt true
} if the rectangle was successfully retrieved or
{\tt false
}
335 if it was not (in this case
{\it rect
} is not changed) - for example, if the
336 item is currently invisible.
338 \pythonnote{The wxPython version of this method requires only the
339 {\tt item
} and
{\tt textOnly
} parameters. The return value is either a
340 {\tt wxRect
} object or
{\tt None
}.
}
342 \perlnote{In wxPerl this method only takes the parameters
{\tt item
} and
343 {\tt textOnly
}, and returns a Wx::Rect ( or undef ).
}
346 \membersection{wxTreeCtrl::GetButtonsImageList
}\label{wxtreectrlgetbuttonsimagelist
}
348 \constfunc{wxImageList*
}{GetButtonsImageList
}{\void}
350 Returns the buttons image list (from which application-defined button images are taken).
352 This function is only available in the generic version.
355 \membersection{wxTreeCtrl::GetChildrenCount
}\label{wxtreectrlgetchildrencount
}
357 \constfunc{size
\_t}{GetChildrenCount
}{\param{const wxTreeItemId\&
}{ item
},
\param{bool
}{ recursively =
{\tt true
}}}
359 Returns the number of items in the branch. If
{\it recursively
} is
{\tt true
}, returns the total number
360 of descendants, otherwise only one level of children is counted.
363 \membersection{wxTreeCtrl::GetCount
}\label{wxtreectrlgetcount
}
365 \constfunc{int
}{GetCount
}{\void}
367 Returns the number of items in the control.
370 \membersection{wxTreeCtrl::GetEditControl
}\label{wxtreectrlgeteditcontrol
}
372 \constfunc{wxTextCtrl *
}{GetEditControl
}{\void}
374 Returns the edit control being currently used to edit a label. Returns
{\tt NULL
}
375 if no label is being edited.
377 {\bf NB:
} It is currently only implemented for wxMSW.
380 \membersection{wxTreeCtrl::GetFirstChild
}\label{wxtreectrlgetfirstchild
}
382 \constfunc{wxTreeItemId
}{GetFirstChild
}{\param{const wxTreeItemId\&
}{ item
},
\param{wxTreeItemIdValue \&
}{cookie
}}
384 Returns the first child; call
\helpref{wxTreeCtrl::GetNextChild
}{wxtreectrlgetnextchild
} for the next child.
386 For this enumeration function you must pass in a `cookie' parameter
387 which is opaque for the application but is necessary for the library
388 to make these functions reentrant (i.e. allow more than one
389 enumeration on one and the same object simultaneously). The cookie passed to
390 GetFirstChild and GetNextChild should be the same variable.
392 Returns an invalid tree item (i.e. IsOk() returns
{\tt false
}) if there are no further children.
396 \helpref{wxTreeCtrl::GetNextChild
}{wxtreectrlgetnextchild
},
397 \helpref{wxTreeCtrl::GetNextSibling
}{wxtreectrlgetnextsibling
}
399 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
400 value are both returned as a tuple containing the two values.
}
402 \perlnote{In wxPerl this method only takes the
{\tt item
} parameter, and
403 returns a
2-element list
{\tt ( item, cookie )
}.
}
406 \membersection{wxTreeCtrl::GetFirstVisibleItem
}\label{wxtreectrlgetfirstvisibleitem
}
408 \constfunc{wxTreeItemId
}{GetFirstVisibleItem
}{\void}
410 Returns the first visible item.
413 \membersection{wxTreeCtrl::GetImageList
}\label{wxtreectrlgetimagelist
}
415 \constfunc{wxImageList*
}{GetImageList
}{\void}
417 Returns the normal image list.
420 \membersection{wxTreeCtrl::GetIndent
}\label{wxtreectrlgetindent
}
422 \constfunc{int
}{GetIndent
}{\void}
424 Returns the current tree control indentation.
427 \membersection{wxTreeCtrl::GetItemBackgroundColour
}\label{wxtreectrlgetitembackgroundcolour
}
429 \constfunc{wxColour
}{GetItemBackgroundColour
}{\param{const wxTreeItemId\&
}{ item
}}
431 Returns the background colour of the item.
434 \membersection{wxTreeCtrl::GetItemData
}\label{wxtreectrlgetitemdata
}
436 \constfunc{wxTreeItemData*
}{GetItemData
}{\param{const wxTreeItemId\&
}{ item
}}
438 Returns the tree item data associated with the item.
442 \helpref{wxTreeItemData
}{wxtreeitemdata
}
444 \pythonnote{wxPython provides the following shortcut method:
446 \indented{2cm
}{\begin{twocollist
}\itemsep=
0pt
447 \twocolitem{{\bf GetPyData(item)
}}{Returns the Python Object
448 associated with the wxTreeItemData for the given item Id.
}
452 \perlnote{wxPerl provides the following shortcut method:
454 \begin{twocollist
}\itemsep=
0pt
455 \twocolitem{{\bf GetPlData( item )
}}{Returns the Perl data
456 associated with the Wx::TreeItemData. It is just the same as
457 tree->GetItemData(item)->GetData().
}
461 \membersection{wxTreeCtrl::GetItemFont
}\label{wxtreectrlgetitemfont
}
463 \constfunc{wxFont
}{GetItemFont
}{\param{const wxTreeItemId\&
}{ item
}}
465 Returns the font of the item label.
468 \membersection{wxTreeCtrl::GetItemImage
}\label{wxtreectrlgetitemimage
}
470 \constfunc{int
}{GetItemImage
}{\param{const wxTreeItemId\&
}{item
},
471 \param{wxTreeItemIcon
}{which = wxTreeItemIcon
\_Normal}}
473 Gets the specified item image. The value of
{\it which
} may be:
475 \begin{itemize
}\itemsep=
0pt
476 \item{wxTreeItemIcon
\_Normal} to get the normal item image
477 \item{wxTreeItemIcon
\_Selected} to get the selected item image (i.e. the image
478 which is shown when the item is currently selected)
479 \item{wxTreeItemIcon
\_Expanded} to get the expanded image (this only
480 makes sense for items which have children - then this image is shown when the
481 item is expanded and the normal image is shown when it is collapsed)
482 \item{wxTreeItemIcon
\_SelectedExpanded} to get the selected expanded image
483 (which is shown when an expanded item is currently selected)
487 \membersection{wxTreeCtrl::GetItemText
}\label{wxtreectrlgetitemtext
}
489 \constfunc{wxString
}{GetItemText
}{\param{const wxTreeItemId\&
}{ item
}}
491 Returns the item label.
494 \membersection{wxTreeCtrl::GetItemTextColour
}\label{wxtreectrlgetitemtextcolour
}
496 \constfunc{wxColour
}{GetItemTextColour
}{\param{const wxTreeItemId\&
}{ item
}}
498 Returns the colour of the item label.
501 \membersection{wxTreeCtrl::GetLastChild
}\label{wxtreectrlgetlastchild
}
503 \constfunc{wxTreeItemId
}{GetLastChild
}{\param{const wxTreeItemId\&
}{ item
}}
505 Returns the last child of the item (or an invalid tree item if this item has no children).
509 \helpref{GetFirstChild
}{wxtreectrlgetfirstchild
},
510 \helpref{wxTreeCtrl::GetNextSibling
}{wxtreectrlgetnextsibling
},
511 \helpref{GetLastChild
}{wxtreectrlgetlastchild
}
514 \membersection{wxTreeCtrl::GetNextChild
}\label{wxtreectrlgetnextchild
}
516 \constfunc{wxTreeItemId
}{GetNextChild
}{\param{const wxTreeItemId\&
}{ item
},
\param{wxTreeItemIdValue \&
}{cookie
}}
518 Returns the next child; call
\helpref{wxTreeCtrl::GetFirstChild
}{wxtreectrlgetfirstchild
} for the first child.
520 For this enumeration function you must pass in a `cookie' parameter
521 which is opaque for the application but is necessary for the library
522 to make these functions reentrant (i.e. allow more than one
523 enumeration on one and the same object simultaneously). The cookie passed to
524 GetFirstChild and GetNextChild should be the same.
526 Returns an invalid tree item if there are no further children.
530 \helpref{wxTreeCtrl::GetFirstChild
}{wxtreectrlgetfirstchild
}
532 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
533 value are both returned as a tuple containing the two values.
}
535 \perlnote{In wxPerl this method returns a
2-element list
536 {\tt ( item, cookie )
}, instead of modifying its parameters.
}
539 \membersection{wxTreeCtrl::GetNextSibling
}\label{wxtreectrlgetnextsibling
}
541 \constfunc{wxTreeItemId
}{GetNextSibling
}{\param{const wxTreeItemId\&
}{ item
}}
543 Returns the next sibling of the specified item; call
\helpref{wxTreeCtrl::GetPrevSibling
}{wxtreectrlgetprevsibling
} for the previous sibling.
545 Returns an invalid tree item if there are no further siblings.
549 \helpref{wxTreeCtrl::GetPrevSibling
}{wxtreectrlgetprevsibling
}
552 \membersection{wxTreeCtrl::GetNextVisible
}\label{wxtreectrlgetnextvisible
}
554 \constfunc{wxTreeItemId
}{GetNextVisible
}{\param{const wxTreeItemId\&
}{ item
}}
556 Returns the next visible item.
559 \membersection{wxTreeCtrl::GetItemParent
}\label{wxtreectrlgetitemparent
}
561 \constfunc{wxTreeItemId
}{GetItemParent
}{\param{const wxTreeItemId\&
}{ item
}}
563 Returns the item's parent.
566 \membersection{wxTreeCtrl::GetParent
}\label{wxtreectrlgetparent
}
568 \constfunc{wxTreeItemId
}{GetParent
}{\param{const wxTreeItemId\&
}{ item
}}
570 {\bf NOTE:
} This function is deprecated and will only work if
{\tt WXWIN
\_COMPATIBILITY\_2\_2}
571 is defined. Use
\helpref{wxTreeCtrl::GetItemParent
}{wxtreectrlgetitemparent
} instead.
573 Returns the item's parent.
575 \pythonnote{This method is named
{\tt GetItemParent
} to avoid a name
576 clash with wxWindow::GetParent.
}
579 \membersection{wxTreeCtrl::GetPrevSibling
}\label{wxtreectrlgetprevsibling
}
581 \constfunc{wxTreeItemId
}{GetPrevSibling
}{\param{const wxTreeItemId\&
}{ item
}}
583 Returns the previous sibling of the specified item; call
\helpref{wxTreeCtrl::GetNextSibling
}{wxtreectrlgetnextsibling
} for the next sibling.
585 Returns an invalid tree item if there are no further children.
589 \helpref{wxTreeCtrl::GetNextSibling
}{wxtreectrlgetnextsibling
}
592 \membersection{wxTreeCtrl::GetPrevVisible
}\label{wxtreectrlgetprevvisible
}
594 \constfunc{wxTreeItemId
}{GetPrevVisible
}{\param{const wxTreeItemId\&
}{ item
}}
596 Returns the previous visible item.
599 \membersection{wxTreeCtrl::GetRootItem
}\label{wxtreectrlgetrootitem
}
601 \constfunc{wxTreeItemId
}{GetRootItem
}{\void}
603 Returns the root item for the tree control.
606 \membersection{wxTreeCtrl::GetItemSelectedImage
}\label{wxtreectrlgetitemselectedimage
}
608 \constfunc{int
}{GetItemSelectedImage
}{\param{const wxTreeItemId\&
}{item
}}
610 Gets the selected item image (this function is obsolete, use
611 {\tt GetItemImage(item, wxTreeItemIcon
\_Selected}) instead).
614 \membersection{wxTreeCtrl::GetSelection
}\label{wxtreectrlgetselection
}
616 \constfunc{wxTreeItemId
}{GetSelection
}{\void}
618 Returns the selection, or an invalid item if there is no selection.
619 This function only works with the controls without wxTR
\_MULTIPLE style, use
620 \helpref{GetSelections
}{wxtreectrlgetselections
} for the controls which do have
624 \membersection{wxTreeCtrl::GetSelections
}\label{wxtreectrlgetselections
}
626 \constfunc{size
\_t}{GetSelections
}{\param{wxArrayTreeItemIds\&
}{selection
}}
628 Fills the array of tree items passed in with the currently selected items. This
629 function can be called only if the control has the wxTR
\_MULTIPLE style.
631 Returns the number of selected items.
633 \pythonnote{The wxPython version of this method accepts no parameters
634 and returns a Python list of
{\tt wxTreeItemId
}s.
}
636 \perlnote{In wxPerl this method takes no parameters and returns a list of
637 {\tt Wx::TreeItemId
}s.
}
640 \membersection{wxTreeCtrl::GetStateImageList
}\label{wxtreectrlgetstateimagelist
}
642 \constfunc{wxImageList*
}{GetStateImageList
}{\void}
644 Returns the state image list (from which application-defined state images are taken).
647 \membersection{wxTreeCtrl::HitTest
}\label{wxtreectrlhittest
}
649 \func{wxTreeItemId
}{HitTest
}{\param{const wxPoint\&
}{point
},
\param{int\&
}{flags
}}
651 Calculates which (if any) item is under the given point, returning the tree item
652 id at this point plus extra information
{\it flags
}.
{\it flags
} is a bitlist of the following:
655 \begin{twocollist
}\itemsep=
0pt
656 \twocolitem{wxTREE
\_HITTEST\_ABOVE}{Above the client area.
}
657 \twocolitem{wxTREE
\_HITTEST\_BELOW}{Below the client area.
}
658 \twocolitem{wxTREE
\_HITTEST\_NOWHERE}{In the client area but below the last item.
}
659 \twocolitem{wxTREE
\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.
}
660 \twocolitem{wxTREE
\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.
}
661 \twocolitem{wxTREE
\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.
}
662 \twocolitem{wxTREE
\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.
}
663 \twocolitem{wxTREE
\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.
}
664 \twocolitem{wxTREE
\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.
}
665 \twocolitem{wxTREE
\_HITTEST\_TOLEFT}{To the right of the client area.
}
666 \twocolitem{wxTREE
\_HITTEST\_TORIGHT}{To the left of the client area.
}
669 \pythonnote{in wxPython both the wxTreeItemId and the flags are
670 returned as a tuple.
}
672 \perlnote{In wxPerl this method only takes the
{\tt point
} parameter
673 and returns a
2-element list
{\tt ( item, flags )
}.
}
676 \membersection{wxTreeCtrl::InsertItem
}\label{wxtreectrlinsertitem
}
678 \func{wxTreeItemId
}{InsertItem
}{\param{const wxTreeItemId\&
}{parent
},
\param{const wxTreeItemId\&
}{previous
},
\param{const wxString\&
}{ text
},
679 \param{int
}{ image = -
1},
\param{int
}{ selImage = -
1},
\param{wxTreeItemData*
}{ data =
{\tt NULL
}}}
681 \func{wxTreeItemId
}{InsertItem
}{\param{const wxTreeItemId\&
}{parent
},
\param{size
\_t}{ before
},
\param{const wxString\&
}{ text
},
682 \param{int
}{ image = -
1},
\param{int
}{ selImage = -
1},
\param{wxTreeItemData*
}{ data =
{\tt NULL
}}}
684 Inserts an item after a given one (
{\it previous
}) or before one identified by its position (
{\it before
}).
685 {\it before
} must be less than the number of children.
687 The
{\it image
} and
{\it selImage
} parameters are an index within
688 the normal image list specifying the image to use for unselected and
689 selected items, respectively.
690 If
{\it image
} > -
1 and
{\it selImage
} is -
1, the same image is used for
691 both selected and unselected items.
693 \pythonnote{The second form of this method is called
694 {\tt InsertItemBefore
} in wxPython.
}
697 \membersection{wxTreeCtrl::IsBold
}\label{wxtreectrlisbold
}
699 \constfunc{bool
}{IsBold
}{\param{const wxTreeItemId\&
}{item
}}
701 Returns
{\tt true
} if the given item is in bold state.
703 See also:
\helpref{SetItemBold
}{wxtreectrlsetitembold
}
706 \membersection{wxTreeCtrl::IsExpanded
}\label{wxtreectrlisexpanded
}
708 \constfunc{bool
}{IsExpanded
}{\param{const wxTreeItemId\&
}{ item
}}
710 Returns
{\tt true
} if the item is expanded (only makes sense if it has children).
713 \membersection{wxTreeCtrl::IsSelected
}\label{wxtreectrlisselected
}
715 \constfunc{bool
}{IsSelected
}{\param{const wxTreeItemId\&
}{ item
}}
717 Returns
{\tt true
} if the item is selected.
720 \membersection{wxTreeCtrl::IsVisible
}\label{wxtreectrlisvisible
}
722 \constfunc{bool
}{IsVisible
}{\param{const wxTreeItemId\&
}{ item
}}
724 Returns
{\tt true
} if the item is visible (it might be outside the view, or not expanded).
727 \membersection{wxTreeCtrl::ItemHasChildren
}\label{wxtreectrlitemhaschildren
}
729 \constfunc{bool
}{ItemHasChildren
}{\param{const wxTreeItemId\&
}{ item
}}
731 Returns
{\tt true
} if the item has children.
734 \membersection{wxTreeCtrl::OnCompareItems
}\label{wxtreectrloncompareitems
}
736 \func{int
}{OnCompareItems
}{\param{const wxTreeItemId\&
}{item1
},
\param{const wxTreeItemId\&
}{item2
}}
738 Override this function in the derived class to change the sort order of the
739 items in the tree control. The function should return a negative, zero or
740 positive value if the first item is less than, equal to or greater than the
743 The base class version compares items alphabetically.
745 See also:
\helpref{SortChildren
}{wxtreectrlsortchildren
}
748 \membersection{wxTreeCtrl::PrependItem
}\label{wxtreectrlprependitem
}
750 \func{wxTreeItemId
}{PrependItem
}{\param{const wxTreeItemId\&
}{parent
},
\param{const wxString\&
}{ text
},
751 \param{int
}{ image = -
1},
\param{int
}{ selImage = -
1},
\param{wxTreeItemData*
}{ data =
{\tt NULL
}}}
753 Appends an item as the first child of
{\it parent
}, return a new item id.
755 The
{\it image
} and
{\it selImage
} parameters are an index within
756 the normal image list specifying the image to use for unselected and
757 selected items, respectively.
758 If
{\it image
} > -
1 and
{\it selImage
} is -
1, the same image is used for
759 both selected and unselected items.
762 \membersection{wxTreeCtrl::ScrollTo
}\label{wxtreectrlscrollto
}
764 \func{void
}{ScrollTo
}{\param{const wxTreeItemId\&
}{ item
}}
766 Scrolls the specified item into view.
769 \membersection{wxTreeCtrl::SelectItem
}\label{wxtreectrlselectitem
}
771 \func{bool
}{SelectItem
}{\param{const wxTreeItemId\&
}{ item
},
\param{bool
}{select =
\true}}
773 Selects the given item. In multiple selection controls, can be also used to
774 deselect a currently selected item if the value of
\arg{select
} is false.
777 \membersection{wxTreeCtrl::SetButtonsImageList
}\label{wxtreectrlsetbuttonsimagelist
}
779 \func{void
}{SetButtonsImageList
}{\param{wxImageList*
}{ imageList
}}
781 Sets the buttons image list (from which application-defined button images are taken).
782 The button images assigned with this method will
783 {\bf not
} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
785 Setting or assigning the button image list enables the display of image buttons.
786 Once enabled, the only way to disable the display of button images is to set
787 the button image list to
{\tt NULL
}.
789 This function is only available in the generic version.
791 See also
\helpref{AssignButtonsImageList
}{wxtreectrlassignbuttonsimagelist
}.
794 \membersection{wxTreeCtrl::SetIndent
}\label{wxtreectrlsetindent
}
796 \func{void
}{SetIndent
}{\param{int
}{indent
}}
798 Sets the indentation for the tree control.
801 \membersection{wxTreeCtrl::SetImageList
}\label{wxtreectrlsetimagelist
}
803 \func{void
}{SetImageList
}{\param{wxImageList*
}{ imageList
}}
805 Sets the normal image list. Image list assigned with this method will
806 {\bf not
} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
808 See also
\helpref{AssignImageList
}{wxtreectrlassignimagelist
}.
812 \membersection{wxTreeCtrl::SetItemBackgroundColour
}\label{wxtreectrlsetitembackgroundcolour
}
814 \func{void
}{SetItemBackgroundColour
}{\param{const wxTreeItemId\&
}{ item
},
\param{const wxColour\&
}{col
}}
816 Sets the colour of the item's background.
819 \membersection{wxTreeCtrl::SetItemBold
}\label{wxtreectrlsetitembold
}
821 \func{void
}{SetItemBold
}{\param{const wxTreeItemId\&
}{item
},
\param{bool
}{ bold =
{\tt true
}}}
823 Makes item appear in bold font if
{\it bold
} parameter is
{\tt true
} or resets it to
826 See also:
\helpref{IsBold
}{wxtreectrlisbold
}
829 \membersection{wxTreeCtrl::SetItemData
}\label{wxtreectrlsetitemdata
}
831 \func{void
}{SetItemData
}{\param{const wxTreeItemId\&
}{ item
},
\param{wxTreeItemData*
}{data
}}
833 Sets the item client data.
835 \pythonnote{wxPython provides the following shortcut method:
\par
836 \indented{2cm
}{\begin{twocollist
}\itemsep=
0pt
837 \twocolitem{{\bf SetPyData(item, obj)
}}{Associate the given Python
838 Object with the wxTreeItemData for the given item Id.
}
842 \perlnote{wxPerl provides the following shortcut method:
844 \begin{twocollist
}\itemsep=
0pt
845 \twocolitem{{\bf SetPlData( item, data )
}}{Sets the Perl data
846 associated with the Wx::TreeItemData. It is just the same as
847 tree->GetItemData(item)->SetData(data).
}
851 \membersection{wxTreeCtrl::SetItemFont
}\label{wxtreectrlsetitemfont
}
853 \func{void
}{SetItemFont
}{\param{const wxTreeItemId\&
}{ item
},
\param{const wxFont\&
}{font
}}
855 Sets the item's font. All items in the tree should have the same height to avoid
856 text clipping, so the fonts height should be the same for all of them,
857 although font attributes may vary.
861 \helpref{SetItemBold
}{wxtreectrlsetitembold
}
864 \membersection{wxTreeCtrl::SetItemHasChildren
}\label{wxtreectrlsetitemhaschildren
}
866 \func{void
}{SetItemHasChildren
}{\param{const wxTreeItemId\&
}{ item
},
\param{bool
}{hasChildren =
{\tt true
}}}
868 Force appearance of the button next to the item. This is useful to
869 allow the user to expand the items which don't have any children now,
870 but instead adding them only when needed, thus minimizing memory
871 usage and loading time.
874 \membersection{wxTreeCtrl::SetItemImage
}\label{wxtreectrlsetitemimage
}
876 \func{void
}{SetItemImage
}{\param{const wxTreeItemId\&
}{ item
},
877 \param{int
}{image
},
\param{wxTreeItemIcon
}{which = wxTreeItemIcon
\_Normal}}
879 Sets the specified item image. See
\helpref{GetItemImage
}{wxtreectrlgetitemimage
}
880 for the description of the
{\it which
} parameter.
883 \membersection{wxTreeCtrl::SetItemSelectedImage
}\label{wxtreectrlsetitemselectedimage
}
885 \func{void
}{SetItemSelectedImage
}{\param{const wxTreeItemId\&
}{ item
},
\param{int
}{selImage
}}
887 Sets the selected item image (this function is obsolete, use
{\tt SetItemImage(item, wxTreeItemIcon
\_Selected}) instead).
890 \membersection{wxTreeCtrl::SetItemText
}\label{wxtreectrlsetitemtext
}
892 \func{void
}{SetItemText
}{\param{const wxTreeItemId\&
}{ item
},
\param{const wxString\&
}{text
}}
897 \membersection{wxTreeCtrl::SetItemTextColour
}\label{wxtreectrlsetitemtextcolour
}
899 \func{void
}{SetItemTextColour
}{\param{const wxTreeItemId\&
}{ item
},
\param{const wxColour\&
}{col
}}
901 Sets the colour of the item's text.
904 \membersection{wxTreeCtrl::SetStateImageList
}\label{wxtreectrlsetstateimagelist
}
906 \func{void
}{SetStateImageList
}{\param{wxImageList*
}{ imageList
}}
908 Sets the state image list (from which application-defined state images are taken).
909 Image list assigned with this method will
910 {\bf not
} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
912 See also
\helpref{AssignStateImageList
}{wxtreectrlassignstateimagelist
}.
914 \membersection{wxTreeCtrl::SetWindowStyle
}\label{wxtreectrlsetwindowstyle
}
916 \func{void
}{SetWindowStyle
}{\param{long
}{styles
}}
918 Sets the mode flags associated with the display of the tree control.
919 The new mode takes effect immediately.
920 (Generic only; MSW ignores changes.)
923 \membersection{wxTreeCtrl::SortChildren
}\label{wxtreectrlsortchildren
}
925 \func{void
}{SortChildren
}{\param{const wxTreeItemId\&
}{ item
}}
927 Sorts the children of the given item using
928 \helpref{OnCompareItems
}{wxtreectrloncompareitems
} method of wxTreeCtrl. You
929 should override that method to change the sort order (the default is ascending
930 case-sensitive alphabetical order).
934 \helpref{wxTreeItemData
}{wxtreeitemdata
},
\helpref{OnCompareItems
}{wxtreectrloncompareitems
}
937 \membersection{wxTreeCtrl::Toggle
}\label{wxtreectrltoggle
}
939 \func{void
}{Toggle
}{\param{const wxTreeItemId\&
}{ item
}}
941 Toggles the given item between collapsed and expanded states.
944 \membersection{wxTreeCtrl::ToggleItemSelection
}\label{wxtreectrltoggleitemselection
}
946 \func{void
}{ToggleItemSelection
}{\param{const wxTreeItemId\&
}{ item
}}
948 Toggles the given item between selected and unselected states. For
949 multiselection controls only.
952 \membersection{wxTreeCtrl::Unselect
}\label{wxtreectrlunselect
}
954 \func{void
}{Unselect
}{\void}
956 Removes the selection from the currently selected item (if any).
959 \membersection{wxTreeCtrl::UnselectAll
}\label{wxtreectrlunselectall
}
961 \func{void
}{UnselectAll
}{\void}
963 This function either behaves the same as
\helpref{Unselect
}{wxtreectrlunselect
}
964 if the control doesn't have wxTR
\_MULTIPLE style, or removes the selection from
965 all items if it does have this style.
968 \membersection{wxTreeCtrl::UnselectItem
}\label{wxtreectrlunselectitem
}
970 \func{void
}{UnselectItem
}{\param{const wxTreeItemId\&
}{item
}}
972 Unselects the given item. This works in multiselection controls only.