a bit more docs

[wxWidgets.git] / docs / latex / wx / treectrl.tex

\section{\class{wxTreeCtrl}}\label{wxtreectrl}

A tree control presents information as a hierarchy, with items that may be expanded
to show further items. Items in a tree control are referenced by wxTreeItemId handles.

To intercept events from a tree control, use the event table macros described in \helpref{wxTreeEvent}{wxtreeevent}.

\wxheading{Derived from}

\helpref{wxControl}{wxcontrol}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Window styles}

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style to show + and - buttons to the
left of parent items.}
\twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style if you wish the user to be
able to edit labels in the tree control.}
\end{twocollist}

See also \helpref{window styles overview}{windowstyles}.

\wxheading{Event handling}

To process input from a tree control, use these event handler macros to direct input to member
functions that take a \helpref{wxTreeEvent}{wxtreeevent} argument.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_TREE\_BEGIN\_DRAG(id, func)}}{Begin dragging with the left mouse button.}
\twocolitem{{\bf EVT\_TREE\_BEGIN\_RDRAG(id, func)}}{Begin dragging with the right mouse button.}
\twocolitem{{\bf EVT\_TREE\_BEGIN\_LABEL\_EDIT(id, func)}}{Begin editing a label.}
\twocolitem{{\bf EVT\_TREE\_END\_LABEL\_EDIT(id, func)}}{Finish editing a label.}
\twocolitem{{\bf EVT\_TREE\_DELETE\_ITEM(id, func)}}{Delete an item.}
\twocolitem{{\bf EVT\_TREE\_GET\_INFO(id, func)}}{Request information from the application.}
\twocolitem{{\bf EVT\_TREE\_SET\_INFO(id, func)}}{Information is being supplied.}
\twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDED(id, func)}}{Parent has been expanded.}
\twocolitem{{\bf EVT\_TREE\_ITEM\_EXPANDING(id, func)}}{Parent is being expanded.}
\twocolitem{{\bf EVT\_TREE\_SEL\_CHANGED(id, func)}}{Selection has changed.}
\twocolitem{{\bf EVT\_TREE\_SEL\_CHANGING(id, func)}}{Selection is changing.}
\twocolitem{{\bf EVT\_TREE\_KEY\_DOWN(id, func)}}{A key has been pressed.}
\end{twocollist}%

\wxheading{See also}

\helpref{wxTreeItemData}{wxtreeitemdata}, \helpref{wxTreeCtrl overview}{wxtreectrloverview}, \helpref{wxListBox}{wxlistbox}, \helpref{wxListCtrl}{wxlistctrl},\rtfsp
\helpref{wxImageList}{wximagelist}, \helpref{wxTreeEvent}{wxtreeevent}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxTreeCtrl::wxTreeCtrl}\label{wxtreectrlconstr}

\func{}{wxTreeCtrl}{\void}

Default constructor.

\func{}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
\param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}

Constructor, creating and showing a tree control.

\wxheading{Parameters}

\docparam{parent}{Parent window. Must not be NULL.}

\docparam{id}{Window identifier. A value of -1 indicates a default value.}

\docparam{pos}{Window position.}

\docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
appropriately.}

\docparam{style}{Window style. See \helpref{wxTreeCtrl}{wxtreectrl}.}

\docparam{validator}{Window validator.}

\docparam{name}{Window name.}

\wxheading{See also}

\helpref{wxTreeCtrl::Create}{wxtreectrlcreate}, \helpref{wxValidator}{wxvalidator}

\membersection{wxTreeCtrl::\destruct{wxTreeCtrl}}

\func{void}{\destruct{wxTreeCtrl}}{\void}

Destructor, destroying the list control.

\membersection{wxTreeCtrl::AddRoot}\label{wxtreectrladdroot}

\func{wxTreeItemId}{AddRoot}{\param{const wxString\&}{ text},
 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}

Adds the root node to the tree, returning the new item.

If {\it image} > -1 and {\it selImage} is -1, the same image is used for
both selected and unselected items.

\membersection{wxTreeCtrl::AppendItem}\label{wxtreectrlappenditem}

\func{wxTreeItemId}{AppendItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}

Appends an item to the end of the branch identified by {\it parent}, return a new item id.

If {\it image} > -1 and {\it selImage} is -1, the same image is used for
both selected and unselected items.

\membersection{wxTreeCtrl::Collapse}\label{wxtreectrlcollapse}

\func{void}{Collapse}{\param{const wxTreeItemId\&}{ item}}

Collapses the given item.

\membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}

\func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}

Collapses the given item and removes all children.

\membersection{wxTreeCtrl::Create}\label{wxtreectrlcreate}

\func{bool}{wxTreeCtrl}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
\param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
\param{long}{ style = wxTR\_HAS\_BUTTONS}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listCtrl"}}

