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{long}{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 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 453
 454 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 455  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 456
 457 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 458  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 459
 460 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 461
 462 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 463 both selected and unselected items.
 464
 465 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 466
 467 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 468
 469 Returns TRUE if the given item is in bold state.
 470
 471 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 472
 473 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 474
 475 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 476
 477 Returns TRUE if the item is expanded (only makes sense if it has children).
 478
 479 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 480
 481 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 482
 483 Returns TRUE if the item is selected.
 484
 485 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 486
 487 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 488
 489 Returns TRUE if the item is visible (it might be outside the view, or not expanded).
 490
 491 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 492
 493 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 494
 495 Returns TRUE if the item has children.
 496
 497 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 498
 499 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 500
 501 Override this function in the derived class to change the sort order of the
 502 items in the tree control. The function should return a negative, zero or
 503 positive value if the first item is less than, equal to or greater than the
 504 second one.
 505
 506 The base class version compares items alphabetically.
 507
 508 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 509
 510 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 511
 512 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 513  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}
 514
 515 Appends an item as the first child of {\it parent}, return a new item id.
 516
 517 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 518 both selected and unselected items.
 519
 520 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 521
 522 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 523
 524 Scrolls the specified item into view.
 525
 526 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 527
 528 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}}
 529
 530 Selects the given item.
 531
 532 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 533
 534 \func{void}{SetIndent}{\param{int }{indent}}
 535
 536 Sets the indentation for the tree control.
 537
 538 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 539
 540 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 541
 542 Sets the normal image list.
 543
 544 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 545
 546 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 547
 548 Sets the colour of the items background.
 549
 550 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 551
 552 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = TRUE}}
 553
 554 Makes item appear in bold font if {\it bold} parameter is TRUE or resets it to
 555 the normal state.
 556
 557 See also: \helpref{IsBold}{wxtreectrlisbold}
 558
 559 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 560
 561 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 562
 563 Sets the item client data.
 564
 565 \pythonnote{wxPython provides the following shortcut method:\par
 566 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 567 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 568 Object with the wxTreeItemData for the given item Id.}
 569 \end{twocollist}}
 570 }
 571
 572 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 573
 574 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 575
 576 Sets the items font. All items in the tree should have the same height to avoid
 577 text clipping, so the fonts height should be the same for all of them,
 578 although font attributes may vary.
 579
 580 \wxheading{See also}
 581
 582 \helpref{SetItemBold}{wxtreectrlsetitembold}
 583
 584 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 585
 586 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = TRUE}}
 587
 588 Force appearance of the button next to the item. This is useful to
 589 allow the user to expand the items which don't have any children now,
 590 but instead adding them only when needed, thus minimizing memory
 591 usage and loading time.
 592
 593 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 594
 595 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 596  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 597
 598 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 599 for the description of {\it which} parameter.
 600
 601 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 602
 603 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 604
 605 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected} instead).
 606
 607 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 608
 609 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 610
 611 Sets the item label.
 612
 613 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 614
 615 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 616
 617 Sets the colour of the items text.
 618
 619 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 620
 621 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 622
 623 Sets the state image list (from which application-defined state images are taken).
 624
 625 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 626
 627 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 628
 629 Sorts the children of the given item using
 630 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 631 should override that method to change the sort order (default is ascending
 632 alphabetical order).
 633
 634 \wxheading{See also}
 635
 636 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 637
 638 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 639
 640 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 641
 642 Toggles the given item between collapsed and expanded states.
 643
 644 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 645
 646 \func{void}{Unselect}{\void}
 647
 648 Removes the selection from the currently selected item (if any).
 649
 650 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 651
 652 \func{void}{UnselectAll}{\void}
 653
 654 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 655 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 656 all items if it does have this style.
 657
 658 \section{\class{wxTreeItemData}}\label{wxtreeitemdata}
 659
 660 wxTreeItemData is some (arbitrary) user class associated with some item. The
 661 main advantage of having this class (compared to the old untyped interface) is
 662 that wxTreeItemData's are destroyed automatically by the tree and, as this
 663 class has virtual dtor, it means that the memory will be automatically
 664 freed. We don't just use wxObject instead of wxTreeItemData because
 665 the size of this class is critical: in any real application, each tree leaf
 666 will have wxTreeItemData associated with it and number of leaves may be
 667 quite big.
 668
 669 Because the objects of this class are deleted by the tree, they should
 670 always be allocated on the heap.
 671
 672 \wxheading{Derived from}
 673
 674 wxTreeItemId
 675
 676 \wxheading{Include files}
 677
 678 <wx/treectrl.h>
 679
 680 \wxheading{See also}
 681
 682 \helpref{wxTreeCtrl}{wxtreectrl}
 683
 684 \latexignore{\rtfignore{\wxheading{Members}}}
 685
 686 \membersection{wxTreeItemData::wxTreeItemData}\label{wxtreeitemdataconstr}
 687
 688 \func{}{wxTreeItemData}{\void}
 689
 690 Default constructor.
 691
 692 \pythonnote{The wxPython version of this constructor optionally
 693 accepts any Python object as a parameter.  This object is then
 694 associated with the tree item using the wxTreeItemData as a
 695 container.
 696
 697 In addition, the following methods are added in wxPython for accessing
 698 the object:
 699
 700 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 701 \twocolitem{{\bf GetData()}}{Returns a reference to the Python Object}
 702 \twocolitem{{\bf SetData(obj)}}{Associates a new Python Object with the
 703 wxTreeItemData}
 704 \end{twocollist}}
 705 }
 706
 707
 708 \membersection{wxTreeItemData::\destruct{wxTreeItemData}}
 709
 710 \func{void}{\destruct{wxTreeItemData}}{\void}
 711
 712 Virtual destructor.
 713
 714 \membersection{wxTreeItemData::GetId}\label{wxtreeitemdatagetid}
 715
 716 \func{const wxTreeItem\&}{GetId}{\void}
 717
 718 Returns the item associated with this node.
 719
 720 \membersection{wxTreeItemData::SetId}\label{wxtreeitemdatasetid}
 721
 722 \func{void}{SetId}{\param{const wxTreeItemId\&}{ id}}
 723
 724 Sets the item associated with this node.
 725