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