docs/latex/wx/treectrl.tex

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