docs/doxygen/overviews/treectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treectrl.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_treectrl wxTreeCtrl Overview
  12
  13 @tableofcontents
  14
  15 The tree control displays its items in a tree like structure. Each item has
  16 its own (optional) icon and a label. An item may be either collapsed (meaning
  17 that its children are not visible) or expanded (meaning that its children are
  18 shown). Each item in the tree is identified by its @c itemId which is of opaque
  19 data type wxTreeItemId. You can test whether an item is valid by calling
  20 wxTreeItemId::IsOk.
  21
  22 @see wxTreeCtrl, wxImageList
  23
  24 The items text and image may be retrieved and changed with (Get|Set)ItemText
  25 and (Get|Set)ItemImage. In fact, an item may even have two images associated
  26 with it: the normal one and another one for selected state which is
  27 set/retrieved with (Get|Set)ItemSelectedImage functions, but this functionality
  28 might be unavailable on some platforms.
  29
  30 Tree items have several attributes: an item may be selected or not, visible or
  31 not, bold or not. It may also be expanded or collapsed. All these attributes
  32 may be retrieved with the corresponding functions: IsSelected, IsVisible,
  33 IsBold and IsExpanded. Only one item at a time may be selected, selecting
  34 another one (with SelectItem) automatically unselects the previously selected
  35 one.
  36
  37 In addition to its icon and label, a user-specific data structure may be
  38 associated with all tree items. If you wish to do it, you should derive a class
  39 from wxTreeItemData which is a very simple class having only one function
  40 GetId() which returns the id of the item this data is associated with. This
  41 data will be freed by the control itself when the associated item is deleted
  42 (all items are deleted when the control is destroyed), so you shouldn't delete
  43 it yourself (if you do it, you should call SetItemData(@NULL) to prevent the
  44 tree from deleting the pointer second time). The associated data may be
  45 retrieved with GetItemData() function.
  46
  47 Working with trees is relatively straightforward if all the items are added to
  48 the tree at the moment of its creation. However, for large trees it may be
  49 very inefficient. To improve the performance you may want to delay adding the
  50 items to the tree until the branch containing the items is expanded: so, in the
  51 beginning, only the root item is created (with AddRoot). Other items are added
  52 when EVT_TREE_ITEM_EXPANDING event is received: then all items lying
  53 immediately under the item being expanded should be added, but, of course, only
  54 when this event is received for the first time for this item - otherwise, the
  55 items would be added twice if the user expands/collapses/re-expands the branch.
  56
  57 The tree control provides functions for enumerating its items. There are 3
  58 groups of enumeration functions: for the children of a given item, for the
  59 sibling of the given item and for the visible items (those which are currently
  60 shown to the user: an item may be invisible either because its branch is
  61 collapsed or because it is scrolled out of view). Child enumeration functions
  62 require the caller to give them a @e cookie parameter: it is a number which
  63 is opaque to the caller but is used by the tree control itself to allow
  64 multiple enumerations to run simultaneously (this is explicitly allowed). The
  65 only thing to remember is that the @e cookie passed to GetFirstChild and to
  66 GetNextChild should be the same variable (and that nothing should be done with
  67 it by the user code).
  68
  69 Among other features of the tree control are: item sorting with SortChildren
  70 which uses the user-defined comparison function OnCompareItems (by default the
  71 comparison is the alphabetic comparison of tree labels), hit testing
  72 (determining to which portion of the control the given point belongs, useful
  73 for implementing drag-and-drop in the tree) with HitTest and editing of the
  74 tree item labels in place (see EditLabel).
  75
  76 Finally, the tree control has a keyboard interface: the cursor navigation
  77 (arrow) keys may be used to change the current selection. HOME and END are used
  78 to go to the first/last sibling of the current item. '+', '-' and '*' expand,
  79 collapse and toggle the current branch. Note, however, that DEL and INS keys do
  80 nothing by default, but it is common to associate them with deleting an item
  81 from a tree and inserting a new one into it.
  82
  83 */