docs/latex/wx/treectrl.tex

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