docs/doxygen/overviews/treectrl.h

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