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