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