Creates the tree control. See \helpref{wxTreeCtrl::wxTreeCtrl}{wxtreectrlconstr} for further details.

\membersection{wxTreeCtrl::Delete}\label{wxtreectrldelete}

\func{void}{Delete}{\param{const wxTreeItemId\&}{ item}}

Deletes the specified item.

\membersection{wxTreeCtrl::DeleteAllItems}\label{wxtreectrldeleteallitems}

\func{void}{DeleteAllItems}{\void}

Deletes all the items in the control.

\membersection{wxTreeCtrl::EditLabel}\label{wxtreectrleditlabel}

\func{wxTextCtrl*}{EditLabel}{\param{const wxTreeItemId\&}{ item}, \param{wxClassInfo*}{ textControlClass = CLASSINFO(wxTextCtrl)}}

Starts editing the label of the given item, returning the text control that the tree control uses for editing.

Pass another {\it textControlClass} if a derived class is required. It usually will be, in order for
the application to detect when editing has finished and to call \helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel}.

Do not delete the text control yourself.

This function is currently supported under Windows only.

\wxheading{See also}

\helpref{wxTreeCtrl::EndEditLabel}{wxtreectrlendeditlabel}

\membersection{wxTreeCtrl::EndEditLabel}\label{wxtreectrlendeditlabel}

\func{void}{EndEditLabel}{\param{bool }{cancelEdit}}

Ends label editing. If {\it cancelEdit} is TRUE, the edit will be cancelled.

This function is currently supported under Windows only.

\wxheading{See also}

\helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}

\membersection{wxTreeCtrl::EnsureVisible}\label{wxtreectrlensurevisible}

\func{void}{EnsureVisible}{\param{const wxTreeItemId\&}{ item}}

Scrolls and/or expands items to ensure that the given item is visible.

\membersection{wxTreeCtrl::Expand}\label{wxtreectrlexpand}

\func{void}{Expand}{\param{const wxTreeItemId\&}{ item}}

Expands the given item.

\membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}

\constfunc{void}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = FALSE}}

Returns the position and size of the rectangle bounding the item.

\membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}

\constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = TRUE}}

Returns the number of items in the branch. If {\it recursively} is TRUE, returns the total number
of descendants, otherwise only one level of children is counted.

\membersection{wxTreeCtrl::GetCount}\label{wxtreectrlgetcount}

\constfunc{int}{GetCount}{\void}

Returns the number of items in the control.

\membersection{wxTreeCtrl::GetEditControl}\label{wxtreectrlgeteditcontrol}

\constfunc{wxTextCtrl\&}{GetEditControl}{\void}

Returns the edit control used to edit a label.

\membersection{wxTreeCtrl::GetFirstChild}\label{wxtreectrlgetfirstchild}

\constfunc{wxTreeItemId}{GetFirstChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}}

Returns the first child; call \helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild} for the next child.

For this enumeration function you must pass in a `cookie' parameter
which is opaque for the application but is necessary for the library
to make these functions reentrant (i.e. allow more than one
enumeration on one and the same object simultaneously). The cookie passed to
GetFirstChild and GetNextChild should be the same.

Returns 0 if there are no further children.

\wxheading{See also}

\helpref{wxTreeCtrl::GetNextChild}{wxtreectrlgetnextchild}

\membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}

\constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}

Returns the first visible item.

\membersection{wxTreeCtrl::GetImageList}\label{wxtreectrlgetimagelist}

\constfunc{wxImageList*}{GetImageList}{\param{int }{which = wxIMAGE\_LIST\_NORMAL}}

Returns the specified image list. {\it which} may be one of:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxIMAGE\_LIST\_NORMAL}}{The normal (large icon) image list.}
\twocolitem{\windowstyle{wxIMAGE\_LIST\_SMALL}}{The small icon image list.}
\twocolitem{\windowstyle{wxIMAGE\_LIST\_STATE}}{The user-defined state image list (unimplemented).}
\end{twocollist}

\membersection{wxTreeCtrl::GetIndent}\label{wxtreectrlgetindent}

\constfunc{int}{GetIndent}{\void}

Returns the current tree control indentation.

\membersection{wxTreeCtrl::GetItemData}\label{wxtreectrlgetitemdata}

\constfunc{wxTreeItemData*}{GetItemData}{\param{const wxTreeItemId\&}{ item}}

Returns the tree item data associated with the item.

\wxheading{See also}

\helpref{wxTreeItemData}{wxtreeitemdata}

\membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}

\constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item}}

Gets the normal item image.

\membersection{wxTreeCtrl::GetItemText}\label{wxtreectrlgetitemtext}

\constfunc{wxString}{GetItemText}{\param{const wxTreeItemId\&}{ item}}

Returns the item label.

\membersection{wxTreeCtrl::GetNextChild}\label{wxtreectrlgetnextchild}

\constfunc{wxTreeItemId}{GetNextChild}{\param{const wxTreeItemId\&}{ item}, \param{long\& }{cookie}}

Returns the next child; call \helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild} for the first child.

For this enumeration function you must pass in a `cookie' parameter
which is opaque for the application but is necessary for the library
to make these functions reentrant (i.e. allow more than one
enumeration on one and the same object simultaneously). The cookie passed to
GetFirstChild and GetNextChild should be the same.

