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