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