Returns 0 if there are no further children.

\wxheading{See also}

\helpref{wxTreeCtrl::GetFirstChild}{wxtreectrlgetfirstchild}

\membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}

\constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}

Returns the next sibling of the specified item; call \helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling} for the previous sibling.

Returns 0 if there are no further siblings.

\wxheading{See also}

\helpref{wxTreeCtrl::GetPrevSibling}{wxtreectrlgetprevsibling}

\membersection{wxTreeCtrl::GetNextVisible}\label{wxtreectrlgetnextvisible}

\constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}

Returns the next visible item.

\membersection{wxTreeCtrl::GetParent}\label{wxtreectrlgetparent}

\constfunc{wxTreeItemId}{GetParent}{\param{const wxTreeItemId\&}{ item}}

Returns the item's parent.

\membersection{wxTreeCtrl::GetPrevSibling}\label{wxtreectrlgetprevsibling}

\constfunc{wxTreeItemId}{GetPrevSibling}{\param{const wxTreeItemId\&}{ item}}

Returns the previous sibling of the specified item; call \helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling} for the next sibling.

Returns 0 if there are no further children.

\wxheading{See also}

\helpref{wxTreeCtrl::GetNextSibling}{wxtreectrlgetnextsibling}

\membersection{wxTreeCtrl::GetPrevVisible}\label{wxtreectrlgetprevvisible}

\constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}

Returns the previous visible item.

\membersection{wxTreeCtrl::GetRootItem}\label{wxtreectrlgetrootitem}

\constfunc{wxTreeItemId}{GetRootItem}{\void}

Returns the root item for the tree control.

\membersection{wxTreeCtrl::GetSelectedItemImage}\label{wxtreectrlgetselecteditemimage}

\constfunc{int}{GetSelectedItemImage}{\param{const wxTreeItemId\& }{item}}

Gets the selected item image.

\membersection{wxTreeCtrl::GetSelection}\label{wxtreectrlgetselection}

\constfunc{wxTreeItemId}{GetSelection}{\void}

Returns the selection, or 0 if there is no selection.

\membersection{wxTreeCtrl::HitTest}\label{wxtreectrlhittest}

\func{long}{HitTest}{\param{const wxPoint\& }{point}, \param{int\& }{flags}}

Calculates which (if any) item is under the given point, returning extra information
in {\it flags}. {\it flags} is a bitlist of the following:

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{wxTREE\_HITTEST\_ABOVE}{Above the client area.}
\twocolitem{wxTREE\_HITTEST\_BELOW}{Below the client area.}
\twocolitem{wxTREE\_HITTEST\_NOWHERE}{In the client area but below the last item.}
\twocolitem{wxTREE\_HITTEST\_ONITEMBUTTON}{On the button associated with an item.}
\twocolitem{wxTREE\_HITTEST\_ONITEMICON}{On the bitmap associated with an item.}
\twocolitem{wxTREE\_HITTEST\_ONITEMINDENT}{In the indentation associated with an item.}
\twocolitem{wxTREE\_HITTEST\_ONITEMLABEL}{On the label (string) associated with an item.}
\twocolitem{wxTREE\_HITTEST\_ONITEMRIGHT}{In the area to the right of an item.}
\twocolitem{wxTREE\_HITTEST\_ONITEMSTATEICON}{On the state icon for a tree view item that is in a user-defined state.}
\twocolitem{wxTREE\_HITTEST\_TOLEFT}{To the right of the client area.}
\twocolitem{wxTREE\_HITTEST\_TORIGHT}{To the left of the client area.}
\end{twocollist}

\membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}

\func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}

Inserts an item after a given one.

If {\it image} > -1 and {\it selImage} is -1, the same image is used for
both selected and unselected items.

\membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}

\constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}

Returns TRUE if the item is expanded (only makes sense if it has children).

\membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}

\constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}

Returns TRUE if the item is selected.

\membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}

\constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}

Returns TRUE if the item is visible (it might be outside the view, or not expanded).

\membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}

\constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}

Returns TRUE if the item has children.

\membersection{wxTreeCtrl::PrependItem}\label{wxtreectrlprependitem}

