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 \pythonnote{The wxPython version of this method requires only the
 347 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 348 {\tt wxRect} object or {\tt None}.}
 349
 350 \perlnote{In wxPerl this method only takes the parameters {\tt item} and
 351   {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
 352
 353
 354 \membersection{wxTreeCtrl::GetButtonsImageList}\label{wxtreectrlgetbuttonsimagelist}
 355
 356 \constfunc{wxImageList*}{GetButtonsImageList}{\void}
 357
 358 Returns the buttons image list (from which application-defined button images are taken).
 359
 360 This function is only available in the generic version.
 361
 362
 363 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 364
 365 \constfunc{unsigned int}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = {\tt true}}}
 366
 367 Returns the number of items in the branch. If {\it recursively} is {\tt true}, returns the total number
 368 of descendants, otherwise only one level of children is counted.
 369
 370
 371 \membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}
 372
 373 \constfunc{unsigned int}{GetCount}{\void}
 374
 375 Returns the number of items in the control.
 376
 377
 378 \membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}
 379
 380 \constfunc{wxTextCtrl *}{GetEditControl}{\void}
 381
 382 Returns the edit control being currently used to edit a label. Returns {\tt NULL}
 383 if no label is being edited.
 384
 385 {\bf NB:} It is currently only implemented for wxMSW.
 386
 387
 388 \membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}
 389
 390 \constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 391
 392 Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.
 393
 394 For this enumeration function you must pass in a `cookie' parameter
 395 which is opaque for the application but is necessary for the library
 396 to make these functions reentrant (i.e. allow more than one
 397 enumeration on one and the same object simultaneously). The cookie passed to
 398 GetFirstChild and GetNextChild should be the same variable.
 399
 400 Returns an invalid tree item (i.e. IsOk() returns {\tt false}) if there are no further children.
 401
 402 \wxheading{See also}
 403
 404 \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild},
 405 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 406
 407 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 408 value are both returned as a tuple containing the two values.}
 409
 410 \perlnote{In wxPerl this method only takes the {\tt item} parameter, and
 411   returns a 2-element list {\tt ( item, cookie )}.}
 412
 413
 414 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 415
 416 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
 417
 418 Returns the first visible item.
 419
 420
 421 \membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}
 422
 423 \constfunc{wxImageList*}{GetImageList}{\void}
 424
 425 Returns the normal image list.
 426
 427
 428 \membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}
 429
 430 \constfunc{int}{GetIndent}{\void}
 431
 432 Returns the current tree control indentation.
 433
 434
 435 \membersection{wxTreeCtrl::GetItemBackgroundColour}\label{wxtreectrlgetitembackgroundcolour}
 436
 437 \constfunc{wxColour}{GetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}}
 438
 439 Returns the background colour of the item.
 440
 441
 442 \membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}
 443
 444 \constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}
 445
 446 Returns the tree item data associated with the item.
 447
 448 \wxheading{See also}
 449
 450 \helpref{wxTreeItemData}{wxtreeitemdata}
 451
 452 \pythonnote{wxPython provides the following shortcut method:
 453
 454 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 455 \twocolitem{{\bf GetPyData(item)}}{Returns the Python Object
 456 associated with the wxTreeItemData for the given item Id.}
 457 \end{twocollist}}
 458 }%
 459
 460 \perlnote{wxPerl provides the following shortcut method:
 461 \indented{2cm}{
 462 \begin{twocollist}\itemsep=0pt
 463 \twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
 464 associated with the Wx::TreeItemData. It is just the same as
 465 tree->GetItemData(item)->GetData().}
 466 \end{twocollist}}
 467 }%
 468
 469 \membersection{wxTreeCtrl::GetItemFont}\label{wxtreectrlgetitemfont}
 470
 471 \constfunc{wxFont}{GetItemFont}{\param{const wxTreeItemId\&}{ item}}
 472
 473 Returns the font of the item label.
 474
 475
 476 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 477
 478 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
 479  \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 480
 481 Gets the specified item image. The value of {\it which} may be:
 482
 483 \begin{itemize}\itemsep=0pt
 484 \item{wxTreeItemIcon\_Normal} to get the normal item image
 485 \item{wxTreeItemIcon\_Selected} to get the selected item image (i.e. the image
 486 which is shown when the item is currently selected)
 487 \item{wxTreeItemIcon\_Expanded} to get the expanded image (this only
 488 makes sense for items which have children - then this image is shown when the
 489 item is expanded and the normal image is shown when it is collapsed)
 490 \item{wxTreeItemIcon\_SelectedExpanded} to get the selected expanded image
 491 (which is shown when an expanded item is currently selected)
 492 \end{itemize}
 493
 494
 495 \membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}
 496
 497 \constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}
 498
 499 Returns the item label.
 500
 501
 502 \membersection{wxTreeCtrl::GetItemTextColour}\label{wxtreectrlgetitemtextcolour}
 503
 504 \constfunc{wxColour}{GetItemTextColour}{\param{const wxTreeItemId\&}{ item}}
 505
 506 Returns the colour of the item label.
 507
 508
 509 \membersection{wxTreeCtrl::GetLastChild}\label{wxtreectrlgetlastchild}
 510
 511 \constfunc{wxTreeItemId}{GetLastChild}{\param{const wxTreeItemId\&}{ item}}
 512
 513 Returns the last child of the item (or an invalid tree item if this item has no children).
 514
 515 \wxheading{See also}
 516
 517 \helpref{GetFirstChild}{wxtreectrlgetfirstchild},
 518 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling},
 519 \helpref{GetLastChild}{wxtreectrlgetlastchild}
 520
 521
 522 \membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}
 523
 524 \constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemIdValue \& }{cookie}}
 525
 526 Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.
 527
 528 For this enumeration function you must pass in a `cookie' parameter
 529 which is opaque for the application but is necessary for the library
 530 to make these functions reentrant (i.e. allow more than one
 531 enumeration on one and the same object simultaneously). The cookie passed to
 532 GetFirstChild and GetNextChild should be the same.
 533
 534 Returns an invalid tree item if there are no further children.
 535
 536 \wxheading{See also}
 537
 538 \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}
 539
 540 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 541 value are both returned as a tuple containing the two values.}
 542
 543 \perlnote{In wxPerl this method returns a 2-element list
 544   {\tt ( item, cookie )}, instead of modifying its parameters.}
 545
 546
 547 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 548
 549 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
 550
 551 Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.
 552
 553 Returns an invalid tree item if there are no further siblings.
 554
 555 \wxheading{See also}
 556
 557 \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}
 558
 559
 560 \membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}
 561
 562 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 563
 564 Returns the next visible item.
 565
 566
 567 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}
 568
 569 \constfunc{wxTreeItemId}{GetItemParent}{\param{const wxTreeItemId\&}{ item}}
 570
 571 Returns the item's parent.
 572
 573
 574 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
 575
 576 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
 577
 578 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
 579
 580 Returns an invalid tree item if there are no further children.
 581
 582 \wxheading{See also}
 583
 584 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 585
 586
 587 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
 588
 589 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 590
 591 Returns the previous visible item.
 592
 593
 594 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
 595
 596 \constfunc{wxTreeItemId}{GetRootItem}{\void}
 597
 598 Returns the root item for the tree control.
 599
 600
 601 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
 602
 603 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 604
 605 Gets the selected item image (this function is obsolete, use
 606 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 607
 608
 609 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
 610
 611 \constfunc{wxTreeItemId}{GetSelection}{\void}
 612
 613 Returns the selection, or an invalid item if there is no selection.
 614 This function only works with the controls without wxTR\_MULTIPLE style, use
 615 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
 616 this style.
 617
 618
 619 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
 620
 621 \constfunc{unsigned int}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
 622
 623 Fills the array of tree items passed in with the currently selected items. This
 624 function can be called only if the control has the wxTR\_MULTIPLE style.
 625
 626 Returns the number of selected items.
 627
 628 \pythonnote{The wxPython version of this method accepts no parameters
 629 and returns a Python list of {\tt wxTreeItemId}s.}
 630
 631 \perlnote{In wxPerl this method takes no parameters and returns a list of
 632  {\tt Wx::TreeItemId}s.}
 633
 634
 635 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 636
 637 \constfunc{wxImageList*}{GetStateImageList}{\void}
 638
 639 Returns the state image list (from which application-defined state images are taken).
 640
 641
 642 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
 643
 644 \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 645
 646 Calculates which (if any) item is under the given point, returning the tree item
 647 id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
 648
 649 \twocolwidtha{5cm}
 650 \begin{twocollist}\itemsep=0pt
 651 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
 652 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
 653 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 654 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
 655 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 656 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
 657 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 658 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 659 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 660 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
 661 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
 662 \end{twocollist}
 663
 664 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 665 returned as a tuple.}
 666
 667 \perlnote{In wxPerl this method only takes the {\tt point} parameter
 668   and returns a 2-element list {\tt ( item, flags )}.}
 669
 670
 671 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 672
 673 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 674  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 675
 676 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 677  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 678
 679 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 680 {\it before} must be less than the number of children.
 681
 682 The {\it image} and {\it selImage} parameters are an index within
 683 the normal image list specifying the image to use for unselected and
 684 selected items, respectively.
 685 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 686 both selected and unselected items.
 687
 688 \pythonnote{The second form of this method is called
 689 {\tt InsertItemBefore} in wxPython.}
 690
 691
 692 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 693
 694 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 695
 696 Returns {\tt true} if the given item is in bold state.
 697
 698 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 699
 700
 701 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 702
 703 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 704
 705 Returns {\tt true} if the item is expanded (only makes sense if it has children).
 706
 707
 708 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 709
 710 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 711
 712 Returns {\tt true} if the item is selected.
 713
 714
 715 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 716
 717 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 718
 719 Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
 720
 721
 722 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 723
 724 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 725
 726 Returns {\tt true} if the item has children.
 727
 728
 729 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 730
 731 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 732
 733 Override this function in the derived class to change the sort order of the
 734 items in the tree control. The function should return a negative, zero or
 735 positive value if the first item is less than, equal to or greater than the
 736 second one.
 737
 738 The base class version compares items alphabetically.
 739
 740 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 741
 742
 743 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 744
 745 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 746  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 747
 748 Appends an item as the first child of {\it parent}, return a new item id.
 749
 750 The {\it image} and {\it selImage} parameters are an index within
 751 the normal image list specifying the image to use for unselected and
 752 selected items, respectively.
 753 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 754 both selected and unselected items.
 755
 756
 757 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 758
 759 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 760
 761 Scrolls the specified item into view.
 762
 763
 764 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 765
 766 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}, \param{bool }{select = \true}}
 767
 768 Selects the given item. In multiple selection controls, can be also used to
 769 deselect a currently selected item if the value of \arg{select} is false.
 770
 771
 772 \membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
 773
 774 \func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
 775
 776 Sets the buttons image list (from which application-defined button images are taken).
 777 The button images assigned with this method will
 778 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 779
 780 Setting or assigning the button image list enables the display of image buttons.
 781 Once enabled, the only way to disable the display of button images is to set
 782 the button image list to {\tt NULL}.
 783
 784 This function is only available in the generic version.
 785
 786 See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
 787
 788
 789 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 790
 791 \func{void}{SetIndent}{\param{int }{indent}}
 792
 793 Sets the indentation for the tree control.
 794
 795
 796 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 797
 798 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 799
 800 Sets the normal image list. Image list assigned with this method will
 801 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 802
 803 See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 804
 805
 806
 807 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 808
 809 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 810
 811 Sets the colour of the item's background.
 812
 813
 814 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 815
 816 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
 817
 818 Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
 819 the normal state.
 820
 821 See also: \helpref{IsBold}{wxtreectrlisbold}
 822
 823
 824 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 825
 826 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 827
 828 Sets the item client data.
 829
 830 \pythonnote{wxPython provides the following shortcut method:\par
 831 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 832 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 833 Object with the wxTreeItemData for the given item Id.}
 834 \end{twocollist}}
 835 }%
 836
 837 \perlnote{wxPerl provides the following shortcut method:
 838 \indented{2cm}{
 839 \begin{twocollist}\itemsep=0pt
 840 \twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
 841 associated with the Wx::TreeItemData. It is just the same as
 842 tree->GetItemData(item)->SetData(data).}
 843 \end{twocollist}}
 844 }%
 845
 846 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
 847
 848 \func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = {\tt true}}}
 849
 850 Gives the item the visual feedback for Drag'n'Drop actions, which is
 851 useful if something is dragged from the outside onto the tree control
 852 (as opposed to a DnD operation within the tree control, which already
 853 is implemented internally).
 854
 855 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 856
 857 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 858
 859 Sets the item's font. All items in the tree should have the same height to avoid
 860 text clipping, so the fonts height should be the same for all of them,
 861 although font attributes may vary.
 862
 863 \wxheading{See also}
 864
 865 \helpref{SetItemBold}{wxtreectrlsetitembold}
 866
 867
 868 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 869
 870 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
 871
 872 Force appearance of the button next to the item. This is useful to
 873 allow the user to expand the items which don't have any children now,
 874 but instead adding them only when needed, thus minimizing memory
 875 usage and loading time.
 876
 877
 878 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 879
 880 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 881  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 882
 883 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 884 for the description of the {\it which} parameter.
 885
 886
 887 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 888
 889 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 890
 891 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 892
 893
 894 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 895
 896 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 897
 898 Sets the item label.
 899
 900
 901 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 902
 903 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 904
 905 Sets the colour of the item's text.
 906
 907
 908 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 909
 910 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 911
 912 Sets the state image list (from which application-defined state images are taken).
 913 Image list assigned with this method will
 914 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 915
 916 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 917
 918 \membersection{wxTreeCtrl::SetWindowStyle}\label{wxtreectrlsetwindowstyle}
 919
 920 \func{void}{SetWindowStyle}{\param{long}{styles}}
 921
 922 Sets the mode flags associated with the display of the tree control.
 923 The new mode takes effect immediately.
 924 (Generic only; MSW ignores changes.)
 925
 926
 927 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 928
 929 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 930
 931 Sorts the children of the given item using
 932 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 933 should override that method to change the sort order (the default is ascending
 934 case-sensitive alphabetical order).
 935
 936 \wxheading{See also}
 937
 938 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 939
 940
 941 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 942
 943 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 944
 945 Toggles the given item between collapsed and expanded states.
 946
 947
 948 \membersection{wxTreeCtrl::ToggleItemSelection}\label{wxtreectrltoggleitemselection}
 949
 950 \func{void}{ToggleItemSelection}{\param{const wxTreeItemId\&}{ item}}
 951
 952 Toggles the given item between selected and unselected states. For
 953 multiselection controls only.
 954
 955
 956 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 957
 958 \func{void}{Unselect}{\void}
 959
 960 Removes the selection from the currently selected item (if any).
 961
 962
 963 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 964
 965 \func{void}{UnselectAll}{\void}
 966
 967 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 968 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 969 all items if it does have this style.
 970
 971
 972 \membersection{wxTreeCtrl::UnselectItem}\label{wxtreectrlunselectitem}
 973
 974 \func{void}{UnselectItem}{\param{const wxTreeItemId\& }{item}}
 975
 976 Unselects the given item. This works in multiselection controls only.