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