docs/latex/wx/treectrl.tex

   1 \section{\class{wxTreeCtrl}}\label{wxtreectrl}
   2
   3 A tree control presents information as a hierarchy, with items that may be expanded
   4 to show further items. Items in a tree control are referenced by wxTreeItemId handles.
   5
   6 To intercept events from a tree control, use the event table macros described in \helpref{wxTreeEvent}{wxtreeevent}.
   7
   8 \wxheading{Derived from}
   9
  10 \helpref{wxControl}{wxcontrol}\\
  11 \helpref{wxWindow}{wxwindow}\\
  12 \helpref{wxEvtHandler}{wxevthandler}\\
  13 \helpref{wxObject}{wxobject}
  14
  15 \wxheading{Include files}
  16
  17 <wx/treectrl.h>
  18
  19 \wxheading{Window styles}
  20
  21 \twocolwidtha{5cm}
  22 \begin{twocollist}\itemsep=0pt
  23 \twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style to show + and - buttons to the
  24 left of parent items. Win32 only. }
  25 \twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style if you wish the user to be
  26 able to edit labels in the tree control.}
  27 \twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style to allow the user to
  28 select more than one item in the control - by default, only one item may be
  29 selected.}
  30 \end{twocollist}
  31
  32 See also \helpref{window styles overview}{windowstyles}.
  33
  34 \wxheading{Event handling}
  35
  36 To process input from a tree control, use these event handler macros to direct input to member
  37 functions that take a \helpref{wxTreeEvent}{wxtreeevent} argument.
  38
  39 \twocolwidtha{7cm}
  40 \begin{twocollist}\itemsep=0pt
  41 \twocolitem{{\bf EVT\_TREE\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
  42 \twocolitem{{\bf EVT\_TREE\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
  43 \twocolitem{{\bf EVT\_TREE\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  44 \twocolitem{{\bf EVT\_TREE\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  45 \twocolitem{{\bf EVT\_TREE\_DELETE\_ITEM(id, func)}}{Delete an item.}
  46 \twocolitem{{\bf EVT\_TREE\_GET\_INFO(id, func)}}{Request information from the application.}
  47 \twocolitem{{\bf EVT\_TREE\_SET\_INFO(id, func)}}{Information is being supplied.}
  48 \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}
  49 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSED(id, func)}}{Parent has been collapsed.}
  50 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSING(id, func)}}{Parent is being collapsed. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  51 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{Parent has been expanded.}
  52 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{Parent is being expanded. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  53 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGED(id, func)}}{Selection has changed.}
  54 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGING(id, func)}}{Selection is changing. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  55 \twocolitem{{\bf EVT\_TREE\_KEY\_DOWN(id, func)}}{A key has been pressed.}
  56 \end{twocollist}%
  57
  58 \wxheading{See also}
  59
  60 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp
  61 \helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent}
  62
  63 \latexignore{\rtfignore{\wxheading{Members}}}
  64
  65 \membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr}
  66
  67 \func{}{wxTreeCtrl}{\void}
  68
  69 Default constructor.
  70
  71 \func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  72 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  73 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
  74
  75 Constructor, creating and showing a tree control.
  76
  77 \wxheading{Parameters}
  78
  79 \docparam{parent}{Parent window. Must not be NULL.}
  80
  81 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  82
  83 \docparam{pos}{Window position.}
  84
  85 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
  86 appropriately.}
  87
  88 \docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.}
  89
  90 \docparam{validator}{Window validator.}
  91
  92 \docparam{name}{Window name.}
  93
  94 \wxheading{See also}
  95
  96 \helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator}
  97
  98 \membersection{wxTreeCtrl::\destruct{wxTreeCtrl}}
  99
 100 \func{void}{\destruct{wxTreeCtrl}}{\void}
 101
 102 Destructor, destroying the list control.
 103
 104 \membersection{wxTreeCtrl::AddRoot}\label{wxtreectrladdroot}
 105
 106 \func{wxTreeItemId}{AddRoot}{\param{const wxString\&}{ text},
 107  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 108
 109 Adds the root node to the tree, returning the new item.
 110
 111 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 112 both selected and unselected items.
 113
 114 \membersection{wxTreeCtrl::AppendItem}\label{wxtreectrlappenditem}
 115
 116 \func{wxTreeItemId}{AppendItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 117  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 118
 119 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
 120
 121 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 122 both selected and unselected items.
 123
 124 \membersection{wxTreeCtrl::Collapse}\label{wxtreectrlcollapse}
 125
 126 \func{void}{Collapse}{\param{const wxTreeItemId\&}{ item}}
 127
 128 Collapses the given item.
 129
 130 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
 131
 132 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}
 133
 134 Collapses the given item and removes all children.
 135
 136 \membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate}
 137
 138 \func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 139 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 140 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 141
 142 Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details.
 143
 144 \membersection{wxTreeCtrl::Delete}\label{wxtreectrldelete}
 145
 146 \func{void}{Delete}{\param{const wxTreeItemId\&}{ item}}
 147
 148 Deletes the specified item.
 149
 150 \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems}
 151
 152 \func{void}{DeleteAllItems}{\void}
 153
 154 Deletes all the items in the control.
 155
 156 \membersection{wxTreeCtrl::EditLabel}\label{wxtreectrleditlabel}
 157
 158 \func{void}{EditLabel}{\param{const wxTreeItemId\&}{ item}}
 159
 160 Starts editing the label of the given item. This function generates a
 161 EVT\_TREE\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
 162 text control will appear for in-place editing.
 163
 164 If the user changed the label (i.e. s/he does not press ESC or leave
 165 the text control without changes, a EVT\_TREE\_END\_LABEL\_EDIT event
 166 will be sent which can be vetoed as well.
 167
 168 \wxheading{See also}
 169
 170 \helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel},
 171 \helpref{wxTreeEvent}{wxtreeevent}
 172
 173 \membersection{wxTreeCtrl::EndEditLabel}\label{wxtreectrlendeditlabel}
 174
 175 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
 176
 177 Ends label editing. If {\it cancelEdit} is TRUE, the edit will be cancelled.
 178
 179 This function is currently supported under Windows only.
 180
 181 \wxheading{See also}
 182
 183 \helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}
 184
 185 \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible}
 186
 187 \func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}}
 188
 189 Scrolls and/or expands items to ensure that the given item is visible.
 190
 191 \membersection{wxTreeCtrl::Expand}\label{wxtreectrlexpand}
 192
 193 \func{void}{Expand}{\param{const wxTreeItemId\&}{ item}}
 194
 195 Expands the given item.
 196
 197 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
 198
 199 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = FALSE}}
 200
 201 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is TRUE,
 202 only the rectangle around the items label will be returned, otherwise the
 203 items image is also taken into account.
 204
 205 The return value is TRUE if the rectangle was successfully retrieved or FALSE
 206 if it was not (in this case {\it rect} is not changed) - for example, if the
 207 item is currently invisible.
 208
 209 \pythonnote{The wxPython version of this method requires only the
 210 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 211 {\tt wxRect} object or {\tt None}.}
 212
 213 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 214
 215 \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = TRUE}}
 216
 217 Returns the number of items in the branch. If {\it recursively} is TRUE, returns the total number
 218 of descendants, otherwise only one level of children is counted.
 219
 220 \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
 221
 222 \constfunc{int}{GetCount}{\void}
 223
 224 Returns the number of items in the control.
 225
 226 \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
 227
 228 \constfunc{wxTextCtrl\&}{GetEditControl}{\void}
 229
 230 Returns the edit control used to edit a label.
 231
 232 \membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
 233
 234 \constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}}
 235
 236 Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
 237
 238 For this enumeration function you must pass in a `cookie' parameter
 239 which is opaque for the application but is necessary for the library
 240 to make these functions reentrant (i.e. allow more than one
 241 enumeration on one and the same object simultaneously). The cookie passed to
 242 GetFirstChild and GetNextChild should be the same.
 243
 244 Returns an invalid tree item if there are no further children.
 245
 246 \wxheading{See also}
 247
 248 \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild}
 249
 250 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 251 value are both returned as a tuple containing the two values.}
 252
 253 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 254
 255 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
 256
 257 Returns the first visible item.
 258
 259 \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
 260
 261 \constfunc{wxImageList*}{GetImageList}{\void}
 262
 263 Returns the normal image list.
 264
 265 \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
 266
 267 \constfunc{int}{GetIndent}{\void}
 268
 269 Returns the current tree control indentation.
 270
 271 \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
 272
 273 \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
 274
 275 Returns the tree item data associated with the item.
 276
 277 \wxheading{See also}
 278
 279 \helpref{wxTreeItemData}{wxtreeitemdata}
 280
 281 \pythonnote{wxPython provides the following shortcut method:
 282
 283 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 284 \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
 285 associated with the wxTreeItemData for the given item Id.}
 286 \end{twocollist}}
 287 }
 288
 289 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 290
 291 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
 292  \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 293
 294 Gets the specified item image. The value of {\it which} may be:
 295
 296 \begin{itemize}\itemsep=0pt
 297 \item{wxTreeItemIcon\_Normal} to get the normal item image
 298 \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
 299 which is shown when the item is currently selected)
 300 \item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
 301 makes sense for items which have children - then this image is shown when the
 302 item is expanded and the normal image is shown when it is collapsed)
 303 \item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
 304 (which is shown when an expanded item is currently selected)
 305 \end{itemize}
 306
 307 \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
 308
 309 \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
 310
 311 Returns the item label.
 312
 313 \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
 314
 315 \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
 316
 317 Returns the last child of the item (or an invalid tree item if this item has no children).
 318
 319 \wxheading{See also}
 320
 321 \helpref{GetFirstChild}{wxtreectrlgetfirstchild},
 322 \helpref{GetLastChild}{wxtreectrlgetlastchild}
 323
 324 \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
 325
 326 \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}}
 327
 328 Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
 329
 330 For this enumeration function you must pass in a `cookie' parameter
 331 which is opaque for the application but is necessary for the library
 332 to make these functions reentrant (i.e. allow more than one
 333 enumeration on one and the same object simultaneously). The cookie passed to
 334 GetFirstChild and GetNextChild should be the same.
 335
 336 Returns an invalid tree item if there are no further children.
 337
 338 \wxheading{See also}
 339
 340 \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
 341
 342 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 343 value are both returned as a tuple containing the two values.}
 344
 345 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 346
 347 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
 348
 349 Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
 350
 351 Returns an invalid tree item if there are no further siblings.
 352
 353 \wxheading{See also}
 354
 355 \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
 356
 357 \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
 358
 359 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 360
 361 Returns the next visible item.
 362
 363 \membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent}
 364
 365 \constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}
 366
 367 Returns the item's parent.
 368
 369 \pythonnote{This method is named {\tt GetItemParent} to avoid a name
 370 clash with wxWindow::GetParent.}
 371
 372 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
 373
 374 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
 375
 376 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
 377
 378 Returns an invalid tree item if there are no further children.
 379
 380 \wxheading{See also}
 381
 382 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 383
 384 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
 385
 386 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 387
 388 Returns the previous visible item.
 389
 390 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
 391
 392 \constfunc{wxTreeItemId}{GetRootItem}{\void}
 393
 394 Returns the root item for the tree control.
 395
 396 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
 397
 398 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 399
 400 Gets the selected item image (this function is obsolete, use
 401 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 402
 403 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
 404
 405 \constfunc{wxTreeItemId}{GetSelection}{\void}
 406
 407 Returns the selection, or an invalid item if there is no selection.
 408 This function only works with the controls without wxTR\_MULTIPLE style, use
 409 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
 410 this style.
 411
 412 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
 413
 414 \constfunc{size\_t}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
 415
 416 Fills the array of tree items passed in with the currently selected items. This
 417 function can be called only if the control has the wxTR\_MULTIPLE style.
 418
 419 Returns the number of selected items.
 420
 421 \pythonnote{The wxPython version of this method accepts no parameters
 422 and returns a Python list of {\tt wxTreeItemId}s.}
 423
 424 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 425
 426 \constfunc{wxImageList*}{GetStateImageList}{\void}
 427
 428 Returns the state image list (from which application-defined state images are taken).
 429
 430 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
 431
 432 \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 433
 434 Calculates which (if any) item is under the given point, returning extra information
 435 in {\it flags}. {\it flags} is a bitlist of the following:
 436
 437 \twocolwidtha{5cm}
 438 \begin{twocollist}\itemsep=0pt
 439 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
 440 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
 441 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 442 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
 443 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 444 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
 445 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 446 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 447 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 448 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
 449 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
 450 \end{twocollist}
 451
 452 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 453 returned as a tuple.}
 454
 455 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 456
 457 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 458  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 459
 460 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 461  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 462
 463 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 464
 465 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 466 both selected and unselected items.
 467
 468 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 469
 470 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 471
 472 Returns TRUE if the given item is in bold state.
 473
 474 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 475
 476 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 477
 478 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 479
 480 Returns TRUE if the item is expanded (only makes sense if it has children).
 481
 482 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 483
 484 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 485
 486 Returns TRUE if the item is selected.
 487
 488 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 489
 490 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 491
 492 Returns TRUE if the item is visible (it might be outside the view, or not expanded).
 493
 494 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 495
 496 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 497
 498 Returns TRUE if the item has children.
 499
 500 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 501
 502 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 503
 504 Override this function in the derived class to change the sort order of the
 505 items in the tree control. The function should return a negative, zero or
 506 positive value if the first item is less than, equal to or greater than the
 507 second one.
 508
 509 The base class version compares items alphabetically.
 510
 511 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 512
 513 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 514
 515 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 516  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 517
 518 Appends an item as the first child of {\it parent}, return a new item id.
 519
 520 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 521 both selected and unselected items.
 522
 523 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 524
 525 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 526
 527 Scrolls the specified item into view.
 528
 529 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 530
 531 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}}
 532
 533 Selects the given item.
 534
 535 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 536
 537 \func{void}{SetIndent}{\param{int }{indent}}
 538
 539 Sets the indentation for the tree control.
 540
 541 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 542
 543 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 544
 545 Sets the normal image list.
 546
 547 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 548
 549 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 550
 551 Sets the colour of the items background.
 552
 553 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 554
 555 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = TRUE}}
 556
 557 Makes item appear in bold font if {\it bold} parameter is TRUE or resets it to
 558 the normal state.
 559
 560 See also: \helpref{IsBold}{wxtreectrlisbold}
 561
 562 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 563
 564 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 565
 566 Sets the item client data.
 567
 568 \pythonnote{wxPython provides the following shortcut method:\par
 569 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 570 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 571 Object with the wxTreeItemData for the given item Id.}
 572 \end{twocollist}}
 573 }
 574
 575 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 576
 577 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 578
 579 Sets the items font. All items in the tree should have the same height to avoid
 580 text clipping, so the fonts height should be the same for all of them,
 581 although font attributes may vary.
 582
 583 \wxheading{See also}
 584
 585 \helpref{SetItemBold}{wxtreectrlsetitembold}
 586
 587 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 588
 589 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = TRUE}}
 590
 591 Force appearance of the button next to the item. This is useful to
 592 allow the user to expand the items which don't have any children now,
 593 but instead adding them only when needed, thus minimizing memory
 594 usage and loading time.
 595
 596 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 597
 598 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 599  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 600
 601 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 602 for the description of the {\it which} parameter.
 603
 604 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 605
 606 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 607
 608 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 609
 610 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 611
 612 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 613
 614 Sets the item label.
 615
 616 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 617
 618 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 619
 620 Sets the colour of the items text.
 621
 622 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 623
 624 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 625
 626 Sets the state image list (from which application-defined state images are taken).
 627
 628 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 629
 630 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 631
 632 Sorts the children of the given item using
 633 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 634 should override that method to change the sort order (the default is ascending
 635 alphabetical order).
 636
 637 \wxheading{See also}
 638
 639 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 640
 641 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 642
 643 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 644
 645 Toggles the given item between collapsed and expanded states.
 646
 647 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 648
 649 \func{void}{Unselect}{\void}
 650
 651 Removes the selection from the currently selected item (if any).
 652
 653 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 654
 655 \func{void}{UnselectAll}{\void}
 656
 657 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 658 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 659 all items if it does have this style.
 660
 661 \section{\class{wxTreeItemData}}\label{wxtreeitemdata}
 662
 663 wxTreeItemData is some (arbitrary) user class associated with some item. The
 664 main advantage of having this class (compared to the old untyped interface) is
 665 that wxTreeItemData's are destroyed automatically by the tree and, as this
 666 class has virtual dtor, it means that the memory will be automatically
 667 freed. We don't just use wxObject instead of wxTreeItemData because
 668 the size of this class is critical: in any real application, each tree leaf
 669 will have wxTreeItemData associated with it and number of leaves may be
 670 quite big.
 671
 672 Because the objects of this class are deleted by the tree, they should
 673 always be allocated on the heap.
 674
 675 \wxheading{Derived from}
 676
 677 wxTreeItemId
 678
 679 \wxheading{Include files}
 680
 681 <wx/treectrl.h>
 682
 683 \wxheading{See also}
 684
 685 \helpref{wxTreeCtrl}{wxtreectrl}
 686
 687 \latexignore{\rtfignore{\wxheading{Members}}}
 688
 689 \membersection{wxTreeItemData::wxTreeItemData}\label{wxtreeitemdataconstr}
 690
 691 \func{}{wxTreeItemData}{\void}
 692
 693 Default constructor.
 694
 695 \pythonnote{The wxPython version of this constructor optionally
 696 accepts any Python object as a parameter.  This object is then
 697 associated with the tree item using the wxTreeItemData as a
 698 container.
 699
 700 In addition, the following methods are added in wxPython for accessing
 701 the object:
 702
 703 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 704 \twocolitem{{\bf GetData()}}{Returns a reference to the Python Object}
 705 \twocolitem{{\bf SetData(obj)}}{Associates a new Python Object with the
 706 wxTreeItemData}
 707 \end{twocollist}}
 708 }
 709
 710
 711 \membersection{wxTreeItemData::\destruct{wxTreeItemData}}
 712
 713 \func{void}{\destruct{wxTreeItemData}}{\void}
 714
 715 Virtual destructor.
 716
 717 \membersection{wxTreeItemData::GetId}\label{wxtreeitemdatagetid}
 718
 719 \func{const wxTreeItem\&}{GetId}{\void}
 720
 721 Returns the item associated with this node.
 722
 723 \membersection{wxTreeItemData::SetId}\label{wxtreeitemdatasetid}
 724
 725 \func{void}{SetId}{\param{const wxTreeItemId\&}{ id}}
 726
 727 Sets the item associated with this node.
 728