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