docs/latex/wx/ttreectl.tex

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