\func{wxTreeItemId}{PrependItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxString\&}{ text},
 \param{int}{ image = -1}, \param{int}{ selImage = -1}, \param{wxTreeItemData*}{ data = NULL}}

Appends an item as the first child of {\it parent}, return a new item id.

If {\it image} > -1 and {\it selImage} is -1, the same image is used for
both selected and unselected items.

\membersection{wxTreeCtrl::ScrollTo}\label{wxtreectrlscrollto}

\func{void}{ScrollTo}{\param{const wxTreeItemId\&}{ item}}

Scrolls the specified item into view.

\membersection{wxTreeCtrl::SelectItem}\label{wxtreectrlselectitem}

\func{bool}{SelectItem}{\param{const wxTreeItemId\&}{ item}}

Selects the given item.

\membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}

\func{void}{SetIndent}{\param{int }{indent}}

Sets the indentation for the tree control.

\membersection{wxTreeCtrl::SetImageList}\label{wxtreectrlsetimagelist}

\func{void}{SetImageList}{\param{wxImageList*}{ imageList}, \param{int }{which = wxIMAGE\_LIST\_NORMAL}}

Sets the image list. {\it which} should be one of wxIMAGE\_LIST\_NORMAL, wxIMAGE\_LIST\_SMALL and
wxIMAGE\_LIST\_STATE.

\membersection{wxTreeCtrl::SetItemData}\label{wxtreectrlsetitemdata}

\func{void}{SetItemData}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemData* }{data}}

Sets the item client data.

\membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}

\func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = TRUE}}

Force appearance of the button next to the item. This is useful to
allow the user to expand the items which don't have any children now,
but instead adding them only when needed, thus minimizing memory
usage and loading time.

\membersection{wxTreeCtrl::SetItemImage}\label{wxtreectrlsetitemimage}

\func{void}{SetItemImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{image}}

Sets the normal item image. This is an index into the assciated image list.

\membersection{wxTreeCtrl::SetItemSelectedImage}\label{wxtreectrlsetitemselectedimage}

\func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}

Sets the item selected image. This is an index into the assciated image list.

\membersection{wxTreeCtrl::SetItemText}\label{wxtreectrlsetitemtext}

\func{void}{SetItemText}{\param{const wxTreeItemId\&}{ item}, \param{const wxString\& }{text}}

Sets the item label.

\membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}

\func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}, \param{wxTreeItemCmpFunc*}{ cmpFunction = NULL}}

Sorts the children of the given item. If {\it cmpFunction} is NULL, sorts in ascending alphabetical order;
otherwise the custom sort function is used, as follows:

{\small
\begin{verbatim}
// a callback function used for sorting tree items, it should return -1 if the
// first item precedes the second, +1 if the second precedes the first or 0 if
// they're equivalent
class wxTreeItemData;
typedef int (*wxTreeItemCmpFunc)(wxTreeItemData *item1, wxTreeItemData *item2);
\end{verbatim}
}

\wxheading{See also}

\helpref{wxTreeItemData}{wxtreeitemdata}

\membersection{wxTreeCtrl::Toggle}\label{wxtreectrltoggle}

\func{void}{Toggle}{\param{const wxTreeItemId\&}{ item}}

Toggles the given item between collapsed and expanded states.

\membersection{wxTreeCtrl::Unselect}\label{wxtreectrlunselect}

\func{void}{Unselect}{\void}

Removes the selection from the currently selected item (if any).

\section{\class{wxTreeItemData}}\label{wxtreeitemdata}

wxTreeItemData is some (arbitrary) user class associated with some item. The
main advantage of having this class (compared to the old untyped interface) is
that wxTreeItemData's are destroyed automatically by the tree and, as this
class has virtual dtor, it means that the memory will be automatically
freed. We don't just use wxObject instead of wxTreeItemData because
the size of this class is critical: in any real application, each tree leaf
will have wxTreeItemData associated with it and number of leaves may be
quite big.

Because the objects of this class are deleted by the tree, they should
always be allocated on the heap.

\wxheading{Derived from}

wxTreeItemId

\wxheading{See also}

\helpref{wxTreeCtrl}{wxtreectrl}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxTreeItemData::wxTreeItemData}\label{wxtreeitemdataconstr}

\func{}{wxTreeItemData}{\void}

Default constructor.

\membersection{wxTreeItemData::\destruct{wxTreeItemData}}

\func{void}{\destruct{wxTreeItemData}}{\void}

Virtual destructor.

\membersection{wxTreeItemData::GetId}\label{wxtreeitemdatagetid}

\func{const wxTreeItem\&}{GetId}{\void}

Returns the item associated with this node.

\membersection{wxTreeItemData::SetId}\label{wxtreeitemdatasetid}

\func{void}{SetId}{\param{const wxTreeItemId\&}{ id}}

Sets the item associated with this node.