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