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 \twocolitem{{\bf EVT\_TREE\_STATE\_IMAGE\_CLICK(id, func)}}{The state image has been clicked. Windows only.}
  94 \end{twocollist}
  95
  96 \wxheading{See also}
  97
  98 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp
  99 \helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent}
 100
 101 \wxheading{Win32 notes}
 102
 103 wxTreeCtrl class uses the standard common treeview control under Win32
 104 implemented in the system library {\tt comctl32.dll}. Some versions of this
 105 library are known to have bugs with handling the tree control colours: the
 106 usual symptom is that the expanded items leave black (or otherwise incorrectly
 107 coloured) background behind them, especially for the controls using non
 108 default background colour. The recommended solution is to upgrade the {\tt comctl32.dll}
 109 to a newer version: see
 110 \urlref{http://www.microsoft.com/downloads/release.asp?ReleaseID=11916}{http://www.microsoft.com/downloads/release.asp?ReleaseID=11916}.
 111
 112 \latexignore{\rtfignore{\wxheading{Members}}}
 113
 114
 115 \membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr}
 116
 117 \func{}{wxTreeCtrl}{\void}
 118
 119 Default constructor.
 120
 121 \func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 122 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 123 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 124
 125 Constructor, creating and showing a tree control.
 126
 127 \wxheading{Parameters}
 128
 129 \docparam{parent}{Parent window. Must not be {\tt NULL}.}
 130
 131 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
 132
 133 \docparam{pos}{Window position.}
 134
 135 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 136 appropriately.}
 137
 138 \docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.}
 139
 140 \docparam{validator}{Window validator.}
 141
 142 \docparam{name}{Window name.}
 143
 144 \wxheading{See also}
 145
 146 \helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator}
 147
 148
 149 \membersection{wxTreeCtrl::\destruct{wxTreeCtrl}}\label{wxtreectrldtor}
 150
 151 \func{void}{\destruct{wxTreeCtrl}}{\void}
 152
 153 Destructor, destroying the list control.
 154
 155
 156 \membersection{wxTreeCtrl::AddRoot}\label{wxtreectrladdroot}
 157
 158 \func{wxTreeItemId}{AddRoot}{\param{const wxString\&}{ text},
 159  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 160
 161 Adds the root node to the tree, returning the new item.
 162
 163 The {\it image} and {\it selImage} parameters are an index within
 164 the normal image list specifying the image to use for unselected and
 165 selected items, respectively.
 166 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 167 both selected and unselected items.
 168
 169
 170 \membersection{wxTreeCtrl::AppendItem}\label{wxtreectrlappenditem}
 171
 172 \func{wxTreeItemId}{AppendItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 173  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 174
 175 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
 176
 177 The {\it image} and {\it selImage} parameters are an index within
 178 the normal image list specifying the image to use for unselected and
 179 selected items, respectively.
 180 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 181 both selected and unselected items.
 182
 183
 184 \membersection{wxTreeCtrl::AssignButtonsImageList}\label{wxtreectrlassignbuttonsimagelist}
 185
 186 \func{void}{AssignButtonsImageList}{\param{wxImageList*}{ imageList}}
 187
 188 Sets the buttons image list. The button images assigned with this method will
 189 be automatically deleted by wxTreeCtrl as appropriate
 190 (i.e. it takes ownership of the list).
 191
 192 Setting or assigning the button image list enables the display of image buttons.
 193 Once enabled, the only way to disable the display of button images is to set
 194 the button image list to {\tt NULL}.
 195
 196 This function is only available in the generic version.
 197
 198 See also \helpref{SetButtonsImageList}{wxtreectrlsetbuttonsimagelist}.
 199
 200
 201 \membersection{wxTreeCtrl::AssignImageList}\label{wxtreectrlassignimagelist}
 202
 203 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
 204
 205 Sets the normal image list. Image list assigned with this method will
 206 be automatically deleted by wxTreeCtrl as appropriate
 207 (i.e. it takes ownership of the list).
 208
 209 See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 210
 211
 212 \membersection{wxTreeCtrl::AssignStateImageList}\label{wxtreectrlassignstateimagelist}
 213
 214 \func{void}{AssignStateImageList}{\param{wxImageList*}{ imageList}}
 215
 216 Sets the state image list. Image list assigned with this method will
 217 be automatically deleted by wxTreeCtrl as appropriate
 218 (i.e. it takes ownership of the list).
 219
 220 See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
 221
 222
 223
 224 \membersection{wxTreeCtrl::Collapse}\label{wxtreectrlcollapse}
 225
 226 \func{void}{Collapse}{\param{const wxTreeItemId\&}{ item}}
 227
 228 Collapses the given item.
 229
 230
 231 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
 232
 233 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}
 234
 235 Collapses the given item and removes all children.
 236
 237
 238 \membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate}
 239
 240 \func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 241 \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 242 \param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}
 243
 244 Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details.
 245
 246
 247 \membersection{wxTreeCtrl::Delete}\label{wxtreectrldelete}
 248
 249 \func{void}{Delete}{\param{const wxTreeItemId\&}{ item}}
 250
 251 Deletes the specified item. A {\tt EVT\_TREE\_DELETE\_ITEM} event will be
 252 generated.
 253
 254 This function may cause a subsequent call to GetNextChild to fail.
 255
 256
 257 \membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems}
 258
 259 \func{void}{DeleteAllItems}{\void}
 260
 261 Deletes all the items in the control. Note that this may not generate
 262 {\tt EVT\_TREE\_DELETE\_ITEM} events under some Windows versions although
 263 normally such event is generated for each removed item.
 264
 265
 266 \membersection{wxTreeCtrl::DeleteChildren}\label{wxtreectrldeletechildren}
 267
 268 \func{void}{DeleteChildren}{\param{const wxTreeItemId\& }{item}}
 269
 270 Deletes all children of the given item (but not the item itself). Note that
 271 this will {\bf not} generate any events unlike
 272 \helpref{Delete}{wxtreectrldelete} method.
 273
 274 If you have called \helpref{wxTreeCtrl::SetItemHasChildren}{wxtreectrlsetitemhaschildren}, you
 275 may need to call it again since {\it DeleteChildren} does not automatically
 276 clear the setting.
 277
 278
 279 \membersection{wxTreeCtrl::EditLabel}\label{wxtreectrleditlabel}
 280
 281 \func{void}{EditLabel}{\param{const wxTreeItemId\&}{ item}}
 282
 283 Starts editing the label of the given item. This function generates a
 284 EVT\_TREE\_BEGIN\_LABEL\_EDIT event which can be vetoed so that no
 285 text control will appear for in-place editing.
 286
 287 If the user changed the label (i.e. s/he does not press ESC or leave
 288 the text control without changes, a EVT\_TREE\_END\_LABEL\_EDIT event
 289 will be sent which can be vetoed as well.
 290
 291 \wxheading{See also}
 292
 293 \helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel},
 294 \helpref{wxTreeEvent}{wxtreeevent}
 295
 296
 297 \membersection{wxTreeCtrl::EndEditLabel}\label{wxtreectrlendeditlabel}
 298
 299 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
 300
 301 Ends label editing. If {\it cancelEdit} is {\tt true}, the edit will be cancelled.
 302
 303 This function is currently supported under Windows only.
 304
 305 \wxheading{See also}
 306
 307 \helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}
 308
 309
 310 \membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible}
 311
 312 \func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}}
 313
 314 Scrolls and/or expands items to ensure that the given item is visible.
 315
 316
 317 \membersection{wxTreeCtrl::Expand}\label{wxtreectrlexpand}
 318
 319 \func{void}{Expand}{\param{const wxTreeItemId\&}{ item}}
 320
 321 Expands the given item.
 322
 323
 324 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
 325
 326 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = {\tt false}}}
 327
 328 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is {\tt true},
 329 only the rectangle around the item's label will be returned, otherwise the
 330 item's image is also taken into account.
 331
 332 The return value is {\tt true} if the rectangle was successfully retrieved or {\tt false}
 333 if it was not (in this case {\it rect} is not changed) - for example, if the
 334 item is currently invisible.
 335
 336 \pythonnote{The wxPython version of this method requires only the
 337 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 338 {\tt wxRect} object or {\tt None}.}
 339
 340 \perlnote{In wxPerl this method only takes the parameters {\tt item} and
 341   {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
 342
 343
 344 \membersection{wxTreeCtrl::GetButtonsImageList}\label{wxtreectrlgetbuttonsimagelist}
 345
 346 \constfunc{wxImageList*}{GetButtonsImageList}{\void}
 347
 348 Returns the buttons image list (from which application-defined button images are taken).
 349
 350 This function is only available in the generic version.
 351
 352
 353 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 354
 355 \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = {\tt true}}}
 356
 357 Returns the number of items in the branch. If {\it recursively} is {\tt true}, returns the total number
 358 of descendants, otherwise only one level of children is counted.
 359
 360
 361 \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
 362
 363 \constfunc{int}{GetCount}{\void}
 364
 365 Returns the number of items in the control.
 366
 367
 368 \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
 369
 370 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
 371
 372 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
 373 if no label is being edited.
 374
 375 {\bf NB:} It is currently only implemented for wxMSW.
 376
 377
 378 \membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
 379
 380 \constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 381
 382 Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
 383
 384 For this enumeration function you must pass in a `cookie' parameter
 385 which is opaque for the application but is necessary for the library
 386 to make these functions reentrant (i.e. allow more than one
 387 enumeration on one and the same object simultaneously). The cookie passed to
 388 GetFirstChild and GetNextChild should be the same variable.
 389
 390 Returns an invalid tree item (i.e. IsOk() returns {\tt false}) if there are no further children.
 391
 392 \wxheading{See also}
 393
 394 \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild},
 395 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 396
 397 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 398 value are both returned as a tuple containing the two values.}
 399
 400 \perlnote{In wxPerl this method only takes the {\tt item} parameter, and
 401   returns a 2-element list {\tt ( item, cookie )}.}
 402
 403
 404 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 405
 406 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
 407
 408 Returns the first visible item.
 409
 410
 411 \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
 412
 413 \constfunc{wxImageList*}{GetImageList}{\void}
 414
 415 Returns the normal image list.
 416
 417
 418 \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
 419
 420 \constfunc{int}{GetIndent}{\void}
 421
 422 Returns the current tree control indentation.
 423
 424
 425 \membersection{wxTreeCtrl::GetItemBackgroundColour}\label{wxtreectrlgetitembackgroundcolour}
 426
 427 \constfunc{wxColour}{GetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}}
 428
 429 Returns the background colour of the item.
 430
 431
 432 \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
 433
 434 \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
 435
 436 Returns the tree item data associated with the item.
 437
 438 \wxheading{See also}
 439
 440 \helpref{wxTreeItemData}{wxtreeitemdata}
 441
 442 \pythonnote{wxPython provides the following shortcut method:
 443
 444 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 445 \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
 446 associated with the wxTreeItemData for the given item Id.}
 447 \end{twocollist}}
 448 }%
 449
 450 \perlnote{wxPerl provides the following shortcut method:
 451 \indented{2cm}{
 452 \begin{twocollist}\itemsep=0pt
 453 \twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
 454 associated with the Wx::TreeItemData. It is just the same as
 455 tree->GetItemData(item)->GetData().}
 456 \end{twocollist}}
 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 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
 850
 851 \func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = {\tt true}}}
 852
 853 Gives the item the visual feedback for Drag'n'Drop actions, which is
 854 useful if something is dragged from the outside onto the tree control
 855 (as opposed to a DnD operation within the tree control, which already
 856 is implemented internally).
 857
 858 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 859
 860 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 861
 862 Sets the item's font. All items in the tree should have the same height to avoid
 863 text clipping, so the fonts height should be the same for all of them,
 864 although font attributes may vary.
 865
 866 \wxheading{See also}
 867
 868 \helpref{SetItemBold}{wxtreectrlsetitembold}
 869
 870
 871 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 872
 873 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
 874
 875 Force appearance of the button next to the item. This is useful to
 876 allow the user to expand the items which don't have any children now,
 877 but instead adding them only when needed, thus minimizing memory
 878 usage and loading time.
 879
 880
 881 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 882
 883 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 884  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 885
 886 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 887 for the description of the {\it which} parameter.
 888
 889
 890 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 891
 892 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 893
 894 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 895
 896
 897 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 898
 899 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 900
 901 Sets the item label.
 902
 903
 904 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 905
 906 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 907
 908 Sets the colour of the item's text.
 909
 910
 911 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 912
 913 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 914
 915 Sets the state image list (from which application-defined state images are taken).
 916 Image list assigned with this method will
 917 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 918
 919 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 920
 921 \membersection{wxTreeCtrl::SetWindowStyle}\label{wxtreectrlsetwindowstyle}
 922
 923 \func{void}{SetWindowStyle}{\param{long}{styles}}
 924
 925 Sets the mode flags associated with the display of the tree control.
 926 The new mode takes effect immediately.
 927 (Generic only; MSW ignores changes.)
 928
 929
 930 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 931
 932 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 933
 934 Sorts the children of the given item using
 935 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 936 should override that method to change the sort order (the default is ascending
 937 case-sensitive alphabetical order).
 938
 939 \wxheading{See also}
 940
 941 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 942
 943
 944 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 945
 946 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 947
 948 Toggles the given item between collapsed and expanded states.
 949
 950
 951 \membersection{wxTreeCtrl::ToggleItemSelection}\label{wxtreectrltoggleitemselection}
 952
 953 \func{void}{ToggleItemSelection}{\param{const wxTreeItemId\&}{ item}}
 954
 955 Toggles the given item between selected and unselected states. For
 956 multiselection controls only.
 957
 958
 959 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 960
 961 \func{void}{Unselect}{\void}
 962
 963 Removes the selection from the currently selected item (if any).
 964
 965
 966 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 967
 968 \func{void}{UnselectAll}{\void}
 969
 970 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 971 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 972 all items if it does have this style.
 973
 974
 975 \membersection{wxTreeCtrl::UnselectItem}\label{wxtreectrlunselectitem}
 976
 977 \func{void}{UnselectItem}{\param{const wxTreeItemId\& }{item}}
 978
 979 Unselects the given item. This works in multiselection controls only.
 980
 981