]>
Commit | Line | Data |
---|---|---|
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 long integer 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{Window styles} | |
16 | ||
17 | \twocolwidtha{5cm} | |
18 | \begin{twocollist}\itemsep=0pt | |
19 | \twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style to show + and - buttons to the | |
20 | left of parent items.} | |
21 | \twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style if you wish the user to be | |
22 | able to edit labels in the tree control.} | |
23 | \end{twocollist} | |
24 | ||
25 | See also \helpref{window styles overview}{windowstyles}. | |
26 | ||
27 | \wxheading{See also} | |
28 | ||
29 | \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp | |
30 | \helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent} | |
31 | ||
32 | \latexignore{\rtfignore{\wxheading{Members}}} | |
33 | ||
34 | \membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr} | |
35 | ||
36 | \func{}{wxTreeCtrl}{\void} | |
37 | ||
38 | Default constructor. | |
39 | ||
40 | \func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp | |
41 | \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp | |
42 | \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}} | |
43 | ||
44 | Constructor, creating and showing a tree control. | |
45 | ||
46 | \wxheading{Parameters} | |
47 | ||
48 | \docparam{parent}{Parent window. Must not be NULL.} | |
49 | ||
50 | \docparam{id}{Window identifier. A value of -1 indicates a default value.} | |
51 | ||
52 | \docparam{pos}{Window position.} | |
53 | ||
54 | \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized | |
55 | appropriately.} | |
56 | ||
57 | \docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.} | |
58 | ||
59 | \docparam{validator}{Window validator.} | |
60 | ||
61 | \docparam{name}{Window name.} | |
62 | ||
63 | \wxheading{See also} | |
64 | ||
65 | \helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator} | |
66 | ||
67 | \membersection{wxTreeCtrl::\destruct{wxTreeCtrl}} | |
68 | ||
69 | \func{void}{\destruct{wxTreeCtrl}}{\void} | |
70 | ||
71 | Destructor, destroying the list control. | |
72 | ||
73 | \membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate} | |
74 | ||
75 | \func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp | |
76 | \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp | |
77 | \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}} | |
78 | ||
79 | Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details. | |
80 | ||
81 | \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems} | |
82 | ||
83 | \func{bool}{DeleteAllItems}{\void} | |
84 | ||
85 | Deletes all the items in the control. | |
86 | ||
87 | \membersection{wxTreeCtrl::DeleteItem}\label{wxtreectrldeleteitem} | |
88 | ||
89 | \func{bool}{DeleteItem}{\param{long }{item}} | |
90 | ||
91 | Deletes the specified item. | |
92 | ||
93 | \membersection{wxTreeCtrl::Edit}\label{wxtreectrledit} | |
94 | ||
95 | \func{wxTextCtrl\&}{Edit}{\param{long }{item}} | |
96 | ||
97 | Starts editing the label of the given item, returning the text control that the tree control uses for editing. | |
98 | ||
99 | \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible} | |
100 | ||
101 | \func{bool}{EnsureVisible}{\param{long }{item}} | |
102 | ||
103 | Scrolls and/or expands items to ensure that the given item is visible. | |
104 | ||
105 | \membersection{wxTreeCtrl::ExpandItem}\label{wxtreectrlexpanditem} | |
106 | ||
107 | \func{bool}{ExpandItem}{\param{long }{item}, \param{int }{action}} | |
108 | ||
109 | Expands the given item. | |
110 | ||
111 | {\it action} may be one of: | |
112 | ||
113 | \twocolwidtha{5cm} | |
114 | \begin{twocollist}\itemsep=0pt | |
115 | \twocolitem{\windowstyle{wxTREE\_EXPAND\_EXPAND}}{Expands the item.} | |
116 | \twocolitem{\windowstyle{wxTREE\_EXPAND\_COLLAPSE}}{Collapses the item.} | |
117 | \twocolitem{\windowstyle{wxTREE\_EXPAND\_COLLAPSE\_RESET}}{Collapses the item and removes the child items.} | |
118 | \twocolitem{\windowstyle{wxTREE\_EXPAND\_TOGGLE}}{Expands if the item is collapsed, collapses if the item is expanded.} | |
119 | \end{twocollist} | |
120 | ||
121 | \membersection{wxTreeCtrl::GetChild}\label{wxtreectrlgetchild} | |
122 | ||
123 | \constfunc{long}{GetChild}{\param{long }{item}} | |
124 | ||
125 | Call this function to retrieve the tree view item that is the first child of the item specified by {\it item}. | |
126 | ||
127 | \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount} | |
128 | ||
129 | \constfunc{int}{GetCount}{\void} | |
130 | ||
131 | Returns the number of items in the control. | |
132 | ||
133 | \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol} | |
134 | ||
135 | \constfunc{wxTextCtrl\&}{GetEditControl}{\void} | |
136 | ||
137 | Returns the edit control used to edit a label. | |
138 | ||
139 | \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem} | |
140 | ||
141 | \constfunc{long}{GetFirstVisibleItem}{\void} | |
142 | ||
143 | Returns the first visible item. | |
144 | ||
145 | \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist} | |
146 | ||
147 | \constfunc{wxImageList*}{GetImageList}{\param{int }{which = wxIMAGE\_LIST\_NORMAL}} | |
148 | ||
149 | Returns the specified image list. {\it which} may be one of: | |
150 | ||
151 | \twocolwidtha{5cm} | |
152 | \begin{twocollist}\itemsep=0pt | |
153 | \twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.} | |
154 | \twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.} | |
155 | \twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).} | |
156 | \end{twocollist} | |
157 | ||
158 | \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent} | |
159 | ||
160 | \constfunc{int}{GetIndent}{\void} | |
161 | ||
162 | Returns the current tree control indentation. | |
163 | ||
164 | \membersection{wxTreeCtrl::GetItem}\label{wxtreectrlgetitem} | |
165 | ||
166 | \constfunc{bool}{GetItem}{\param{wxTreeItem\& }{info}} | |
167 | ||
168 | Gets information about the item. See \helpref{wxTreeCtrl::SetItem}{wxtreectrlsetitem} for more | |
169 | information. | |
170 | ||
171 | \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata} | |
172 | ||
173 | \constfunc{long}{GetItemData}{\param{long }{item}} | |
174 | ||
175 | Returns the client data associated with the item, if any. | |
176 | ||
177 | \membersection{wxTreeCtrl::GetItemRect}\label{wxtreectrlgetitemrect} | |
178 | ||
179 | \constfunc{bool}{GetItemRect}{\param{long }{item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = FALSE}} | |
180 | ||
181 | Returns the position and size of the rectangle bounding the item. | |
182 | ||
183 | \membersection{wxTreeCtrl::GetItemState}\label{wxtreectrlgetitemstate} | |
184 | ||
185 | \constfunc{int}{GetItemState}{\param{long }{item}, \param{long }{stateMask}} | |
186 | ||
187 | Gets the item state. For a list of state flags, see \helpref{wxTreeCtrl::SetItem}{wxtreectrlsetitem}. | |
188 | ||
189 | \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext} | |
190 | ||
191 | \constfunc{wxString}{GetItemText}{\param{long }{item}} | |
192 | ||
193 | Returns the item label. | |
194 | ||
195 | \membersection{wxTreeCtrl::GetNextItem}\label{wxtreectrlgetnextitem} | |
196 | ||
197 | \constfunc{long}{GetNextItem}{\param{long }{item}, \param{int }{code}} | |
198 | ||
199 | Searches for an item using the given criterion, starting from {\it item}. | |
200 | ||
201 | Returns the item or 0 if unsuccessful. | |
202 | ||
203 | {\it code} can be one of: | |
204 | ||
205 | \twocolwidtha{5cm} | |
206 | \begin{twocollist}\itemsep=0pt | |
207 | \twocolitem{wxTREE\_NEXT\_CARET}{Retrieves the currently selected item.} | |
208 | \twocolitem{wxTREE\_NEXT\_CHILD}{Retrieves the first child item. The hItem parameter must be NULL.} | |
209 | \twocolitem{wxTREE\_NEXT\_DROPHILITE}{Retrieves the item that is the target of a drag-and-drop operation.} | |
210 | \twocolitem{wxTREE\_NEXT\_FIRSTVISIBLE}{Retrieves the first visible item.} | |
211 | \twocolitem{wxTREE\_NEXT\_NEXT}{Retrieves the next sibling item.} | |
212 | \twocolitem{wxTREE\_NEXT\_NEXTVISIBLE}{Retrieves the next visible item that follows the specified item.} | |
213 | \twocolitem{wxTREE\_NEXT\_PARENT}{Retrieves the parent of the specified item.} | |
214 | \twocolitem{wxTREE\_NEXT\_PREVIOUS}{Retrieves the previous sibling item.} | |
215 | \twocolitem{wxTREE\_NEXT\_PREVIOUSVISIBLE}{Retrieves the first visible item that precedes the specified item.} | |
216 | \twocolitem{wxTREE\_NEXT\_ROOT}{Retrieves the first child item of the root item of which the specified item is a part.} | |
217 | \end{twocollist} | |
218 | ||
219 | \membersection{wxTreeCtrl::GetNextVisibleItem}\label{wxtreectrlgetnextvisibleitem} | |
220 | ||
221 | \constfunc{long}{GetNextVisibleItem}{\param{long }{item}} | |
222 | ||
223 | Returns the next visible item. | |
224 | ||
225 | \membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent} | |
226 | ||
227 | \constfunc{long}{GetParent}{\param{long }{item}} | |
228 | ||
229 | Returns the item's parent. | |
230 | ||
231 | \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem} | |
232 | ||
233 | \constfunc{long}{GetRootItem}{\void} | |
234 | ||
235 | Returns the root item for the tree control. | |
236 | ||
237 | \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection} | |
238 | ||
239 | \constfunc{long}{GetSelection}{\void} | |
240 | ||
241 | Returns the selection, or 0 if there is no selection. | |
242 | ||
243 | \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest} | |
244 | ||
245 | \func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}} | |
246 | ||
247 | Calculates which (if any) item is under the given point, returning extra information | |
248 | in {\it flags}. {\it flags} is a bitlist of the following: | |
249 | ||
250 | \twocolwidtha{5cm} | |
251 | \begin{twocollist}\itemsep=0pt | |
252 | \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.} | |
253 | \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.} | |
254 | \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.} | |
255 | \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.} | |
256 | \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.} | |
257 | \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.} | |
258 | \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.} | |
259 | \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.} | |
260 | \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.} | |
261 | \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.} | |
262 | \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.} | |
263 | \end{twocollist} | |
264 | ||
265 | \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem} | |
266 | ||
267 | \func{long}{InsertItem}{\param{long }{parent}, \param{wxTreeItem\& }{info}, \param{long }{insertAfter = wxTREE\_INSERT\_LAST}} | |
268 | ||
269 | Inserts an item. For more information on {\it info}, see \helpref{wxTreeCtrl::SetItem}{wxtreectrlsetitem}. | |
270 | ||
271 | \func{long}{InsertItem}{\param{long }{parent}, \param{const wxString\& }{label}, \param{int }{image = -1}, \param{int }{selImage = -1}, \param{long }{insertAfter = wxTREE\_INSERT\_LAST}} | |
272 | ||
273 | Inserts an item. | |
274 | ||
275 | If {\it image} > -1 and {\it selImage} is -1, the same image is used for | |
276 | both selected and unselected items. | |
277 | ||
278 | \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren} | |
279 | ||
280 | \constfunc{bool}{ItemHasChildren}{\param{long }{item}} | |
281 | ||
282 | Returns TRUE if the item has children. | |
283 | ||
284 | \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto} | |
285 | ||
286 | \func{bool}{ScrollTo}{\param{long }{item}} | |
287 | ||
288 | selects the specified item and scrolls the item into view, | |
289 | ||
290 | \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem} | |
291 | ||
292 | \func{bool}{SelectItem}{\param{long }{item}} | |
293 | ||
294 | Selects the given item. | |
295 | ||
296 | \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent} | |
297 | ||
298 | \func{void}{SetIndent}{\param{int }{indent}} | |
299 | ||
300 | Sets the indentation for the tree control. | |
301 | ||
302 | \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist} | |
303 | ||
304 | \func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which = wxIMAGE\_LIST\_NORMAL}} | |
305 | ||
306 | Sets the image list. {\it which} should be one of wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL and | |
307 | wxIMAGE\_LIST\_STATE. | |
308 | ||
309 | \membersection{wxTreeCtrl::SetItem}\label{wxtreectrlsetitem} | |
310 | ||
311 | \func{bool}{SetItem}{\param{wxTreeItem\& }{info}} | |
312 | ||
313 | Sets the properties of the item. | |
314 | ||
315 | The members of wxTreeItem are as follows: | |
316 | ||
317 | \twocolwidtha{5cm} | |
318 | \begin{twocollist}\itemsep=0pt | |
319 | \twocolitem{m\_mask}{A bitlist specifying the valid members. See below for mask flags.} | |
320 | \twocolitem{m\_itemId}{The item identifier.} | |
321 | \twocolitem{m\_state}{The item state. See below for state flags.} | |
322 | \twocolitem{m\_stateMask}{A bitlist specifying the valid contents of {\it m\_state}. These flags | |
323 | are taken from the same set of symbols as {\it m\_state}.} | |
324 | \twocolitem{m\_text}{The item label.} | |
325 | \twocolitem{m\_image}{The item image index (an index into the appropriate image list).} | |
326 | \twocolitem{m\_selectedImage}{The item selected index (an index into the appropriate image list).} | |
327 | \twocolitem{m\_children}{The number of child items that this item has.} | |
328 | \twocolitem{m\_data}{The application-defined data associated with this item.} | |
329 | \end{twocollist} | |
330 | ||
331 | Valid mask flags are: | |
332 | ||
333 | \twocolwidtha{5cm} | |
334 | \begin{twocollist}\itemsep=0pt | |
335 | \twocolitem{wxTREE\_MASK\_HANDLE}{The {\it m\_itemId} member is valid.} | |
336 | \twocolitem{wxTREE\_MASK\_STATE}{The {\it m\_state} member is valid.} | |
337 | \twocolitem{wxTREE\_MASK\_TEXT}{The {\it m\_text} member is valid.} | |
338 | \twocolitem{wxTREE\_MASK\_IMAGE}{The {\it m\_image} member is valid.} | |
339 | \twocolitem{wxTREE\_MASK\_SELECTED\_IMAGE}{The {\it m\_selectedImage} member is valid.} | |
340 | \twocolitem{wxTREE\_MASK\_CHILDREN}{The {\it m\_children} member is valid.} | |
341 | \twocolitem{wxTREE\_MASK\_DATA}{The {\it m\_data} member is valid.} | |
342 | \end{twocollist} | |
343 | ||
344 | Valid state and state mask flags are: | |
345 | ||
346 | \twocolwidtha{5cm} | |
347 | \begin{twocollist}\itemsep=0pt | |
348 | \twocolitem{wxTREE\_STATE\_BOLD}{The label is emboldened.} | |
349 | \twocolitem{wxTREE\_STATE\_DROPHILITED}{The item indicates it is a drop target.} | |
350 | \twocolitem{wxTREE\_STATE\_EXPANDED}{The item is expanded.} | |
351 | \twocolitem{wxTREE\_STATE\_EXPANDEDONCE}{The item's list of child items has been expanded at least once.} | |
352 | \twocolitem{wxTREE\_STATE\_FOCUSED}{The item has the focus, so it is surrounded by a standard focus rectangle. | |
353 | Only one item can have the focus.} | |
354 | \twocolitem{wxTREE\_STATE\_SELECTED}{The item is selected.} | |
355 | \twocolitem{wxTREE\_STATE\_CUT}{The item is selected as part of a cut and paste operation.} | |
356 | \end{twocollist} | |
357 | ||
358 | \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage} | |
359 | ||
360 | \func{bool}{SetItemImage}{\param{long }{item}, \param{int }{image}, \param{int }{selImage}} | |
361 | ||
362 | Sets the item image and selected image. These are indices into the assciated image list. | |
363 | ||
364 | \membersection{wxTreeCtrl::SetItemState}\label{wxtreectrlsetitemstate} | |
365 | ||
366 | \func{bool}{SetItemState}{\param{long }{item}, \param{long }{state}, \param{long }{stateMask}} | |
367 | ||
368 | Sets the item state. See \helpref{wxTreeCtrl::SetItem}{wxtreectrlsetitem} for valid state and state mask flags. | |
369 | ||
370 | \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext} | |
371 | ||
372 | \func{void}{SetItemText}{\param{long }{item}, \param{const wxString\& }{text}} | |
373 | ||
374 | Sets the item label. | |
375 | ||
376 | \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata} | |
377 | ||
378 | \func{bool}{SetItemData}{\param{long }{item}, \param{long }{data}} | |
379 | ||
380 | Sets the item client data. | |
381 | ||
382 | \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren} | |
383 | ||
384 | \func{bool}{SortChildren}{\param{long }{item}} | |
385 | ||
386 | Sorts the children of the given item in ascending alphabetical order. | |
387 |