X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7fa3c420464f94c80f01d3044817c8b47ae9b033..53ff8df7d54cd427674fc9bffb748c8872c0d658:/docs/doxygen/overviews/treectrl.h diff --git a/docs/doxygen/overviews/treectrl.h b/docs/doxygen/overviews/treectrl.h index 4a3f07300a..9c18df9f33 100644 --- a/docs/doxygen/overviews/treectrl.h +++ b/docs/doxygen/overviews/treectrl.h @@ -1,92 +1,82 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: treectrl +// Name: treectrl.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! +/** - @page overview_treectrl wxTreeCtrl overview +@page overview_treectrl wxTreeCtrl Overview - Classes: #wxTreeCtrl, #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 @e itemId which is of - opaque data type @e wxTreeItemId. You can test whether an item is valid - by calling wxTreeItemId::IsOk. +Classes: wxTreeCtrl, wxImageList - The items text and image may be retrieved and changed with - #GetItemText/#SetItemText - and - #GetItemImage/#SetItemImage. - 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 - #SetItemSelectedImage/#GetItemSelectedImage - functions, but this functionality might be unavailable on some platforms. +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 @c itemId which is of opaque +data type wxTreeItemId. You can test whether an item is valid by calling +wxTreeItemId::IsOk. - 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: - #IsSelected, - #IsVisible, #IsBold - and #IsExpanded. Only one item at a time may be - selected, selecting another one (with - #SelectItem) automatically unselects the - previously selected one. +The items text and image may be retrieved and changed with (Get|Set)ItemText +and (Get|Set)ItemImage. 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 (Get|Set)ItemSelectedImage functions, but this functionality +might be unavailable on some platforms. - 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 @e wxTreeItemData which is a very simple class having only one function @e 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 - #SetItemData(@NULL) to prevent the tree from - deleting the pointer second time). The associated data may be retrieved with - #GetItemData() function. +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: IsSelected, IsVisible, +IsBold and IsExpanded. Only one item at a time may be selected, selecting +another one (with SelectItem) automatically unselects the previously selected +one. - 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 - #AddRoot). 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. +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 wxTreeItemData which is a very simple class having only one function +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 SetItemData(@NULL) to prevent the +tree from deleting the pointer second time). The associated data may be +retrieved with GetItemData() function. - 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 @e 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 @e cookie passed to - #GetFirstChild and to - #GetNextChild should be the same variable (and - that nothing should be done with it by the user code). +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 AddRoot). 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. - Among other features of the tree control are: item sorting with - #SortChildren which uses the user-defined comparison - function #OnCompareItems (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 - #HitTest and editing of the tree item labels in - place (see #EditLabel). +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 @e 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 @e cookie passed to GetFirstChild and to +GetNextChild should be the same variable (and that nothing should be done with +it by the user code). - 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. +Among other features of the tree control are: item sorting with SortChildren +which uses the user-defined comparison function OnCompareItems (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 HitTest and editing of the +tree item labels in place (see EditLabel). - */ +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. +*/