4e43c81518
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@37557 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
82 lines
4.9 KiB
TeX
82 lines
4.9 KiB
TeX
\section{wxTreeCtrl overview}\label{wxtreectrloverview}
|
|
|
|
Classes: \helpref{wxTreeCtrl}{wxtreectrl}, \helpref{wxImageList}{wximagelist}
|
|
|
|
The tree control displays its items in a tree like structure. Each item has its
|
|
own (optional) icon and a label. An item may be either collapsed (meaning that
|
|
its children are not visible) or expanded (meaning that its children are
|
|
shown). Each item in the tree is identified by its {\it itemId} which is of
|
|
opaque data type {\it wxTreeItemId}. You can test whether an item is valid
|
|
by calling wxTreeItemId::IsOk.
|
|
|
|
The items text and image may be retrieved and changed with
|
|
\helpref{GetItemText}{wxtreectrlgetitemtext}/\helpref{SetItemText}{wxtreectrlsetitemtext}
|
|
and
|
|
\helpref{GetItemImage}{wxtreectrlgetitemimage}/\helpref{SetItemImage}{wxtreectrlsetitemimage}.
|
|
In fact, an item may even have two images associated with it: the normal one
|
|
and another one for selected state which is set/retrieved with
|
|
\helpref{SetItemSelectedImage}{wxtreectrlsetitemselectedimage}/\helpref{GetItemSelectedImage}{wxtreectrlgetitemselectedimage}
|
|
functions, but this functionality might be unavailable on some platforms.
|
|
|
|
Tree items have several attributes: an item may be selected or not, visible or
|
|
not, bold or not. It may also be expanded or collapsed. All these attributes
|
|
may be retrieved with the corresponding functions:
|
|
\helpref{IsSelected}{wxtreectrlisselected},
|
|
\helpref{IsVisible}{wxtreectrlisvisible}, \helpref{IsBold}{wxtreectrlisbold}
|
|
and \helpref{IsExpanded}{wxtreectrlisexpanded}. Only one item at a time may be
|
|
selected, selecting another one (with
|
|
\helpref{SelectItem}{wxtreectrlselectitem}) automatically unselects the
|
|
previously selected one.
|
|
|
|
In addition to its icon and label, a user-specific data structure may be associated
|
|
with all tree items. If you wish to do it, you should derive a class from {\it
|
|
wxTreeItemData} which is a very simple class having only one function {\it
|
|
GetId()} which returns the id of the item this data is associated with. This
|
|
data will be freed by the control itself when the associated item is deleted
|
|
(all items are deleted when the control is destroyed), so you shouldn't delete
|
|
it yourself (if you do it, you should call
|
|
\helpref{SetItemData(NULL)}{wxtreectrlsetitemdata} to prevent the tree from
|
|
deleting the pointer second time). The associated data may be retrieved with
|
|
\helpref{GetItemData()}{wxtreectrlgetitemdata} function.
|
|
|
|
Working with trees is relatively straightforward if all the items are added to
|
|
the tree at the moment of its creation. However, for large trees it may be
|
|
very inefficient. To improve the performance you may want to delay adding the
|
|
items to the tree until the branch containing the items is expanded: so, in the
|
|
beginning, only the root item is created (with
|
|
\helpref{AddRoot}{wxtreectrladdroot}). Other items are added when
|
|
EVT\_TREE\_ITEM\_EXPANDING event is received: then all items lying immediately
|
|
under the item being expanded should be added, but, of course, only when this
|
|
event is received for the first time for this item - otherwise, the items would
|
|
be added twice if the user expands/collapses/re-expands the branch.
|
|
|
|
The tree control provides functions for enumerating its items. There are 3
|
|
groups of enumeration functions: for the children of a given item, for the
|
|
sibling of the given item and for the visible items (those which are currently
|
|
shown to the user: an item may be invisible either because its branch is
|
|
collapsed or because it is scrolled out of view). Child enumeration functions
|
|
require the caller to give them a {\it cookie} parameter: it is a number which
|
|
is opaque to the caller but is used by the tree control itself to allow
|
|
multiple enumerations to run simultaneously (this is explicitly allowed). The
|
|
only thing to remember is that the {\it cookie} passed to
|
|
\helpref{GetFirstChild}{wxtreectrlgetfirstchild} and to
|
|
\helpref{GetNextChild}{wxtreectrlgetnextchild} should be the same variable (and
|
|
that nothing should be done with it by the user code).
|
|
|
|
Among other features of the tree control are: item sorting with
|
|
\helpref{SortChildren}{wxtreectrlsortchildren} which uses the user-defined comparison
|
|
function \helpref{OnCompareItems}{wxtreectrloncompareitems} (by default the
|
|
comparison is the alphabetic comparison of tree labels), hit testing
|
|
(determining to which portion of the control the given point belongs, useful
|
|
for implementing drag-and-drop in the tree) with
|
|
\helpref{HitTest}{wxtreectrlhittest} and editing of the tree item labels in
|
|
place (see \helpref{EditLabel}{wxtreectrleditlabel}).
|
|
|
|
Finally, the tree control has a keyboard interface: the cursor navigation (arrow) keys
|
|
may be used to change the current selection. <HOME> and <END> are used to go to
|
|
the first/last sibling of the current item. '+', '-' and '*' expand, collapse
|
|
and toggle the current branch. Note, however, that <DEL> and <INS> keys do
|
|
nothing by default, but it is common to associate them with deleting an item from
|
|
a tree and inserting a new one into it.
|
|
|