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