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\_NO\_LINES}}{Use this style
  31 to hide vertical level connectors.}
  32 \twocolitem{\windowstyle{wxTR\_FULL\_ROW\_HIGHLIGHT}}{Use this style to have the background
  33 colour and the selection highlight extend over the entire horizontal
  34 row of the tree control window. (This flag is ignored under Windows unless you
  35 specify wxTR\_NO\_LINES as well.) }
  36 \twocolitem{\windowstyle{wxTR\_LINES\_AT\_ROOT}}{Use this style
  37 to show lines between root nodes.
  38 Only applicable if wxTR\_HIDE\_ROOT is set and wxTR\_NO\_LINES is not set.}
  39 \twocolitem{\windowstyle{wxTR\_HIDE\_ROOT}}{Use this style
  40 to suppress the display of the root node,
  41 effectively causing the first-level nodes
  42 to appear as a series of root nodes.}
  43 \twocolitem{\windowstyle{wxTR\_ROW\_LINES}}{Use this style
  44 to draw a contrasting border between displayed rows.}
  45 \twocolitem{\windowstyle{wxTR\_HAS\_VARIABLE\_ROW\_HEIGHT}}{Use this style
  46 to cause row heights to be just big enough to fit the content.
  47 If not set, all rows use the largest row height.
  48 The default is that this flag is unset.
  49 Generic only.}
  50 \twocolitem{\windowstyle{wxTR\_SINGLE}}{For convenience
  51 to document that only one item may be selected at a time.
  52 Selecting another item causes the current selection, if any,
  53 to be deselected.  This is the default.}
  54 \twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style
  55 to allow a range of items to be selected.
  56 If a second range is selected, the current range, if any, is deselected.}
  57 \twocolitem{\windowstyle{wxTR\_EXTENDED}}{Use this style
  58 to allow disjoint items to be selected.  (Only partially implemented; may not work in all cases.)}
  59 \twocolitem{\windowstyle{wxTR\_DEFAULT\_STYLE}}{The set of flags that are
  60 closest to the defaults for the native control for a particular toolkit.}
  61 \end{twocollist}
  62
  63 See also \helpref{window styles overview}{windowstyles}.
  64
  65 \wxheading{Event handling}
  66
  67 To process input from a tree control, use these event handler macros to direct input to member
  68 functions that take a \helpref{wxTreeEvent}{wxtreeevent} argument.
  69
  70 \twocolwidtha{7cm}
  71 \begin{twocollist}\itemsep=0pt
  72 \twocolitem{{\bf EVT\_TREE\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
  73 \twocolitem{{\bf EVT\_TREE\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
  74 \twocolitem{{\bf EVT\_TREE\_END\_DRAG(id, func)}}{End dragging with the left or right mouse button.}
  75 \twocolitem{{\bf EVT\_TREE\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  76 \twocolitem{{\bf EVT\_TREE\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  77 \twocolitem{{\bf EVT\_TREE\_DELETE\_ITEM(id, func)}}{Delete an item.}
  78 \twocolitem{{\bf EVT\_TREE\_GET\_INFO(id, func)}}{Request information from the application.}
  79 \twocolitem{{\bf EVT\_TREE\_SET\_INFO(id, func)}}{Information is being supplied.}
  80 \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}
  81 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSED(id, func)}}{The item has been collapsed.}
  82 \twocolitem{{\bf EVT\_TREE\_ITEM\_COLLAPSING(id, func)}}{The item is being collapsed. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  83 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{The item has been expanded.}
  84 \twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{The item is being expanded. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  85 \twocolitem{{\bf EVT\_TREE\_ITEM\_RIGHT\_CLICK(id, func)}}{The user has clicked the item with the right mouse button.}
  86 \twocolitem{{\bf EVT\_TREE\_ITEM\_MIDDLE\_CLICK(id, func)}}{The user has clicked the item with the middle mouse button.}
  87 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGED(id, func)}}{Selection has changed.}
  88 \twocolitem{{\bf EVT\_TREE\_SEL\_CHANGING(id, func)}}{Selection is changing. This can be prevented by calling \helpref{Veto()}{wxnotifyeventveto}.}
  89 \twocolitem{{\bf EVT\_TREE\_KEY\_DOWN(id, func)}}{A key has been pressed.}
  90 \twocolitem{{\bf EVT\_TREE\_ITEM\_GETTOOLTIP(id, func)}}{The opportunity to set the item tooltip
  91 is being given to the application (call wxTreeEvent::SetToolTip). Windows only.}
  92 \twocolitem{{\bf EVT\_TREE\_ITEM\_MENU(id, func)}}{The context menu for the selected item has been requested, either by a right click or by using the menu key.}
  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}}\label{wxtreectrldtor}
 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 (i.e. IsOk() returns {\tt false}) 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 \membersection{wxTreeCtrl::GetItemFont}\label{wxtreectrlgetitemfont}
 459
 460 \constfunc{wxFont}{GetItemFont}{\param{const wxTreeItemId\&}{ item}}
 461
 462 Returns the font of the item label.
 463
 464
 465 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 466
 467 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
 468  \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 469
 470 Gets the specified item image. The value of {\it which} may be:
 471
 472 \begin{itemize}\itemsep=0pt
 473 \item{wxTreeItemIcon\_Normal} to get the normal item image
 474 \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
 475 which is shown when the item is currently selected)
 476 \item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
 477 makes sense for items which have children - then this image is shown when the
 478 item is expanded and the normal image is shown when it is collapsed)
 479 \item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
 480 (which is shown when an expanded item is currently selected)
 481 \end{itemize}
 482
 483
 484 \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
 485
 486 \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
 487
 488 Returns the item label.
 489
 490
 491 \membersection{wxTreeCtrl::GetItemTextColour}\label{wxtreectrlgetitemtextcolour}
 492
 493 \constfunc{wxColour}{GetItemTextColour}{\param{const wxTreeItemId\&}{ item}}
 494
 495 Returns the colour of the item label.
 496
 497
 498 \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
 499
 500 \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
 501
 502 Returns the last child of the item (or an invalid tree item if this item has no children).
 503
 504 \wxheading{See also}
 505
 506 \helpref{GetFirstChild}{wxtreectrlgetfirstchild},
 507 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling},
 508 \helpref{GetLastChild}{wxtreectrlgetlastchild}
 509
 510
 511 \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
 512
 513 \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 514
 515 Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
 516
 517 For this enumeration function you must pass in a `cookie' parameter
 518 which is opaque for the application but is necessary for the library
 519 to make these functions reentrant (i.e. allow more than one
 520 enumeration on one and the same object simultaneously). The cookie passed to
 521 GetFirstChild and GetNextChild should be the same.
 522
 523 Returns an invalid tree item if there are no further children.
 524
 525 \wxheading{See also}
 526
 527 \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
 528
 529 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 530 value are both returned as a tuple containing the two values.}
 531
 532 \perlnote{In wxPerl this method returns a 2-element list
 533   {\tt ( item, cookie )}, instead of modifying its parameters.}
 534
 535
 536 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 537
 538 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
 539
 540 Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
 541
 542 Returns an invalid tree item if there are no further siblings.
 543
 544 \wxheading{See also}
 545
 546 \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
 547
 548
 549 \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
 550
 551 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 552
 553 Returns the next visible item.
 554
 555
 556 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}
 557
 558 \constfunc{wxTreeItemId}{GetItemParent}{\param{const wxTreeItemId\&}{ item}}
 559
 560 Returns the item's parent.
 561
 562
 563 \membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent}
 564
 565 \constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}
 566
 567 {\bf NOTE:} This function is deprecated and will only work if {\tt WXWIN\_COMPATIBILITY\_2\_2}
 568 is defined.  Use \helpref{wxTreeCtrl::GetItemParent}{wxtreectrlgetitemparent} instead.
 569
 570 Returns the item's parent.
 571
 572 \pythonnote{This method is named {\tt GetItemParent} to avoid a name
 573 clash with wxWindow::GetParent.}
 574
 575
 576 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
 577
 578 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
 579
 580 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
 581
 582 Returns an invalid tree item if there are no further children.
 583
 584 \wxheading{See also}
 585
 586 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 587
 588
 589 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
 590
 591 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 592
 593 Returns the previous visible item.
 594
 595
 596 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
 597
 598 \constfunc{wxTreeItemId}{GetRootItem}{\void}
 599
 600 Returns the root item for the tree control.
 601
 602
 603 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
 604
 605 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 606
 607 Gets the selected item image (this function is obsolete, use
 608 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 609
 610
 611 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
 612
 613 \constfunc{wxTreeItemId}{GetSelection}{\void}
 614
 615 Returns the selection, or an invalid item if there is no selection.
 616 This function only works with the controls without wxTR\_MULTIPLE style, use
 617 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
 618 this style.
 619
 620
 621 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
 622
 623 \constfunc{size\_t}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
 624
 625 Fills the array of tree items passed in with the currently selected items. This
 626 function can be called only if the control has the wxTR\_MULTIPLE style.
 627
 628 Returns the number of selected items.
 629
 630 \pythonnote{The wxPython version of this method accepts no parameters
 631 and returns a Python list of {\tt wxTreeItemId}s.}
 632
 633 \perlnote{In wxPerl this method takes no parameters and returns a list of
 634  {\tt Wx::TreeItemId}s.}
 635
 636
 637 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 638
 639 \constfunc{wxImageList*}{GetStateImageList}{\void}
 640
 641 Returns the state image list (from which application-defined state images are taken).
 642
 643
 644 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
 645
 646 \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 647
 648 Calculates which (if any) item is under the given point, returning the tree item
 649 id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
 650
 651 \twocolwidtha{5cm}
 652 \begin{twocollist}\itemsep=0pt
 653 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
 654 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
 655 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 656 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
 657 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 658 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
 659 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 660 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 661 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 662 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
 663 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
 664 \end{twocollist}
 665
 666 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 667 returned as a tuple.}
 668
 669 \perlnote{In wxPerl this method only takes the {\tt point} parameter
 670   and returns a 2-element list {\tt ( item, flags )}.}
 671
 672
 673 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 674
 675 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 676  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 677
 678 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 679  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 680
 681 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 682 {\it before} must be less than the number of children.
 683
 684 The {\it image} and {\it selImage} parameters are an index within
 685 the normal image list specifying the image to use for unselected and
 686 selected items, respectively.
 687 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 688 both selected and unselected items.
 689
 690 \pythonnote{The second form of this method is called
 691 {\tt InsertItemBefore} in wxPython.}
 692
 693
 694 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 695
 696 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 697
 698 Returns {\tt true} if the given item is in bold state.
 699
 700 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 701
 702
 703 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 704
 705 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 706
 707 Returns {\tt true} if the item is expanded (only makes sense if it has children).
 708
 709
 710 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 711
 712 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 713
 714 Returns {\tt true} if the item is selected.
 715
 716
 717 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 718
 719 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 720
 721 Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
 722
 723
 724 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 725
 726 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 727
 728 Returns {\tt true} if the item has children.
 729
 730
 731 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 732
 733 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 734
 735 Override this function in the derived class to change the sort order of the
 736 items in the tree control. The function should return a negative, zero or
 737 positive value if the first item is less than, equal to or greater than the
 738 second one.
 739
 740 The base class version compares items alphabetically.
 741
 742 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 743
 744
 745 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 746
 747 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 748  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 749
 750 Appends an item as the first child of {\it parent}, return a new item id.
 751
 752 The {\it image} and {\it selImage} parameters are an index within
 753 the normal image list specifying the image to use for unselected and
 754 selected items, respectively.
 755 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 756 both selected and unselected items.
 757
 758
 759 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 760
 761 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 762
 763 Scrolls the specified item into view.
 764
 765
 766 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 767
 768 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}, \param{bool }{select = \true}}
 769
 770 Selects the given item. In multiple selection controls, can be also used to
 771 deselect a currently selected item if the value of \arg{select} is false.
 772
 773
 774 \membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
 775
 776 \func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
 777
 778 Sets the buttons image list (from which application-defined button images are taken).
 779 The button images assigned with this method will
 780 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 781
 782 Setting or assigning the button image list enables the display of image buttons.
 783 Once enabled, the only way to disable the display of button images is to set
 784 the button image list to {\tt NULL}.
 785
 786 This function is only available in the generic version.
 787
 788 See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
 789
 790
 791 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 792
 793 \func{void}{SetIndent}{\param{int }{indent}}
 794
 795 Sets the indentation for the tree control.
 796
 797
 798 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 799
 800 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 801
 802 Sets the normal image list. Image list assigned with this method will
 803 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 804
 805 See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 806
 807
 808
 809 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 810
 811 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 812
 813 Sets the colour of the item's background.
 814
 815
 816 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 817
 818 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
 819
 820 Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
 821 the normal state.
 822
 823 See also: \helpref{IsBold}{wxtreectrlisbold}
 824
 825
 826 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 827
 828 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 829
 830 Sets the item client data.
 831
 832 \pythonnote{wxPython provides the following shortcut method:\par
 833 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 834 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 835 Object with the wxTreeItemData for the given item Id.}
 836 \end{twocollist}}
 837 }%
 838
 839 \perlnote{wxPerl provides the following shortcut method:
 840 \indented{2cm}{
 841 \begin{twocollist}\itemsep=0pt
 842 \twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
 843 associated with the Wx::TreeItemData. It is just the same as
 844 tree->GetItemData(item)->SetData(data).}
 845 \end{twocollist}}
 846 }%
 847
 848 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
 849
 850 \func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = {\tt true}}}
 851
 852 Gives the item the visual feedback for Drag'n'Drop actions, which is
 853 useful if something is dragged from the outside onto the tree control
 854 (as opposed to a DnD operation within the tree control, which already
 855 is implemented internally).
 856
 857 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 858
 859 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 860
 861 Sets the item's font. All items in the tree should have the same height to avoid
 862 text clipping, so the fonts height should be the same for all of them,
 863 although font attributes may vary.
 864
 865 \wxheading{See also}
 866
 867 \helpref{SetItemBold}{wxtreectrlsetitembold}
 868
 869
 870 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 871
 872 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
 873
 874 Force appearance of the button next to the item. This is useful to
 875 allow the user to expand the items which don't have any children now,
 876 but instead adding them only when needed, thus minimizing memory
 877 usage and loading time.
 878
 879
 880 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 881
 882 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 883  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 884
 885 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 886 for the description of the {\it which} parameter.
 887
 888
 889 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 890
 891 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 892
 893 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 894
 895
 896 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 897
 898 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 899
 900 Sets the item label.
 901
 902
 903 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 904
 905 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 906
 907 Sets the colour of the item's text.
 908
 909
 910 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 911
 912 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 913
 914 Sets the state image list (from which application-defined state images are taken).
 915 Image list assigned with this method will
 916 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 917
 918 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 919
 920 \membersection{wxTreeCtrl::SetWindowStyle}\label{wxtreectrlsetwindowstyle}
 921
 922 \func{void}{SetWindowStyle}{\param{long}{styles}}
 923
 924 Sets the mode flags associated with the display of the tree control.
 925 The new mode takes effect immediately.
 926 (Generic only; MSW ignores changes.)
 927
 928
 929 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 930
 931 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 932
 933 Sorts the children of the given item using
 934 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 935 should override that method to change the sort order (the default is ascending
 936 case-sensitive alphabetical order).
 937
 938 \wxheading{See also}
 939
 940 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 941
 942
 943 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 944
 945 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 946
 947 Toggles the given item between collapsed and expanded states.
 948
 949
 950 \membersection{wxTreeCtrl::ToggleItemSelection}\label{wxtreectrltoggleitemselection}
 951
 952 \func{void}{ToggleItemSelection}{\param{const wxTreeItemId\&}{ item}}
 953
 954 Toggles the given item between selected and unselected states. For
 955 multiselection controls only.
 956
 957
 958 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 959
 960 \func{void}{Unselect}{\void}
 961
 962 Removes the selection from the currently selected item (if any).
 963
 964
 965 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 966
 967 \func{void}{UnselectAll}{\void}
 968
 969 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 970 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 971 all items if it does have this style.
 972
 973
 974 \membersection{wxTreeCtrl::UnselectItem}\label{wxtreectrlunselectitem}
 975
 976 \func{void}{UnselectItem}{\param{const wxTreeItemId\& }{item}}
 977
 978 Unselects the given item. This works in multiselection controls only.
 979
 980