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