]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \section{\class{wxTreeCtrl}}\label{wxtreectrl} |
2 | ||
3 | A tree control presents information as a hierarchy, with items that may be expanded | |
4fabb575 | 4 | to show further items. Items in a tree control are referenced by wxTreeItemId handles. |
a660d684 KB |
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 | ||
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 | 24 | left of parent items. Win32 only. } |
63da7df7 JS |
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.} | |
a660d684 KB |
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.} | |
9dfbf520 VZ |
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.} | |
a660d684 KB |
34 | \end{twocollist} |
35 | ||
36 | See also \helpref{window styles overview}{windowstyles}. | |
37 | ||
5de76427 JS |
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.} | |
fd128b0c RR |
47 | \twocolitem{{\bf EVT\_TREE\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.} |
48 | \twocolitem{{\bf EVT\_TREE\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.} | |
5de76427 JS |
49 | \twocolitem{{\bf EVT\_TREE\_DELETE\_ITEM(id, func)}}{Delete an item.} |
50 | \twocolitem{{\bf EVT\_TREE\_GET\_INFO(id, func)}}{Request information from the application.} | |
51 | \twocolitem{{\bf EVT\_TREE\_SET\_INFO(id, func)}}{Information is being supplied.} | |
9711961c | 52 | \twocolitem{{\bf EVT\_TREE\_ITEM\_ACTIVATED(id, func)}}{The item has been activated, i.e. chosen by double clicking it with mouse or from keyboard} |
61b1a1af VZ |
53 | \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSED(id, func)}}{Parent has been collapsed.} |
54 | \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSING(id, func)}}{Parent is being collapsed. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.} | |
5de76427 | 55 | \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{Parent has been expanded.} |
fd128b0c | 56 | \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{Parent is being expanded. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.} |
5de76427 | 57 | \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGED(id, func)}}{Selection has changed.} |
fd128b0c | 58 | \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGING(id, func)}}{Selection is changing. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.} |
5de76427 JS |
59 | \twocolitem{{\bf EVT\_TREE\_KEY\_DOWN(id, func)}}{A key has been pressed.} |
60 | \end{twocollist}% | |
61 | ||
a660d684 KB |
62 | \wxheading{See also} |
63 | ||
4fabb575 | 64 | \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp |
a660d684 KB |
65 | \helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent} |
66 | ||
61714c23 VZ |
67 | \wxheading{Win32 notes} |
68 | ||
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 | |
f6bcfd97 BP |
74 | default background colour. The recommended solution is to upgrade the {\tt comctl32.dll} |
75 | to 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 | ||
84 | Default 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 | |
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 | ||
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 | ||
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 | ||
46cd520d VS |
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 | ||
4fabb575 JS |
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 | ||
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 | |
176 | Creates 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 | 182 | Deletes the specified item. |
a660d684 | 183 | |
4fabb575 | 184 | \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems} |
a660d684 | 185 | |
4fabb575 | 186 | \func{void}{DeleteAllItems}{\void} |
a660d684 | 187 | |
4fabb575 | 188 | Deletes 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 |
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. | |
a660d684 | 197 | |
fd128b0c | 198 | If the user changed the label (i.e. s/he does not press ESC or leave |
76e1c2de | 199 | the text control without changes, a EVT\_TREE\_END\_LABEL\_EDIT event |
fd128b0c | 200 | will 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 | |
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 | ||
a660d684 KB |
219 | \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible} |
220 | ||
4fabb575 | 221 | \func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}} |
a660d684 KB |
222 | |
223 | Scrolls 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 | |
229 | Expands 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 |
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. | |
a660d684 | 242 | |
76e1c2de | 243 | \pythonnote{The wxPython version of this method requires only the |
c9110876 VS |
244 | {\tt item} and {\tt textOnly} parameters. The return value is either a |
245 | {\tt wxRect} object or {\tt None}.} | |
76e1c2de | 246 | |
4fabb575 | 247 | \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount} |
a660d684 | 248 | |
4fabb575 | 249 | \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = TRUE}} |
a660d684 | 250 | |
4fabb575 JS |
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. | |
a660d684 KB |
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 | ||
4fabb575 JS |
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 | ||
ed93168b | 278 | Returns an invalid tree item if there are no further children. |
4fabb575 JS |
279 | |
280 | \wxheading{See also} | |
281 | ||
282 | \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} | |
283 | ||
f899db6d RD |
284 | \pythonnote{In wxPython the returned wxTreeItemId and the new cookie |
285 | value are both returned as a tuple containing the two values.} | |
286 | ||
a660d684 KB |
287 | \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem} |
288 | ||
4fabb575 | 289 | \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void} |
a660d684 KB |
290 | |
291 | Returns the first visible item. | |
292 | ||
293 | \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist} | |
294 | ||
e2b34251 | 295 | \constfunc{wxImageList*}{GetImageList}{\void} |
a660d684 | 296 | |
e2b34251 | 297 | Returns the normal image list. |
a660d684 KB |
298 | |
299 | \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent} | |
300 | ||
301 | \constfunc{int}{GetIndent}{\void} | |
302 | ||
303 | Returns the current tree control indentation. | |
304 | ||
4fabb575 | 305 | \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata} |
a660d684 | 306 | |
4fabb575 | 307 | \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}} |
a660d684 | 308 | |
4fabb575 | 309 | Returns the tree item data associated with the item. |
a660d684 | 310 | |
4fabb575 | 311 | \wxheading{See also} |
a660d684 | 312 | |
4fabb575 | 313 | \helpref{wxTreeItemData}{wxtreeitemdata} |
a660d684 | 314 | |
ecf527c0 JS |
315 | \pythonnote{wxPython provides the following shortcut method: |
316 | ||
317 | \indented{2cm}{\begin{twocollist}\itemsep=0pt | |
c9110876 | 318 | \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object |
f899db6d RD |
319 | associated with the wxTreeItemData for the given item Id.} |
320 | \end{twocollist}} | |
321 | } | |
322 | ||
4fabb575 | 323 | \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage} |
a660d684 | 324 | |
74b31181 | 325 | \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item}, |
ecf527c0 | 326 | \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}} |
74b31181 VZ |
327 | |
328 | Gets the specified item image. The value of {\it which} may be: | |
ecf527c0 | 329 | |
74b31181 VZ |
330 | \begin{itemize}\itemsep=0pt |
331 | \item{wxTreeItemIcon\_Normal} to get the normal item image | |
332 | \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image | |
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} | |
a660d684 | 340 | |
4fabb575 | 341 | \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext} |
a660d684 | 342 | |
4fabb575 | 343 | \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}} |
a660d684 | 344 | |
4fabb575 | 345 | Returns the item label. |
a660d684 | 346 | |
978f38c2 VZ |
347 | \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild} |
348 | ||
349 | \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}} | |
350 | ||
ed93168b | 351 | Returns the last child of the item (or an invalid tree item if this item has no children). |
978f38c2 VZ |
352 | |
353 | \wxheading{See also} | |
354 | ||
f6bcfd97 | 355 | \helpref{GetFirstChild}{wxtreectrlgetfirstchild}, |
978f38c2 VZ |
356 | \helpref{GetLastChild}{wxtreectrlgetlastchild} |
357 | ||
4fabb575 | 358 | \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild} |
a660d684 | 359 | |
4fabb575 | 360 | \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}} |
a660d684 | 361 | |
4fabb575 | 362 | Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child. |
a660d684 | 363 | |
4fabb575 JS |
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. | |
a660d684 | 369 | |
ed93168b | 370 | Returns an invalid tree item if there are no further children. |
a660d684 | 371 | |
4fabb575 | 372 | \wxheading{See also} |
a660d684 | 373 | |
4fabb575 | 374 | \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} |
a660d684 | 375 | |
f899db6d RD |
376 | \pythonnote{In wxPython the returned wxTreeItemId and the new cookie |
377 | value are both returned as a tuple containing the two values.} | |
378 | ||
4fabb575 | 379 | \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling} |
a660d684 | 380 | |
4fabb575 | 381 | \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}} |
a660d684 | 382 | |
4fabb575 | 383 | Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling. |
a660d684 | 384 | |
ed93168b | 385 | Returns an invalid tree item if there are no further siblings. |
a660d684 | 386 | |
4fabb575 JS |
387 | \wxheading{See also} |
388 | ||
389 | \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} | |
390 | ||
391 | \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible} | |
392 | ||
393 | \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}} | |
a660d684 KB |
394 | |
395 | Returns the next visible item. | |
396 | ||
397 | \membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent} | |
398 | ||
4fabb575 | 399 | \constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}} |
a660d684 KB |
400 | |
401 | Returns the item's parent. | |
402 | ||
c9110876 | 403 | \pythonnote{This method is named {\tt GetItemParent} to avoid a name |
874a1686 RD |
404 | clash with wxWindow::GetParent.} |
405 | ||
4fabb575 JS |
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 | ||
ed93168b | 412 | Returns an invalid tree item if there are no further children. |
4fabb575 JS |
413 | |
414 | \wxheading{See also} | |
415 | ||
416 | \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} | |
417 | ||
418 | \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible} | |
419 | ||
420 | \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}} | |
421 | ||
422 | Returns the previous visible item. | |
423 | ||
a660d684 KB |
424 | \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem} |
425 | ||
4fabb575 | 426 | \constfunc{wxTreeItemId}{GetRootItem}{\void} |
a660d684 KB |
427 | |
428 | Returns the root item for the tree control. | |
429 | ||
ed93168b | 430 | \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage} |
4fabb575 | 431 | |
ed93168b | 432 | \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}} |
4fabb575 | 433 | |
f6bcfd97 | 434 | Gets the selected item image (this function is obsolete, use |
b2cf617c | 435 | {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead). |
4fabb575 | 436 | |
a660d684 KB |
437 | \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection} |
438 | ||
4fabb575 | 439 | \constfunc{wxTreeItemId}{GetSelection}{\void} |
a660d684 | 440 | |
ed93168b | 441 | Returns the selection, or an invalid item if there is no selection. |
f6bcfd97 | 442 | This function only works with the controls without wxTR\_MULTIPLE style, use |
9dfbf520 VZ |
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. | |
a660d684 | 454 | |
76e1c2de | 455 | \pythonnote{The wxPython version of this method accepts no parameters |
ecf527c0 | 456 | and returns a Python list of {\tt wxTreeItemId}s.} |
76e1c2de | 457 | |
e2b34251 JS |
458 | \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist} |
459 | ||
460 | \constfunc{wxImageList*}{GetStateImageList}{\void} | |
461 | ||
462 | Returns the state image list (from which application-defined state images are taken). | |
463 | ||
a660d684 KB |
464 | \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest} |
465 | ||
aa9fb2be | 466 | \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}} |
a660d684 | 467 | |
f6bcfd97 BP |
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: | |
a660d684 KB |
470 | |
471 | \twocolwidtha{5cm} | |
472 | \begin{twocollist}\itemsep=0pt | |
473 | \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.} | |
474 | \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.} | |
475 | \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.} | |
476 | \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.} | |
477 | \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.} | |
478 | \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.} | |
479 | \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.} | |
480 | \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.} | |
481 | \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.} | |
482 | \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.} | |
483 | \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.} | |
484 | \end{twocollist} | |
485 | ||
aa9fb2be RD |
486 | \pythonnote{in wxPython both the wxTreeItemId and the flags are |
487 | returned as a tuple.} | |
488 | ||
a660d684 KB |
489 | \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem} |
490 | ||
4fabb575 JS |
491 | \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text}, |
492 | \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}} | |
a660d684 | 493 | |
f2593d0d RR |
494 | \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text}, |
495 | \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}} | |
496 | ||
497 | Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}). | |
a660d684 KB |
498 | |
499 | If {\it image} > -1 and {\it selImage} is -1, the same image is used for | |
500 | both selected and unselected items. | |
501 | ||
f6bcfd97 BP |
502 | \pythonnote{The second form of this method is called |
503 | \tt{InsertItemBefore} in wxPython.} | |
504 | ||
ed93168b VZ |
505 | \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold} |
506 | ||
507 | \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}} | |
508 | ||
509 | Returns TRUE if the given item is in bold state. | |
510 | ||
511 | See also: \helpref{SetItemBold}{wxtreectrlsetitembold} | |
512 | ||
4fabb575 JS |
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 | ||
a660d684 KB |
531 | \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren} |
532 | ||
4fabb575 | 533 | \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}} |
a660d684 KB |
534 | |
535 | Returns TRUE if the item has children. | |
536 | ||
ed93168b VZ |
537 | \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems} |
538 | ||
539 | \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}} | |
540 | ||
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 | ||
4fabb575 JS |
550 | \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem} |
551 | ||
552 | \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text}, | |
553 | \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}} | |
554 | ||
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 | ||
a660d684 KB |
560 | \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto} |
561 | ||
4fabb575 | 562 | \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}} |
a660d684 | 563 | |
4fabb575 | 564 | Scrolls the specified item into view. |
a660d684 KB |
565 | |
566 | \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem} | |
567 | ||
4fabb575 | 568 | \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}} |
a660d684 KB |
569 | |
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 | ||
e2b34251 | 580 | \func{void}{SetImageList}{\param{wxImageList*}{ imageList}} |
a660d684 | 581 | |
46cd520d VS |
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 | ||
a660d684 | 587 | |
9ec64fa7 VZ |
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 | ||
ed93168b VZ |
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 | ||
4fabb575 | 603 | \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata} |
a660d684 | 604 | |
4fabb575 | 605 | \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}} |
a660d684 | 606 | |
4fabb575 | 607 | Sets the item client data. |
a660d684 | 608 | |
f899db6d | 609 | \pythonnote{wxPython provides the following shortcut method:\par |
ecf527c0 | 610 | \indented{2cm}{\begin{twocollist}\itemsep=0pt |
c9110876 | 611 | \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python |
f899db6d RD |
612 | Object with the wxTreeItemData for the given item Id.} |
613 | \end{twocollist}} | |
614 | } | |
615 | ||
9ec64fa7 VZ |
616 | \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont} |
617 | ||
618 | \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}} | |
619 | ||
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 | ||
4fabb575 | 628 | \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren} |
a660d684 | 629 | |
4fabb575 | 630 | \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = TRUE}} |
a660d684 | 631 | |
4fabb575 JS |
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. | |
a660d684 KB |
636 | |
637 | \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage} | |
638 | ||
74b31181 | 639 | \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item}, |
ecf527c0 | 640 | \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}} |
a660d684 | 641 | |
f6bcfd97 | 642 | Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage} |
b2cf617c | 643 | for the description of the {\it which} parameter. |
a660d684 | 644 | |
4fabb575 | 645 | \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage} |
a660d684 | 646 | |
4fabb575 | 647 | \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}} |
a660d684 | 648 | |
b2cf617c | 649 | Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead). |
a660d684 KB |
650 | |
651 | \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext} | |
652 | ||
4fabb575 | 653 | \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}} |
a660d684 KB |
654 | |
655 | Sets the item label. | |
656 | ||
9ec64fa7 VZ |
657 | \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour} |
658 | ||
659 | \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}} | |
660 | ||
661 | Sets the colour of the items text. | |
662 | ||
e2b34251 JS |
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). | |
46cd520d VS |
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}. | |
e2b34251 | 672 | |
4fabb575 | 673 | \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren} |
a660d684 | 674 | |
ed93168b | 675 | \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}} |
a660d684 | 676 | |
f6bcfd97 | 677 | Sorts the children of the given item using |
ed93168b | 678 | \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You |
b2cf617c | 679 | should override that method to change the sort order (the default is ascending |
ed93168b | 680 | alphabetical order). |
4fabb575 JS |
681 | |
682 | \wxheading{See also} | |
683 | ||
ed93168b | 684 | \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems} |
4fabb575 JS |
685 | |
686 | \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle} | |
687 | ||
688 | \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}} | |
689 | ||
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 | ||
9dfbf520 VZ |
698 | \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall} |
699 | ||
700 | \func{void}{UnselectAll}{\void} | |
701 | ||
f6bcfd97 | 702 | This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect} |
9dfbf520 VZ |
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 | ||
4fabb575 JS |
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 | ||
954b8ae6 JS |
724 | \wxheading{Include files} |
725 | ||
726 | <wx/treectrl.h> | |
727 | ||
4fabb575 JS |
728 | \wxheading{See also} |
729 | ||
730 | \helpref{wxTreeCtrl}{wxtreectrl} | |
731 | ||
732 | \latexignore{\rtfignore{\wxheading{Members}}} | |
733 | ||
734 | \membersection{wxTreeItemData::wxTreeItemData}\label{wxtreeitemdataconstr} | |
735 | ||
736 | \func{}{wxTreeItemData}{\void} | |
737 | ||
738 | Default constructor. | |
739 | ||
f899db6d RD |
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 | |
ecf527c0 JS |
746 | the object: |
747 | ||
748 | \indented{2cm}{\begin{twocollist}\itemsep=0pt | |
c9110876 VS |
749 | \twocolitem{{\bf GetData()}}{Returns a reference to the Python Object} |
750 | \twocolitem{{\bf SetData(obj)}}{Associates a new Python Object with the | |
f899db6d RD |
751 | wxTreeItemData} |
752 | \end{twocollist}} | |
753 | } | |
754 | ||
755 | ||
4fabb575 JS |
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} | |
a660d684 | 769 | |
4fabb575 | 770 | \func{void}{SetId}{\param{const wxTreeItemId\&}{ id}} |
a660d684 | 771 | |
4fabb575 | 772 | Sets the item associated with this node. |
a660d684 | 773 |