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 which may be tested for validity by calling wxTreeItemId::IsOk.
   6
   7 To intercept events from a tree control, use the event table macros described in \helpref{wxTreeEvent}{wxtreeevent}.
   8
   9 \wxheading{Derived from}
  10
  11 \helpref{wxControl}{wxcontrol}\\
  12 \helpref{wxWindow}{wxwindow}\\
  13 \helpref{wxEvtHandler}{wxevthandler}\\
  14 \helpref{wxObject}{wxobject}
  15
  16 \wxheading{Include files}
  17
  18 <wx/treectrl.h>
  19
  20 \wxheading{Window styles}
  21
  22 \twocolwidtha{5cm}
  23 \begin{twocollist}\itemsep=0pt
  24 \twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style
  25 if you wish the user to be able to edit labels in the tree control.}
  26 \twocolitem{\windowstyle{wxTR\_NO\_BUTTONS}}{For convenience
  27 to document that no buttons are to be drawn.}
  28 \twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style
  29 to show + and - buttons to the left of parent items.}
  30 \twocolitem{\windowstyle{wxTR\_TWIST\_BUTTONS}}{Use this style
  31 to show Mac-style twister buttons to the left of parent items.
  32 If both wxTR\_HAS\_BUTTONS and wxTR\_TWIST\_BUTTONS are given,
  33 twister buttons are generated.  Generic only.}
  34 \twocolitem{\windowstyle{wxTR\_NO\_LINES}}{Use this style
  35 to hide vertical level connectors.}
  36 \twocolitem{\windowstyle{wxTR\_FULL\_ROW\_HIGHLIGHT}}{Use this style to have the background
  37 colour and the selection highlight extend over the entire horizontal
  38 row of the tree control window. (This flag is ignored under Windows unless you
  39 specify wxTR\_NO\_LINES as well.) }
  40 \twocolitem{\windowstyle{wxTR\_LINES\_AT\_ROOT}}{Use this style
  41 to show lines between root nodes.
  42 Only applicable if wxTR\_HIDE\_ROOT is set and wxTR\_NO\_LINES is not set.}
  43 \twocolitem{\windowstyle{wxTR\_HIDE\_ROOT}}{Use this style
  44 to suppress the display of the root node,
  45 effectively causing the first-level nodes
  46 to appear as a series of root nodes.}
  47 \twocolitem{\windowstyle{wxTR\_ROW\_LINES}}{Use this style
  48 to draw a contrasting border between displayed rows.}
  49 \twocolitem{\windowstyle{wxTR\_HAS\_VARIABLE\_ROW\_HEIGHT}}{Use this style
  50 to cause row heights to be just big enough to fit the content.
  51 If not set, all rows use the largest row height.
  52 The default is that this flag is unset.
  53 Generic only.}
  54 \twocolitem{\windowstyle{wxTR\_SINGLE}}{For convenience
  55 to document that only one item may be selected at a time.
  56 Selecting another item causes the current selection, if any,
  57 to be deselected.  This is the default.}
  58 \twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style
  59 to allow a range of items to be selected.
  60 If a second range is selected, the current range, if any, is deselected.}
  61 \twocolitem{\windowstyle{wxTR\_EXTENDED}}{Use this style
  62 to allow disjoint items to be selected.  (Only partially implemented; may not work in all cases.)}
  63 \twocolitem{\windowstyle{wxTR\_DEFAULT\_STYLE}}{The set of flags that are
  64 closest to the defaults for the native control for a particular toolkit.}
  65 \end{twocollist}
  66
  67 See also \helpref{window styles overview}{windowstyles}.
  68
  69 \wxheading{Event handling}
  70
  71 To process input from a tree control, use these event handler macros to direct input to member
  72 functions that take a \helpref{wxTreeEvent}{wxtreeevent} argument.
  73
  74 \twocolwidtha{7cm}
  75 \begin{twocollist}\itemsep=0pt
  76 \twocolitem{{\bf EVT\_TREE\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
  77 \twocolitem{{\bf EVT\_TREE\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
  78 \twocolitem{{\bf EVT\_TREE\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  79 \twocolitem{{\bf EVT\_TREE\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  80 \twocolitem{{\bf EVT\_TREE\_DELETE\_ITEM(id, func)}}{Delete an item.}
  81 \twocolitem{{\bf EVT\_TREE\_GET\_INFO(id, func)}}{Request information from the application.}
  82 \twocolitem{{\bf EVT\_TREE\_SET\_INFO(id, func)}}{Information is being supplied.}
  83 \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}
  84 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSED(id, func)}}{The item has been collapsed.}
  85 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSING(id, func)}}{The item is being collapsed. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  86 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{The item has been expanded.}
  87 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{The item is being expanded. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  88 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGED(id, func)}}{Selection has changed.}
  89 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGING(id, func)}}{Selection is changing. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  90 \twocolitem{{\bf EVT\_TREE\_KEY\_DOWN(id, func)}}{A key has been pressed.}
  91 \twocolitem{{\bf EVT\_TREE\_ITEM\_GETTOOLTIP(id, func)}}{The opportunity to set the item tooltip
  92 is being given to the application (call wxTreeEvent::SetToolTip). Windows only.}
  93 \end{twocollist}
  94
  95 \wxheading{See also}
  96
  97 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp
  98 \helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent}
  99
 100 \wxheading{Win32 notes}
 101
 102 wxTreeCtrl class uses the standard common treeview control under Win32
 103 implemented in the system library {\tt comctl32.dll}. Some versions of this
 104 library are known to have bugs with handling the tree control colours: the
 105 usual symptom is that the expanded items leave black (or otherwise incorrectly
 106 coloured) background behind them, especially for the controls using non
 107 default background colour. The recommended solution is to upgrade the {\tt comctl32.dll}
 108 to a newer version: see
 109 \urlref{http://www.microsoft.com/msdownload/ieplatform/ie/comctrlx86.asp}{http://www.microsoft.com/msdownload/ieplatform/ie/comctrlx86.asp}.
 110
 111 \latexignore{\rtfignore{\wxheading{Members}}}
 112
 113 \membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr}
 114
 115 \func{}{wxTreeCtrl}{\void}
 116
 117 Default constructor.
 118
 119 \func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 120 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 121 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 122
 123 Constructor, creating and showing a tree control.
 124
 125 \wxheading{Parameters}
 126
 127 \docparam{parent}{Parent window. Must not be {\tt NULL}.}
 128
 129 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
 130
 131 \docparam{pos}{Window position.}
 132
 133 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 134 appropriately.}
 135
 136 \docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.}
 137
 138 \docparam{validator}{Window validator.}
 139
 140 \docparam{name}{Window name.}
 141
 142 \wxheading{See also}
 143
 144 \helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator}
 145
 146 \membersection{wxTreeCtrl::\destruct{wxTreeCtrl}}
 147
 148 \func{void}{\destruct{wxTreeCtrl}}{\void}
 149
 150 Destructor, destroying the list control.
 151
 152 \membersection{wxTreeCtrl::AddRoot}\label{wxtreectrladdroot}
 153
 154 \func{wxTreeItemId}{AddRoot}{\param{const wxString\&}{ text},
 155  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 156
 157 Adds the root node to the tree, returning the new item.
 158
 159 The {\it image} and {\it selImage} parameters are an index within
 160 the normal image list specifying the image to use for unselected and
 161 selected items, respectively.
 162 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 163 both selected and unselected items.
 164
 165 \membersection{wxTreeCtrl::AppendItem}\label{wxtreectrlappenditem}
 166
 167 \func{wxTreeItemId}{AppendItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 168  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 169
 170 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
 171
 172 The {\it image} and {\it selImage} parameters are an index within
 173 the normal image list specifying the image to use for unselected and
 174 selected items, respectively.
 175 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 176 both selected and unselected items.
 177
 178 \membersection{wxTreeCtrl::AssignButtonsImageList}\label{wxtreectrlassignbuttonsimagelist}
 179
 180 \func{void}{AssignButtonsImageList}{\param{wxImageList*}{ imageList}}
 181
 182 Sets the buttons image list. The button images assigned with this method will
 183 be automatically deleted by wxTreeCtrl as appropriate
 184 (i.e. it takes ownership of the list).
 185
 186 Setting or assigning the button image list enables the display of image buttons.
 187 Once enabled, the only way to disable the display of button images is to set
 188 the button image list to {\tt NULL}.
 189
 190 This function is only available in the generic version.
 191
 192 See also \helpref{SetButtonsImageList}{wxtreectrlsetbuttonsimagelist}.
 193
 194 \membersection{wxTreeCtrl::AssignImageList}\label{wxtreectrlassignimagelist}
 195
 196 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
 197
 198 Sets the normal image list. Image list assigned with this method will
 199 be automatically deleted by wxTreeCtrl as appropriate
 200 (i.e. it takes ownership of the list).
 201
 202 See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 203
 204 \membersection{wxTreeCtrl::AssignStateImageList}\label{wxtreectrlassignstateimagelist}
 205
 206 \func{void}{AssignStateImageList}{\param{wxImageList*}{ imageList}}
 207
 208 Sets the state image list. Image list assigned with this method will
 209 be automatically deleted by wxTreeCtrl as appropriate
 210 (i.e. it takes ownership of the list).
 211
 212 See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
 213
 214
 215 \membersection{wxTreeCtrl::Collapse}\label{wxtreectrlcollapse}
 216
 217 \func{void}{Collapse}{\param{const wxTreeItemId\&}{ item}}
 218
 219 Collapses the given item.
 220
 221 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
 222
 223 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}
 224
 225 Collapses the given item and removes all children.
 226
 227 \membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate}
 228
 229 \func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 230 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 231 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 232
 233 Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details.
 234
 235 \membersection{wxTreeCtrl::Delete}\label{wxtreectrldelete}
 236
 237 \func{void}{Delete}{\param{const wxTreeItemId\&}{ item}}
 238
 239 Deletes the specified item. A {\tt EVT\_TREE\_DELETE\_ITEM} event will be
 240 generated.
 241
 242 This function may cause a subsequent call to GetNextChild to fail.
 243
 244 \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems}
 245
 246 \func{void}{DeleteAllItems}{\void}
 247
 248 Deletes all the items in the control. Note that this may not generate
 249 {\tt EVT\_TREE\_DELETE\_ITEM} events under some Windows versions although
 250 normally such event is generated for each removed item.
 251
 252 \membersection{wxTreeCtrl::DeleteChildren}\label{wxtreectrldeletechildren}
 253
 254 \func{void}{DeleteChildren}{\param{const wxTreeItemId\& }{item}}
 255
 256 Deletes all children of the given item (but not the item itself). Note that
 257 this will {\bf not} generate any events unlike
 258 \helpref{Delete}{wxtreectrldelete} method.
 259
 260 If you have called \helpref{wxTreeCtrl::SetItemHasChildren}{wxtreectrlsetitemhaschildren}, you
 261 may need to call it again since {\it DeleteChildren} does not automatically
 262 clear the setting.
 263
 264 \membersection{wxTreeCtrl::EditLabel}\label{wxtreectrleditlabel}
 265
 266 \func{void}{EditLabel}{\param{const wxTreeItemId\&}{ item}}
 267
 268 Starts editing the label of the given item. This function generates a
 269 EVT\_TREE\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
 270 text control will appear for in-place editing.
 271
 272 If the user changed the label (i.e. s/he does not press ESC or leave
 273 the text control without changes, a EVT\_TREE\_END\_LABEL\_EDIT event
 274 will be sent which can be vetoed as well.
 275
 276 \wxheading{See also}
 277
 278 \helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel},
 279 \helpref{wxTreeEvent}{wxtreeevent}
 280
 281 \membersection{wxTreeCtrl::EndEditLabel}\label{wxtreectrlendeditlabel}
 282
 283 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
 284
 285 Ends label editing. If {\it cancelEdit} is {\tt true}, the edit will be cancelled.
 286
 287 This function is currently supported under Windows only.
 288
 289 \wxheading{See also}
 290
 291 \helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}
 292
 293 \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible}
 294
 295 \func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}}
 296
 297 Scrolls and/or expands items to ensure that the given item is visible.
 298
 299 \membersection{wxTreeCtrl::Expand}\label{wxtreectrlexpand}
 300
 301 \func{void}{Expand}{\param{const wxTreeItemId\&}{ item}}
 302
 303 Expands the given item.
 304
 305 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
 306
 307 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = {\tt false}}}
 308
 309 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is {\tt true},
 310 only the rectangle around the item's label will be returned, otherwise the
 311 item's image is also taken into account.
 312
 313 The return value is {\tt true} if the rectangle was successfully retrieved or {\tt false}
 314 if it was not (in this case {\it rect} is not changed) - for example, if the
 315 item is currently invisible.
 316
 317 \pythonnote{The wxPython version of this method requires only the
 318 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 319 {\tt wxRect} object or {\tt None}.}
 320
 321 \perlnote{In wxPerl this method only takes the parameters {\tt item} and
 322   {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
 323
 324 \membersection{wxTreeCtrl::GetButtonsImageList}\label{wxtreectrlgetbuttonsimagelist}
 325
 326 \constfunc{wxImageList*}{GetButtonsImageList}{\void}
 327
 328 Returns the buttons image list (from which application-defined button images are taken).
 329
 330 This function is only available in the generic version.
 331
 332 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 333
 334 \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = {\tt true}}}
 335
 336 Returns the number of items in the branch. If {\it recursively} is {\tt true}, returns the total number
 337 of descendants, otherwise only one level of children is counted.
 338
 339 \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
 340
 341 \constfunc{int}{GetCount}{\void}
 342
 343 Returns the number of items in the control.
 344
 345 \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
 346
 347 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
 348
 349 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
 350 if no label is being edited.
 351
 352 {\bf NB:} It is currently only implemented for wxMSW.
 353
 354 \membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
 355
 356 \constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 357
 358 Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
 359
 360 For this enumeration function you must pass in a `cookie' parameter
 361 which is opaque for the application but is necessary for the library
 362 to make these functions reentrant (i.e. allow more than one
 363 enumeration on one and the same object simultaneously). The cookie passed to
 364 GetFirstChild and GetNextChild should be the same variable.
 365
 366 Returns an invalid tree item if there are no further children.
 367
 368 \wxheading{See also}
 369
 370 \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild},
 371 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 372
 373 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 374 value are both returned as a tuple containing the two values.}
 375
 376 \perlnote{In wxPerl this method only takes the {\tt item} parameter, and
 377   returns a 2-element list {\tt ( item, cookie )}.}
 378
 379 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 380
 381 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
 382
 383 Returns the first visible item.
 384
 385 \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
 386
 387 \constfunc{wxImageList*}{GetImageList}{\void}
 388
 389 Returns the normal image list.
 390
 391 \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
 392
 393 \constfunc{int}{GetIndent}{\void}
 394
 395 Returns the current tree control indentation.
 396
 397 \membersection{wxTreeCtrl::GetItemBackgroundColour}\label{wxtreectrlgetitembackgroundcolour}
 398
 399 \constfunc{wxColour}{GetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}}
 400
 401 Returns the background colour of the item.
 402
 403 \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
 404
 405 \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
 406
 407 Returns the tree item data associated with the item.
 408
 409 \wxheading{See also}
 410
 411 \helpref{wxTreeItemData}{wxtreeitemdata}
 412
 413 \pythonnote{wxPython provides the following shortcut method:
 414
 415 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 416 \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
 417 associated with the wxTreeItemData for the given item Id.}
 418 \end{twocollist}}
 419 }
 420
 421 \perlnote{wxPerl provides the following shortcut method:
 422 \indented{2cm}{
 423 \begin{twocollist}\itemsep=0pt
 424 \twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
 425 associated with the Wx::TreeItemData ( it is just the same as
 426 tree->GetItemData( item )->GetData(); ).}
 427 \end{twocollist}}
 428 }
 429
 430 \membersection{wxTreeCtrl::GetItemFont}\label{wxtreectrlgetitemfont}
 431
 432 \constfunc{wxFont}{GetItemFont}{\param{const wxTreeItemId\&}{ item}}
 433
 434 Returns the font of the item label.
 435
 436 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 437
 438 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
 439  \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 440
 441 Gets the specified item image. The value of {\it which} may be:
 442
 443 \begin{itemize}\itemsep=0pt
 444 \item{wxTreeItemIcon\_Normal} to get the normal item image
 445 \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
 446 which is shown when the item is currently selected)
 447 \item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
 448 makes sense for items which have children - then this image is shown when the
 449 item is expanded and the normal image is shown when it is collapsed)
 450 \item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
 451 (which is shown when an expanded item is currently selected)
 452 \end{itemize}
 453
 454 \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
 455
 456 \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
 457
 458 Returns the item label.
 459
 460 \membersection{wxTreeCtrl::GetItemTextColour}\label{wxtreectrlgetitemtextcolour}
 461
 462 \constfunc{wxColour}{GetItemTextColour}{\param{const wxTreeItemId\&}{ item}}
 463
 464 Returns the colour of the item label.
 465
 466 \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
 467
 468 \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
 469
 470 Returns the last child of the item (or an invalid tree item if this item has no children).
 471
 472 \wxheading{See also}
 473
 474 \helpref{GetFirstChild}{wxtreectrlgetfirstchild},
 475 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling},
 476 \helpref{GetLastChild}{wxtreectrlgetlastchild}
 477
 478 \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
 479
 480 \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 481
 482 Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
 483
 484 For this enumeration function you must pass in a `cookie' parameter
 485 which is opaque for the application but is necessary for the library
 486 to make these functions reentrant (i.e. allow more than one
 487 enumeration on one and the same object simultaneously). The cookie passed to
 488 GetFirstChild and GetNextChild should be the same.
 489
 490 Returns an invalid tree item if there are no further children.
 491
 492 \wxheading{See also}
 493
 494 \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
 495
 496 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 497 value are both returned as a tuple containing the two values.}
 498
 499 \perlnote{In wxPerl this method returns a 2-element list
 500   {\tt ( item, cookie )}, instead of modifying its parameters.}
 501
 502 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 503
 504 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
 505
 506 Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
 507
 508 Returns an invalid tree item if there are no further siblings.
 509
 510 \wxheading{See also}
 511
 512 \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
 513
 514 \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
 515
 516 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 517
 518 Returns the next visible item.
 519
 520 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}
 521
 522 \constfunc{wxTreeItemId}{GetItemParent}{\param{const wxTreeItemId\&}{ item}}
 523
 524 Returns the item's parent.
 525
 526 \membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent}
 527
 528 \constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}
 529
 530 {\bf NOTE:} This function is deprecated and will only work if {\tt WXWIN\_COMPATIBILITY\_2\_2}
 531 is defined.  Use \helpref{wxTreeCtrl::GetItemParent}{wxtreectrlgetitemparent} instead.
 532
 533 Returns the item's parent.
 534
 535 \pythonnote{This method is named {\tt GetItemParent} to avoid a name
 536 clash with wxWindow::GetParent.}
 537
 538 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
 539
 540 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
 541
 542 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
 543
 544 Returns an invalid tree item if there are no further children.
 545
 546 \wxheading{See also}
 547
 548 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 549
 550 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
 551
 552 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 553
 554 Returns the previous visible item.
 555
 556 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
 557
 558 \constfunc{wxTreeItemId}{GetRootItem}{\void}
 559
 560 Returns the root item for the tree control.
 561
 562 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
 563
 564 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 565
 566 Gets the selected item image (this function is obsolete, use
 567 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 568
 569 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
 570
 571 \constfunc{wxTreeItemId}{GetSelection}{\void}
 572
 573 Returns the selection, or an invalid item if there is no selection.
 574 This function only works with the controls without wxTR\_MULTIPLE style, use
 575 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
 576 this style.
 577
 578 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
 579
 580 \constfunc{size\_t}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
 581
 582 Fills the array of tree items passed in with the currently selected items. This
 583 function can be called only if the control has the wxTR\_MULTIPLE style.
 584
 585 Returns the number of selected items.
 586
 587 \pythonnote{The wxPython version of this method accepts no parameters
 588 and returns a Python list of {\tt wxTreeItemId}s.}
 589
 590 \perlnote{In wxPerl this method takes no parameters and returns a list of
 591  {\tt Wx::TreeItemId}s.}
 592
 593 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 594
 595 \constfunc{wxImageList*}{GetStateImageList}{\void}
 596
 597 Returns the state image list (from which application-defined state images are taken).
 598
 599 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
 600
 601 \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 602
 603 Calculates which (if any) item is under the given point, returning the tree item
 604 id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
 605
 606 \twocolwidtha{5cm}
 607 \begin{twocollist}\itemsep=0pt
 608 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
 609 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
 610 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 611 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
 612 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 613 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
 614 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 615 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 616 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 617 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
 618 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
 619 \end{twocollist}
 620
 621 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 622 returned as a tuple.}
 623
 624 \perlnote{In wxPerl this method only takes the {\tt point} parameter
 625   and returns a 2-element list {\tt ( item, flags )}.}
 626
 627 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 628
 629 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 630  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 631
 632 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 633  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 634
 635 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 636 {\it before} must be less than the number of children.
 637
 638 The {\it image} and {\it selImage} parameters are an index within
 639 the normal image list specifying the image to use for unselected and
 640 selected items, respectively.
 641 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 642 both selected and unselected items.
 643
 644 \pythonnote{The second form of this method is called
 645 {\tt InsertItemBefore} in wxPython.}
 646
 647 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 648
 649 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 650
 651 Returns {\tt true} if the given item is in bold state.
 652
 653 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 654
 655 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 656
 657 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 658
 659 Returns {\tt true} if the item is expanded (only makes sense if it has children).
 660
 661 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 662
 663 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 664
 665 Returns {\tt true} if the item is selected.
 666
 667 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 668
 669 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 670
 671 Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
 672
 673 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 674
 675 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 676
 677 Returns {\tt true} if the item has children.
 678
 679 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 680
 681 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 682
 683 Override this function in the derived class to change the sort order of the
 684 items in the tree control. The function should return a negative, zero or
 685 positive value if the first item is less than, equal to or greater than the
 686 second one.
 687
 688 The base class version compares items alphabetically.
 689
 690 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 691
 692 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 693
 694 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 695  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 696
 697 Appends an item as the first child of {\it parent}, return a new item id.
 698
 699 The {\it image} and {\it selImage} parameters are an index within
 700 the normal image list specifying the image to use for unselected and
 701 selected items, respectively.
 702 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 703 both selected and unselected items.
 704
 705 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 706
 707 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 708
 709 Scrolls the specified item into view.
 710
 711 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 712
 713 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}}
 714
 715 Selects the given item.
 716
 717 \membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
 718
 719 \func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
 720
 721 Sets the buttons image list (from which application-defined button images are taken).
 722 The button images assigned with this method will
 723 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 724
 725 Setting or assigning the button image list enables the display of image buttons.
 726 Once enabled, the only way to disable the display of button images is to set
 727 the button image list to {\tt NULL}.
 728
 729 This function is only available in the generic version.
 730
 731 See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
 732
 733 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 734
 735 \func{void}{SetIndent}{\param{int }{indent}}
 736
 737 Sets the indentation for the tree control.
 738
 739 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 740
 741 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 742
 743 Sets the normal image list. Image list assigned with this method will
 744 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 745
 746 See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 747
 748
 749 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 750
 751 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 752
 753 Sets the colour of the item's background.
 754
 755 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 756
 757 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
 758
 759 Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
 760 the normal state.
 761
 762 See also: \helpref{IsBold}{wxtreectrlisbold}
 763
 764 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 765
 766 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 767
 768 Sets the item client data.
 769
 770 \pythonnote{wxPython provides the following shortcut method:\par
 771 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 772 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 773 Object with the wxTreeItemData for the given item Id.}
 774 \end{twocollist}}
 775 }
 776
 777 \perlnote{wxPerl provides the following shortcut method:
 778 \indented{2cm}{
 779 \begin{twocollist}\itemsep=0pt
 780 \twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
 781 associated with the Wx::TreeItemData ( it is just the same as
 782 tree->GetItemData( item )->SetData( data ); ).}
 783 \end{twocollist}}
 784 }
 785
 786 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 787
 788 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 789
 790 Sets the item's font. All items in the tree should have the same height to avoid
 791 text clipping, so the fonts height should be the same for all of them,
 792 although font attributes may vary.
 793
 794 \wxheading{See also}
 795
 796 \helpref{SetItemBold}{wxtreectrlsetitembold}
 797
 798 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 799
 800 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
 801
 802 Force appearance of the button next to the item. This is useful to
 803 allow the user to expand the items which don't have any children now,
 804 but instead adding them only when needed, thus minimizing memory
 805 usage and loading time.
 806
 807 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 808
 809 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 810  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 811
 812 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 813 for the description of the {\it which} parameter.
 814
 815 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 816
 817 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 818
 819 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 820
 821 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 822
 823 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 824
 825 Sets the item label.
 826
 827 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 828
 829 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 830
 831 Sets the colour of the item's text.
 832
 833 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 834
 835 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 836
 837 Sets the state image list (from which application-defined state images are taken).
 838 Image list assigned with this method will
 839 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 840
 841 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 842
 843 \func{void}{SetWindowStyle}{\param{long}{styles}}
 844
 845 Sets the mode flags associated with the display of the tree control.
 846 The new mode takes effect immediately.
 847 (Generic only; MSW ignores changes.)
 848
 849 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 850
 851 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 852
 853 Sorts the children of the given item using
 854 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 855 should override that method to change the sort order (the default is ascending
 856 case-sensitive alphabetical order).
 857
 858 \wxheading{See also}
 859
 860 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 861
 862 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 863
 864 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 865
 866 Toggles the given item between collapsed and expanded states.
 867
 868 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 869
 870 \func{void}{Unselect}{\void}
 871
 872 Removes the selection from the currently selected item (if any).
 873
 874 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 875
 876 \func{void}{UnselectAll}{\void}
 877
 878 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 879 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 880 all items if it does have this style.
 881