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