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