| 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 another 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/re-expands 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 features 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 usual to associate them with deleting item from |
| 79 | a tree and inserting a new one into it. |
| 80 | |