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
 114 \membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr}
 115
 116 \func{}{wxTreeCtrl}{\void}
 117
 118 Default constructor.
 119
 120 \func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 121 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 122 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 123
 124 Constructor, creating and showing a tree control.
 125
 126 \wxheading{Parameters}
 127
 128 \docparam{parent}{Parent window. Must not be {\tt NULL}.}
 129
 130 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
 131
 132 \docparam{pos}{Window position.}
 133
 134 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 135 appropriately.}
 136
 137 \docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.}
 138
 139 \docparam{validator}{Window validator.}
 140
 141 \docparam{name}{Window name.}
 142
 143 \wxheading{See also}
 144
 145 \helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator}
 146
 147
 148 \membersection{wxTreeCtrl::\destruct{wxTreeCtrl}}
 149
 150 \func{void}{\destruct{wxTreeCtrl}}{\void}
 151
 152 Destructor, destroying the list control.
 153
 154
 155 \membersection{wxTreeCtrl::AddRoot}\label{wxtreectrladdroot}
 156
 157 \func{wxTreeItemId}{AddRoot}{\param{const wxString\&}{ text},
 158  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 159
 160 Adds the root node to the tree, returning the new item.
 161
 162 The {\it image} and {\it selImage} parameters are an index within
 163 the normal image list specifying the image to use for unselected and
 164 selected items, respectively.
 165 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 166 both selected and unselected items.
 167
 168
 169 \membersection{wxTreeCtrl::AppendItem}\label{wxtreectrlappenditem}
 170
 171 \func{wxTreeItemId}{AppendItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 172  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 173
 174 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
 175
 176 The {\it image} and {\it selImage} parameters are an index within
 177 the normal image list specifying the image to use for unselected and
 178 selected items, respectively.
 179 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 180 both selected and unselected items.
 181
 182
 183 \membersection{wxTreeCtrl::AssignButtonsImageList}\label{wxtreectrlassignbuttonsimagelist}
 184
 185 \func{void}{AssignButtonsImageList}{\param{wxImageList*}{ imageList}}
 186
 187 Sets the buttons image list. The button images assigned with this method will
 188 be automatically deleted by wxTreeCtrl as appropriate
 189 (i.e. it takes ownership of the list).
 190
 191 Setting or assigning the button image list enables the display of image buttons.
 192 Once enabled, the only way to disable the display of button images is to set
 193 the button image list to {\tt NULL}.
 194
 195 This function is only available in the generic version.
 196
 197 See also \helpref{SetButtonsImageList}{wxtreectrlsetbuttonsimagelist}.
 198
 199
 200 \membersection{wxTreeCtrl::AssignImageList}\label{wxtreectrlassignimagelist}
 201
 202 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
 203
 204 Sets the normal image list. Image list assigned with this method will
 205 be automatically deleted by wxTreeCtrl as appropriate
 206 (i.e. it takes ownership of the list).
 207
 208 See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 209
 210
 211 \membersection{wxTreeCtrl::AssignStateImageList}\label{wxtreectrlassignstateimagelist}
 212
 213 \func{void}{AssignStateImageList}{\param{wxImageList*}{ imageList}}
 214
 215 Sets the state image list. Image list assigned with this method will
 216 be automatically deleted by wxTreeCtrl as appropriate
 217 (i.e. it takes ownership of the list).
 218
 219 See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
 220
 221
 222
 223 \membersection{wxTreeCtrl::Collapse}\label{wxtreectrlcollapse}
 224
 225 \func{void}{Collapse}{\param{const wxTreeItemId\&}{ item}}
 226
 227 Collapses the given item.
 228
 229
 230 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
 231
 232 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}
 233
 234 Collapses the given item and removes all children.
 235
 236
 237 \membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate}
 238
 239 \func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 240 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 241 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 242
 243 Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details.
 244
 245
 246 \membersection{wxTreeCtrl::Delete}\label{wxtreectrldelete}
 247
 248 \func{void}{Delete}{\param{const wxTreeItemId\&}{ item}}
 249
 250 Deletes the specified item. A {\tt EVT\_TREE\_DELETE\_ITEM} event will be
 251 generated.
 252
 253 This function may cause a subsequent call to GetNextChild to fail.
 254
 255
 256 \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems}
 257
 258 \func{void}{DeleteAllItems}{\void}
 259
 260 Deletes all the items in the control. Note that this may not generate
 261 {\tt EVT\_TREE\_DELETE\_ITEM} events under some Windows versions although
 262 normally such event is generated for each removed item.
 263
 264
 265 \membersection{wxTreeCtrl::DeleteChildren}\label{wxtreectrldeletechildren}
 266
 267 \func{void}{DeleteChildren}{\param{const wxTreeItemId\& }{item}}
 268
 269 Deletes all children of the given item (but not the item itself). Note that
 270 this will {\bf not} generate any events unlike
 271 \helpref{Delete}{wxtreectrldelete} method.
 272
 273 If you have called \helpref{wxTreeCtrl::SetItemHasChildren}{wxtreectrlsetitemhaschildren}, you
 274 may need to call it again since {\it DeleteChildren} does not automatically
 275 clear the setting.
 276
 277
 278 \membersection{wxTreeCtrl::EditLabel}\label{wxtreectrleditlabel}
 279
 280 \func{void}{EditLabel}{\param{const wxTreeItemId\&}{ item}}
 281
 282 Starts editing the label of the given item. This function generates a
 283 EVT\_TREE\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
 284 text control will appear for in-place editing.
 285
 286 If the user changed the label (i.e. s/he does not press ESC or leave
 287 the text control without changes, a EVT\_TREE\_END\_LABEL\_EDIT event
 288 will be sent which can be vetoed as well.
 289
 290 \wxheading{See also}
 291
 292 \helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel},
 293 \helpref{wxTreeEvent}{wxtreeevent}
 294
 295
 296 \membersection{wxTreeCtrl::EndEditLabel}\label{wxtreectrlendeditlabel}
 297
 298 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
 299
 300 Ends label editing. If {\it cancelEdit} is {\tt true}, the edit will be cancelled.
 301
 302 This function is currently supported under Windows only.
 303
 304 \wxheading{See also}
 305
 306 \helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}
 307
 308
 309 \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible}
 310
 311 \func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}}
 312
 313 Scrolls and/or expands items to ensure that the given item is visible.
 314
 315
 316 \membersection{wxTreeCtrl::Expand}\label{wxtreectrlexpand}
 317
 318 \func{void}{Expand}{\param{const wxTreeItemId\&}{ item}}
 319
 320 Expands the given item.
 321
 322
 323 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
 324
 325 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = {\tt false}}}
 326
 327 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is {\tt true},
 328 only the rectangle around the item's label will be returned, otherwise the
 329 item's image is also taken into account.
 330
 331 The return value is {\tt true} if the rectangle was successfully retrieved or {\tt false}
 332 if it was not (in this case {\it rect} is not changed) - for example, if the
 333 item is currently invisible.
 334
 335 \pythonnote{The wxPython version of this method requires only the
 336 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 337 {\tt wxRect} object or {\tt None}.}
 338
 339 \perlnote{In wxPerl this method only takes the parameters {\tt item} and
 340   {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
 341
 342
 343 \membersection{wxTreeCtrl::GetButtonsImageList}\label{wxtreectrlgetbuttonsimagelist}
 344
 345 \constfunc{wxImageList*}{GetButtonsImageList}{\void}
 346
 347 Returns the buttons image list (from which application-defined button images are taken).
 348
 349 This function is only available in the generic version.
 350
 351
 352 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 353
 354 \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = {\tt true}}}
 355
 356 Returns the number of items in the branch. If {\it recursively} is {\tt true}, returns the total number
 357 of descendants, otherwise only one level of children is counted.
 358
 359
 360 \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
 361
 362 \constfunc{int}{GetCount}{\void}
 363
 364 Returns the number of items in the control.
 365
 366
 367 \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
 368
 369 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
 370
 371 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
 372 if no label is being edited.
 373
 374 {\bf NB:} It is currently only implemented for wxMSW.
 375
 376
 377 \membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
 378
 379 \constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 380
 381 Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
 382
 383 For this enumeration function you must pass in a `cookie' parameter
 384 which is opaque for the application but is necessary for the library
 385 to make these functions reentrant (i.e. allow more than one
 386 enumeration on one and the same object simultaneously). The cookie passed to
 387 GetFirstChild and GetNextChild should be the same variable.
 388
 389 Returns an invalid tree item if there are no further children.
 390
 391 \wxheading{See also}
 392
 393 \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild},
 394 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 395
 396 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 397 value are both returned as a tuple containing the two values.}
 398
 399 \perlnote{In wxPerl this method only takes the {\tt item} parameter, and
 400   returns a 2-element list {\tt ( item, cookie )}.}
 401
 402
 403 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 404
 405 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
 406
 407 Returns the first visible item.
 408
 409
 410 \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
 411
 412 \constfunc{wxImageList*}{GetImageList}{\void}
 413
 414 Returns the normal image list.
 415
 416
 417 \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
 418
 419 \constfunc{int}{GetIndent}{\void}
 420
 421 Returns the current tree control indentation.
 422
 423
 424 \membersection{wxTreeCtrl::GetItemBackgroundColour}\label{wxtreectrlgetitembackgroundcolour}
 425
 426 \constfunc{wxColour}{GetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}}
 427
 428 Returns the background colour of the item.
 429
 430
 431 \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
 432
 433 \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
 434
 435 Returns the tree item data associated with the item.
 436
 437 \wxheading{See also}
 438
 439 \helpref{wxTreeItemData}{wxtreeitemdata}
 440
 441 \pythonnote{wxPython provides the following shortcut method:
 442
 443 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 444 \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
 445 associated with the wxTreeItemData for the given item Id.}
 446 \end{twocollist}}
 447 }
 448
 449 \perlnote{wxPerl provides the following shortcut method:
 450 \indented{2cm}{
 451 \begin{twocollist}\itemsep=0pt
 452 \twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
 453 associated with the Wx::TreeItemData ( it is just the same as
 454 tree->GetItemData( item )->GetData(); ).}
 455 \end{twocollist}}
 456 }
 457
 458
 459 \membersection{wxTreeCtrl::GetItemFont}\label{wxtreectrlgetitemfont}
 460
 461 \constfunc{wxFont}{GetItemFont}{\param{const wxTreeItemId\&}{ item}}
 462
 463 Returns the font of the item label.
 464
 465
 466 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 467
 468 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
 469  \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 470
 471 Gets the specified item image. The value of {\it which} may be:
 472
 473 \begin{itemize}\itemsep=0pt
 474 \item{wxTreeItemIcon\_Normal} to get the normal item image
 475 \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
 476 which is shown when the item is currently selected)
 477 \item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
 478 makes sense for items which have children - then this image is shown when the
 479 item is expanded and the normal image is shown when it is collapsed)
 480 \item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
 481 (which is shown when an expanded item is currently selected)
 482 \end{itemize}
 483
 484
 485 \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
 486
 487 \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
 488
 489 Returns the item label.
 490
 491
 492 \membersection{wxTreeCtrl::GetItemTextColour}\label{wxtreectrlgetitemtextcolour}
 493
 494 \constfunc{wxColour}{GetItemTextColour}{\param{const wxTreeItemId\&}{ item}}
 495
 496 Returns the colour of the item label.
 497
 498
 499 \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
 500
 501 \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
 502
 503 Returns the last child of the item (or an invalid tree item if this item has no children).
 504
 505 \wxheading{See also}
 506
 507 \helpref{GetFirstChild}{wxtreectrlgetfirstchild},
 508 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling},
 509 \helpref{GetLastChild}{wxtreectrlgetlastchild}
 510
 511
 512 \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
 513
 514 \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 515
 516 Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
 517
 518 For this enumeration function you must pass in a `cookie' parameter
 519 which is opaque for the application but is necessary for the library
 520 to make these functions reentrant (i.e. allow more than one
 521 enumeration on one and the same object simultaneously). The cookie passed to
 522 GetFirstChild and GetNextChild should be the same.
 523
 524 Returns an invalid tree item if there are no further children.
 525
 526 \wxheading{See also}
 527
 528 \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
 529
 530 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 531 value are both returned as a tuple containing the two values.}
 532
 533 \perlnote{In wxPerl this method returns a 2-element list
 534   {\tt ( item, cookie )}, instead of modifying its parameters.}
 535
 536
 537 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 538
 539 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
 540
 541 Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
 542
 543 Returns an invalid tree item if there are no further siblings.
 544
 545 \wxheading{See also}
 546
 547 \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
 548
 549
 550 \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
 551
 552 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 553
 554 Returns the next visible item.
 555
 556
 557 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}
 558
 559 \constfunc{wxTreeItemId}{GetItemParent}{\param{const wxTreeItemId\&}{ item}}
 560
 561 Returns the item's parent.
 562
 563
 564 \membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent}
 565
 566 \constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}
 567
 568 {\bf NOTE:} This function is deprecated and will only work if {\tt WXWIN\_COMPATIBILITY\_2\_2}
 569 is defined.  Use \helpref{wxTreeCtrl::GetItemParent}{wxtreectrlgetitemparent} instead.
 570
 571 Returns the item's parent.
 572
 573 \pythonnote{This method is named {\tt GetItemParent} to avoid a name
 574 clash with wxWindow::GetParent.}
 575
 576
 577 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
 578
 579 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
 580
 581 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
 582
 583 Returns an invalid tree item if there are no further children.
 584
 585 \wxheading{See also}
 586
 587 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 588
 589
 590 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
 591
 592 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 593
 594 Returns the previous visible item.
 595
 596
 597 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
 598
 599 \constfunc{wxTreeItemId}{GetRootItem}{\void}
 600
 601 Returns the root item for the tree control.
 602
 603
 604 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
 605
 606 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 607
 608 Gets the selected item image (this function is obsolete, use
 609 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 610
 611
 612 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
 613
 614 \constfunc{wxTreeItemId}{GetSelection}{\void}
 615
 616 Returns the selection, or an invalid item if there is no selection.
 617 This function only works with the controls without wxTR\_MULTIPLE style, use
 618 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
 619 this style.
 620
 621
 622 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
 623
 624 \constfunc{size\_t}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
 625
 626 Fills the array of tree items passed in with the currently selected items. This
 627 function can be called only if the control has the wxTR\_MULTIPLE style.
 628
 629 Returns the number of selected items.
 630
 631 \pythonnote{The wxPython version of this method accepts no parameters
 632 and returns a Python list of {\tt wxTreeItemId}s.}
 633
 634 \perlnote{In wxPerl this method takes no parameters and returns a list of
 635  {\tt Wx::TreeItemId}s.}
 636
 637
 638 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 639
 640 \constfunc{wxImageList*}{GetStateImageList}{\void}
 641
 642 Returns the state image list (from which application-defined state images are taken).
 643
 644
 645 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
 646
 647 \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 648
 649 Calculates which (if any) item is under the given point, returning the tree item
 650 id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
 651
 652 \twocolwidtha{5cm}
 653 \begin{twocollist}\itemsep=0pt
 654 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
 655 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
 656 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 657 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
 658 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 659 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
 660 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 661 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 662 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 663 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
 664 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
 665 \end{twocollist}
 666
 667 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 668 returned as a tuple.}
 669
 670 \perlnote{In wxPerl this method only takes the {\tt point} parameter
 671   and returns a 2-element list {\tt ( item, flags )}.}
 672
 673
 674 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 675
 676 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 677  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 678
 679 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 680  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 681
 682 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 683 {\it before} must be less than the number of children.
 684
 685 The {\it image} and {\it selImage} parameters are an index within
 686 the normal image list specifying the image to use for unselected and
 687 selected items, respectively.
 688 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 689 both selected and unselected items.
 690
 691 \pythonnote{The second form of this method is called
 692 {\tt InsertItemBefore} in wxPython.}
 693
 694
 695 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 696
 697 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 698
 699 Returns {\tt true} if the given item is in bold state.
 700
 701 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 702
 703
 704 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 705
 706 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 707
 708 Returns {\tt true} if the item is expanded (only makes sense if it has children).
 709
 710
 711 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 712
 713 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 714
 715 Returns {\tt true} if the item is selected.
 716
 717
 718 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 719
 720 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 721
 722 Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
 723
 724
 725 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 726
 727 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 728
 729 Returns {\tt true} if the item has children.
 730
 731
 732 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 733
 734 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 735
 736 Override this function in the derived class to change the sort order of the
 737 items in the tree control. The function should return a negative, zero or
 738 positive value if the first item is less than, equal to or greater than the
 739 second one.
 740
 741 The base class version compares items alphabetically.
 742
 743 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 744
 745
 746 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 747
 748 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 749  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 750
 751 Appends an item as the first child of {\it parent}, return a new item id.
 752
 753 The {\it image} and {\it selImage} parameters are an index within
 754 the normal image list specifying the image to use for unselected and
 755 selected items, respectively.
 756 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 757 both selected and unselected items.
 758
 759
 760 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 761
 762 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 763
 764 Scrolls the specified item into view.
 765
 766
 767 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 768
 769 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}, \param{bool }{select = \true}}
 770
 771 Selects the given item. In multiple selection controls, can be also used to
 772 deselect a currently selected item if the value of \arg{select} is false.
 773
 774
 775 \membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
 776
 777 \func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
 778
 779 Sets the buttons image list (from which application-defined button images are taken).
 780 The button images assigned with this method will
 781 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 782
 783 Setting or assigning the button image list enables the display of image buttons.
 784 Once enabled, the only way to disable the display of button images is to set
 785 the button image list to {\tt NULL}.
 786
 787 This function is only available in the generic version.
 788
 789 See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
 790
 791
 792 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 793
 794 \func{void}{SetIndent}{\param{int }{indent}}
 795
 796 Sets the indentation for the tree control.
 797
 798
 799 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 800
 801 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 802
 803 Sets the normal image list. Image list assigned with this method will
 804 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 805
 806 See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 807
 808
 809
 810 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 811
 812 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 813
 814 Sets the colour of the item's background.
 815
 816
 817 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 818
 819 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
 820
 821 Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
 822 the normal state.
 823
 824 See also: \helpref{IsBold}{wxtreectrlisbold}
 825
 826
 827 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 828
 829 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 830
 831 Sets the item client data.
 832
 833 \pythonnote{wxPython provides the following shortcut method:\par
 834 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 835 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 836 Object with the wxTreeItemData for the given item Id.}
 837 \end{twocollist}}
 838 }
 839
 840 \perlnote{wxPerl provides the following shortcut method:
 841 \indented{2cm}{
 842 \begin{twocollist}\itemsep=0pt
 843 \twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
 844 associated with the Wx::TreeItemData ( it is just the same as
 845 tree->GetItemData( item )->SetData( data ); ).}
 846 \end{twocollist}}
 847 }
 848
 849
 850 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 851
 852 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 853
 854 Sets the item's font. All items in the tree should have the same height to avoid
 855 text clipping, so the fonts height should be the same for all of them,
 856 although font attributes may vary.
 857
 858 \wxheading{See also}
 859
 860 \helpref{SetItemBold}{wxtreectrlsetitembold}
 861
 862
 863 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 864
 865 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
 866
 867 Force appearance of the button next to the item. This is useful to
 868 allow the user to expand the items which don't have any children now,
 869 but instead adding them only when needed, thus minimizing memory
 870 usage and loading time.
 871
 872
 873 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 874
 875 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 876  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 877
 878 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 879 for the description of the {\it which} parameter.
 880
 881
 882 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 883
 884 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 885
 886 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 887
 888
 889 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 890
 891 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 892
 893 Sets the item label.
 894
 895
 896 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 897
 898 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 899
 900 Sets the colour of the item's text.
 901
 902
 903 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 904
 905 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 906
 907 Sets the state image list (from which application-defined state images are taken).
 908 Image list assigned with this method will
 909 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 910
 911 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 912
 913 \func{void}{SetWindowStyle}{\param{long}{styles}}
 914
 915 Sets the mode flags associated with the display of the tree control.
 916 The new mode takes effect immediately.
 917 (Generic only; MSW ignores changes.)
 918
 919
 920 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 921
 922 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 923
 924 Sorts the children of the given item using
 925 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 926 should override that method to change the sort order (the default is ascending
 927 case-sensitive alphabetical order).
 928
 929 \wxheading{See also}
 930
 931 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 932
 933
 934 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 935
 936 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 937
 938 Toggles the given item between collapsed and expanded states.
 939
 940
 941 \membersection{wxTreeCtrl::ToggleItemSelection}\label{wxtreectrltoggleitemselection}
 942
 943 \func{void}{ToggleItemSelection}{\param{const wxTreeItemId\&}{ item}}
 944
 945 Toggles the given item between selected and unselected states. For
 946 multiselection controls only.
 947
 948
 949 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 950
 951 \func{void}{Unselect}{\void}
 952
 953 Removes the selection from the currently selected item (if any).
 954
 955
 956 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 957
 958 \func{void}{UnselectAll}{\void}
 959
 960 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 961 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 962 all items if it does have this style.
 963
 964
 965 \membersection{wxTreeCtrl::UnselectItem}\label{wxtreectrlunselectitem}
 966
 967 \func{void}{UnselectItem}{\param{const wxTreeItemId\& }{item}}
 968
 969 Unselects the given item. This works in multiselection controls only.
 970
 971