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::GetParent}\label{wxtreectrlgetparent}
 575
 576 \constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}
 577
 578 {\bf NOTE:} This function is deprecated and will only work if {\tt WXWIN\_COMPATIBILITY\_2\_2}
 579 is defined.  Use \helpref{wxTreeCtrl::GetItemParent}{wxtreectrlgetitemparent} instead.
 580
 581 Returns the item's parent.
 582
 583 \pythonnote{This method is named {\tt GetItemParent} to avoid a name
 584 clash with wxWindow::GetParent.}
 585
 586
 587 \membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}
 588
 589 \constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}
 590
 591 Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.
 592
 593 Returns an invalid tree item if there are no further children.
 594
 595 \wxheading{See also}
 596
 597 \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}
 598
 599
 600 \membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}
 601
 602 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 603
 604 Returns the previous visible item.
 605
 606
 607 \membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}
 608
 609 \constfunc{wxTreeItemId}{GetRootItem}{\void}
 610
 611 Returns the root item for the tree control.
 612
 613
 614 \membersection{wxTreeCtrl::GetItemSelectedImage}\label{wxtreectrlgetitemselectedimage}
 615
 616 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 617
 618 Gets the selected item image (this function is obsolete, use
 619 {\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 620
 621
 622 \membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}
 623
 624 \constfunc{wxTreeItemId}{GetSelection}{\void}
 625
 626 Returns the selection, or an invalid item if there is no selection.
 627 This function only works with the controls without wxTR\_MULTIPLE style, use
 628 \helpref{GetSelections}{wxtreectrlgetselections} for the controls which do have
 629 this style.
 630
 631
 632 \membersection{wxTreeCtrl::GetSelections}\label{wxtreectrlgetselections}
 633
 634 \constfunc{unsigned int}{GetSelections}{\param{wxArrayTreeItemIds\& }{selection}}
 635
 636 Fills the array of tree items passed in with the currently selected items. This
 637 function can be called only if the control has the wxTR\_MULTIPLE style.
 638
 639 Returns the number of selected items.
 640
 641 \pythonnote{The wxPython version of this method accepts no parameters
 642 and returns a Python list of {\tt wxTreeItemId}s.}
 643
 644 \perlnote{In wxPerl this method takes no parameters and returns a list of
 645  {\tt Wx::TreeItemId}s.}
 646
 647
 648 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 649
 650 \constfunc{wxImageList*}{GetStateImageList}{\void}
 651
 652 Returns the state image list (from which application-defined state images are taken).
 653
 654
 655 \membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}
 656
 657 \func{wxTreeItemId}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}
 658
 659 Calculates which (if any) item is under the given point, returning the tree item
 660 id at this point plus extra information {\it flags}. {\it flags} is a bitlist of the following:
 661
 662 \twocolwidtha{5cm}
 663 \begin{twocollist}\itemsep=0pt
 664 \twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
 665 \twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
 666 \twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
 667 \twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
 668 \twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
 669 \twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
 670 \twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
 671 \twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
 672 \twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
 673 \twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
 674 \twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
 675 \end{twocollist}
 676
 677 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 678 returned as a tuple.}
 679
 680 \perlnote{In wxPerl this method only takes the {\tt point} parameter
 681   and returns a 2-element list {\tt ( item, flags )}.}
 682
 683
 684 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 685
 686 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 687  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 688
 689 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{size\_t}{ before}, \param{const wxString\&}{ text},
 690  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 691
 692 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 693 {\it before} must be less than the number of children.
 694
 695 The {\it image} and {\it selImage} parameters are an index within
 696 the normal image list specifying the image to use for unselected and
 697 selected items, respectively.
 698 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 699 both selected and unselected items.
 700
 701 \pythonnote{The second form of this method is called
 702 {\tt InsertItemBefore} in wxPython.}
 703
 704
 705 \membersection{wxTreeCtrl::IsBold}\label{wxtreectrlisbold}
 706
 707 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 708
 709 Returns {\tt true} if the given item is in bold state.
 710
 711 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 712
 713
 714 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 715
 716 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 717
 718 Returns {\tt true} if the item is expanded (only makes sense if it has children).
 719
 720
 721 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 722
 723 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 724
 725 Returns {\tt true} if the item is selected.
 726
 727
 728 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 729
 730 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 731
 732 Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
 733
 734
 735 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 736
 737 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 738
 739 Returns {\tt true} if the item has children.
 740
 741
 742 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 743
 744 \func{int}{OnCompareItems}{\param{const wxTreeItemId\& }{item1}, \param{const wxTreeItemId\& }{item2}}
 745
 746 Override this function in the derived class to change the sort order of the
 747 items in the tree control. The function should return a negative, zero or
 748 positive value if the first item is less than, equal to or greater than the
 749 second one.
 750
 751 The base class version compares items alphabetically.
 752
 753 See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 754
 755
 756 \membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}
 757
 758 \func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 759  \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = {\tt NULL}}}
 760
 761 Appends an item as the first child of {\it parent}, return a new item id.
 762
 763 The {\it image} and {\it selImage} parameters are an index within
 764 the normal image list specifying the image to use for unselected and
 765 selected items, respectively.
 766 If {\it image} > -1 and {\it selImage} is -1, the same image is used for
 767 both selected and unselected items.
 768
 769
 770 \membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}
 771
 772 \func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}
 773
 774 Scrolls the specified item into view.
 775
 776
 777 \membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}
 778
 779 \func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}, \param{bool }{select = \true}}
 780
 781 Selects the given item. In multiple selection controls, can be also used to
 782 deselect a currently selected item if the value of \arg{select} is false.
 783
 784
 785 \membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
 786
 787 \func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
 788
 789 Sets the buttons image list (from which application-defined button images are taken).
 790 The button images assigned with this method will
 791 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 792
 793 Setting or assigning the button image list enables the display of image buttons.
 794 Once enabled, the only way to disable the display of button images is to set
 795 the button image list to {\tt NULL}.
 796
 797 This function is only available in the generic version.
 798
 799 See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
 800
 801
 802 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 803
 804 \func{void}{SetIndent}{\param{int }{indent}}
 805
 806 Sets the indentation for the tree control.
 807
 808
 809 \membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}
 810
 811 \func{void}{SetImageList}{\param{wxImageList*}{ imageList}}
 812
 813 Sets the normal image list. Image list assigned with this method will
 814 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 815
 816 See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 817
 818
 819
 820 \membersection{wxTreeCtrl::SetItemBackgroundColour}\label{wxtreectrlsetitembackgroundcolour}
 821
 822 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 823
 824 Sets the colour of the item's background.
 825
 826
 827 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 828
 829 \func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
 830
 831 Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
 832 the normal state.
 833
 834 See also: \helpref{IsBold}{wxtreectrlisbold}
 835
 836
 837 \membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}
 838
 839 \func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}
 840
 841 Sets the item client data.
 842
 843 \pythonnote{wxPython provides the following shortcut method:\par
 844 \indented{2cm}{\begin{twocollist}\itemsep=0pt
 845 \twocolitem{{\bf SetPyData(item, obj)}}{Associate the given Python
 846 Object with the wxTreeItemData for the given item Id.}
 847 \end{twocollist}}
 848 }%
 849
 850 \perlnote{wxPerl provides the following shortcut method:
 851 \indented{2cm}{
 852 \begin{twocollist}\itemsep=0pt
 853 \twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
 854 associated with the Wx::TreeItemData. It is just the same as
 855 tree->GetItemData(item)->SetData(data).}
 856 \end{twocollist}}
 857 }%
 858
 859 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
 860
 861 \func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = {\tt true}}}
 862
 863 Gives the item the visual feedback for Drag'n'Drop actions, which is
 864 useful if something is dragged from the outside onto the tree control
 865 (as opposed to a DnD operation within the tree control, which already
 866 is implemented internally).
 867
 868 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 869
 870 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 871
 872 Sets the item's font. All items in the tree should have the same height to avoid
 873 text clipping, so the fonts height should be the same for all of them,
 874 although font attributes may vary.
 875
 876 \wxheading{See also}
 877
 878 \helpref{SetItemBold}{wxtreectrlsetitembold}
 879
 880
 881 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 882
 883 \func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
 884
 885 Force appearance of the button next to the item. This is useful to
 886 allow the user to expand the items which don't have any children now,
 887 but instead adding them only when needed, thus minimizing memory
 888 usage and loading time.
 889
 890
 891 \membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}
 892
 893 \func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item},
 894  \param{int }{image}, \param{wxTreeItemIcon }{which = wxTreeItemIcon\_Normal}}
 895
 896 Sets the specified item image. See \helpref{GetItemImage}{wxtreectrlgetitemimage}
 897 for the description of the {\it which} parameter.
 898
 899
 900 \membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}
 901
 902 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 903
 904 Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
 905
 906
 907 \membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}
 908
 909 \func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}
 910
 911 Sets the item label.
 912
 913
 914 \membersection{wxTreeCtrl::SetItemTextColour}\label{wxtreectrlsetitemtextcolour}
 915
 916 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 917
 918 Sets the colour of the item's text.
 919
 920
 921 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 922
 923 \func{void}{SetStateImageList}{\param{wxImageList*}{ imageList}}
 924
 925 Sets the state image list (from which application-defined state images are taken).
 926 Image list assigned with this method will
 927 {\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
 928
 929 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 930
 931 \membersection{wxTreeCtrl::SetWindowStyle}\label{wxtreectrlsetwindowstyle}
 932
 933 \func{void}{SetWindowStyle}{\param{long}{styles}}
 934
 935 Sets the mode flags associated with the display of the tree control.
 936 The new mode takes effect immediately.
 937 (Generic only; MSW ignores changes.)
 938
 939
 940 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 941
 942 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 943
 944 Sorts the children of the given item using
 945 \helpref{OnCompareItems}{wxtreectrloncompareitems} method of wxTreeCtrl. You
 946 should override that method to change the sort order (the default is ascending
 947 case-sensitive alphabetical order).
 948
 949 \wxheading{See also}
 950
 951 \helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{OnCompareItems}{wxtreectrloncompareitems}
 952
 953
 954 \membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}
 955
 956 \func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}
 957
 958 Toggles the given item between collapsed and expanded states.
 959
 960
 961 \membersection{wxTreeCtrl::ToggleItemSelection}\label{wxtreectrltoggleitemselection}
 962
 963 \func{void}{ToggleItemSelection}{\param{const wxTreeItemId\&}{ item}}
 964
 965 Toggles the given item between selected and unselected states. For
 966 multiselection controls only.
 967
 968
 969 \membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}
 970
 971 \func{void}{Unselect}{\void}
 972
 973 Removes the selection from the currently selected item (if any).
 974
 975
 976 \membersection{wxTreeCtrl::UnselectAll}\label{wxtreectrlunselectall}
 977
 978 \func{void}{UnselectAll}{\void}
 979
 980 This function either behaves the same as \helpref{Unselect}{wxtreectrlunselect}
 981 if the control doesn't have wxTR\_MULTIPLE style, or removes the selection from
 982 all items if it does have this style.
 983
 984
 985 \membersection{wxTreeCtrl::UnselectItem}\label{wxtreectrlunselectitem}
 986
 987 \func{void}{UnselectItem}{\param{const wxTreeItemId\& }{item}}
 988
 989 Unselects the given item. This works in multiselection controls only.