added SetStatusText method (avoiding dc.Clear)

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

diff --git a/docs/latex/wx/treectrl.tex b/docs/latex/wx/treectrl.tex
index 8e684c6e41448074df221fea221557175ab7a3a2..a52bf932a7c7cf9bf8eae187092e938d08626620 100644 (file)
--- a/docs/latex/wx/treectrl.tex
+++ b/docs/latex/wx/treectrl.tex
@@ -20,17 +20,47 @@ To intercept events from a tree control, use the event table macros described in
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt

-\twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style to show + and - buttons to the
-left of parent items. Win32 only. }
-\twocolitem{\windowstyle{wxTR\_NO\_LINES}}{Use this style to hide vertical lines.
-Win32 only. }
-\twocolitem{\windowstyle{wxTR\_LINES\_AT\_ROOT}}{Use this style to show lines at the
-tree root. Win32 only.}
-\twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style if you wish the user to be
-able to edit labels in the tree control.}
-\twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style to allow the user to
-select more than one item in the control - by default, only one item may be
-selected.}
+\twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style
+if you wish the user to be able to edit labels in the tree control.}
+\twocolitem{\windowstyle{wxTR\_NO\_BUTTONS}}{For convenience
+to document that no buttons are to be drawn.}
+\twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style
+to show + and - buttons to the left of parent items.}
+\twocolitem{\windowstyle{wxTR\_TWIST\_BUTTONS}}{Use this style
+to show Mac-style twister buttons to the left of parent items.
+If both wxTR\_HAS\_BUTTONS and wxTR\_TWIST\_BUTTONS are given,
+twister buttons are generated.  Generic only.}
+\twocolitem{\windowstyle{wxTR\_NO\_LINES}}{Use this style
+to hide vertical level connectors.}
+\twocolitem{\windowstyle{wxTR\_FULL\_ROW\_HIGHLIGHT}}{Use this style to have the background
+colour and the selection highlight extend over the entire horizontal
+row of the tree control window. (This flag is ignored under Windows unless you 
+specify wxTR\_NO\_LINES as well.) }
+\twocolitem{\windowstyle{wxTR\_LINES\_AT\_ROOT}}{Use this style
+to show lines between root nodes.
+Only applicable if wxTR\_HIDE\_ROOT is set and wxTR\_NO\_LINES is not set.}
+\twocolitem{\windowstyle{wxTR\_HIDE\_ROOT}}{Use this style
+to suppress the display of the root node,
+effectively causing the first-level nodes
+to appear as a series of root nodes.  Generic only.}
+\twocolitem{\windowstyle{wxTR\_ROW\_LINES}}{Use this style
+to draw a contrasting border between displayed rows.}
+\twocolitem{\windowstyle{wxTR\_HAS\_VARIABLE\_ROW\_HEIGHT}}{Use this style
+to cause row heights to be just big enough to fit the content.
+If not set, all rows use the largest row height.
+The default is that this flag is unset.
+Generic only.}
+\twocolitem{\windowstyle{wxTR\_SINGLE}}{For convenience
+to document that only one item may be selected at a time.
+Selecting another item causes the current selection, if any,
+to be deselected.  This is the default.}
+\twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style
+to allow a range of items to be selected.
+If a second range is selected, the current range, if any, is deselected.}
+\twocolitem{\windowstyle{wxTR\_EXTENDED}}{Use this style
+to allow disjoint items to be selected.  (Only partially implemented; may not work in all cases.)}
+\twocolitem{\windowstyle{wxTR\_DEFAULT\_STYLE}}{The set of flags that are
+closest to the defaults for the native control for a particular toolkit.}

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


@@ -123,6 +153,9 @@ Destructor, destroying the list control.
 
 Adds the root node to the tree, returning the new item.
 
 
 Adds the root node to the tree, returning the new item.
 

+The {\it image} and {\it selImage} parameters are an index within
+the normal image list specifying the image to use for unselected and
+selected items, respectively.

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


@@ -133,15 +166,35 @@ both selected and unselected items.
 
 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
 
 
 Appends an item to the end of the branch identified by {\it parent}, return a new item id.
 

+The {\it image} and {\it selImage} parameters are an index within
+the normal image list specifying the image to use for unselected and
+selected items, respectively.

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

+\membersection{wxTreeCtrl::AssignButtonsImageList}\label{wxtreectrlassignbuttonsimagelist}
+
+\func{void}{AssignButtonsImageList}{\param{wxImageList*}{ imageList}}
+
+Sets the buttons image list. The button images assigned with this method will
+be automatically deleted by wxTreeCtrl as appropriate
+(i.e. it takes ownership of the list).
+
+Setting or assigning the button image list enables the display of image buttons.
+Once enabled, the only way to disable the display of button images is to set
+the button image list to NULL.
+
+This function is only available in the generic version.
+
+See also \helpref{SetButtonsImageList}{wxtreectrlsetbuttonsimagelist}.
+

 \membersection{wxTreeCtrl::AssignImageList}\label{wxtreectrlassignimagelist}
 
 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
 
 Sets the normal image list. Image list assigned with this method will
 \membersection{wxTreeCtrl::AssignImageList}\label{wxtreectrlassignimagelist}
 
 \func{void}{AssignImageList}{\param{wxImageList*}{ imageList}}
 
 Sets the normal image list. Image list assigned with this method will

-be deleted by wxTreeCtrl's destructor (i.e. it takes ownership of it).
+be automatically deleted by wxTreeCtrl as appropriate
+(i.e. it takes ownership of the list).

 
 See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 
 
 See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 


@@ -150,7 +203,8 @@ See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 \func{void}{AssignStateImageList}{\param{wxImageList*}{ imageList}}
 
 Sets the state image list. Image list assigned with this method will
 \func{void}{AssignStateImageList}{\param{wxImageList*}{ imageList}}
 
 Sets the state image list. Image list assigned with this method will

-be deleted by wxTreeCtrl's destructor (i.e. it takes ownership of it).
+be automatically deleted by wxTreeCtrl as appropriate
+(i.e. it takes ownership of the list).

 
 See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
 
 
 See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
 


@@ -233,8 +287,8 @@ Expands the given item.
 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = FALSE}}
 
 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is TRUE,
 \constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = FALSE}}
 
 Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is TRUE,

-only the rectangle around the items label will be returned, otherwise the
-items image is also taken into account.
+only the rectangle around the item's label will be returned, otherwise the
+item's image is also taken into account.

 
 The return value is TRUE if the rectangle was successfully retrieved or FALSE
 if it was not (in this case {\it rect} is not changed) - for example, if the
 
 The return value is TRUE if the rectangle was successfully retrieved or FALSE
 if it was not (in this case {\it rect} is not changed) - for example, if the


@@ -244,6 +298,17 @@ item is currently invisible.
 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 {\tt wxRect} object or {\tt None}.}
 
 {\tt item} and {\tt textOnly} parameters.  The return value is either a
 {\tt wxRect} object or {\tt None}.}
 

+\perlnote{In wxPerl this method only takes the parameters {\tt item} and 
+  {\tt textOnly}, and returns a Wx::Rect ( or undef ).}
+
+\membersection{wxTreeCtrl::GetButtonsImageList}\label{wxtreectrlgetbuttonsimagelist}
+
+\constfunc{wxImageList*}{GetButtonsImageList}{\void}
+
+Returns the buttons image list (from which application-defined button images are taken).
+
+This function is only available in the generic version.
+

 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 
 \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = TRUE}}
 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 
 \constfunc{size\_t}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = TRUE}}


@@ -284,6 +349,9 @@ Returns an invalid tree item if there are no further children.
 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 value are both returned as a tuple containing the two values.}
 
 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 value are both returned as a tuple containing the two values.}
 

+\perlnote{In wxPerl this method only takes the {\tt item} parameter, and
+  returns a 2-element list ( item, cookie ).}
+

 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 
 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}
 \membersection{wxTreeCtrl::GetFirstVisibleItem}\label{wxtreectrlgetfirstvisibleitem}
 
 \constfunc{wxTreeItemId}{GetFirstVisibleItem}{\void}


@@ -320,6 +388,15 @@ associated with the wxTreeItemData for the given item Id.}
 \end{twocollist}}
 }
 
 \end{twocollist}}
 }
 

+\perlnote{wxPerl provides the following shortcut method:
+\indented{2cm}{
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf GetPlData( item )}}{Returns the Perl data
+associated with the Wx::TreeItemData ( it is just the same as
+tree->GetItemData( item )->GetData(); ).}
+\end{twocollist}}
+}
+

 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 
 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},
 \membersection{wxTreeCtrl::GetItemImage}\label{wxtreectrlgetitemimage}
 
 \constfunc{int}{GetItemImage}{\param{const wxTreeItemId\& }{item},


@@ -376,6 +453,9 @@ Returns an invalid tree item if there are no further children.
 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 value are both returned as a tuple containing the two values.}
 
 \pythonnote{In wxPython the returned wxTreeItemId and the new cookie
 value are both returned as a tuple containing the two values.}
 

+\perlnote{In wxPerl this method returns a 2-element list
+  ( item, cookie ), instead of modifying its parameters.}
+

 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 
 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}
 \membersection{wxTreeCtrl::GetNextSibling}\label{wxtreectrlgetnextsibling}
 
 \constfunc{wxTreeItemId}{GetNextSibling}{\param{const wxTreeItemId\&}{ item}}


@@ -455,6 +535,9 @@ Returns the number of selected items.
 \pythonnote{The wxPython version of this method accepts no parameters
 and returns a Python list of {\tt wxTreeItemId}s.}
 
 \pythonnote{The wxPython version of this method accepts no parameters
 and returns a Python list of {\tt wxTreeItemId}s.}
 

+\perlnote{In wxPerl this method takes no parameters and returns a list of
+ {\tt Wx::TreeItemId}s.}
+

 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 
 \constfunc{wxImageList*}{GetStateImageList}{\void}
 \membersection{wxTreeCtrl::GetStateImageList}\label{wxtreectrlgetstateimagelist}
 
 \constfunc{wxImageList*}{GetStateImageList}{\void}


@@ -486,6 +569,9 @@ id at this point plus extra information {\it flags}. {\it flags} is a bitlist of
 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 returned as a tuple.}
 
 \pythonnote{in wxPython both the wxTreeItemId and the flags are
 returned as a tuple.}
 

+\perlnote{In wxPerl this method only takes the {\tt point} parameter
+  and returns a 2-element list ( item, flags ).}
+

 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 
 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},
 \membersection{wxTreeCtrl::InsertItem}\label{wxtreectrlinsertitem}
 
 \func{wxTreeItemId}{InsertItem}{\param{const wxTreeItemId\& }{parent}, \param{const wxTreeItemId\& }{previous}, \param{const wxString\&}{ text},


@@ -496,6 +582,9 @@ returned as a tuple.}
 
 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 
 
 Inserts an item after a given one ({\it previous}) or before one identified by its position ({\it before}).
 

+The {\it image} and {\it selImage} parameters are an index within
+the normal image list specifying the image to use for unselected and
+selected items, respectively.

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


@@ -554,6 +643,9 @@ See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 
 Appends an item as the first child of {\it parent}, return a new item id.
 
 
 Appends an item as the first child of {\it parent}, return a new item id.
 

+The {\it image} and {\it selImage} parameters are an index within
+the normal image list specifying the image to use for unselected and
+selected items, respectively.

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


@@ -569,6 +661,22 @@ Scrolls the specified item into view.
 
 Selects the given item.
 
 
 Selects the given item.
 

+\membersection{wxTreeCtrl::SetButtonsImageList}\label{wxtreectrlsetbuttonsimagelist}
+
+\func{void}{SetButtonsImageList}{\param{wxImageList*}{ imageList}}
+
+Sets the buttons image list (from which application-defined button images are taken).
+The button images assigned with this method will
+{\bf not} be deleted by wxTreeCtrl's destructor, you must delete it yourself.
+
+Setting or assigning the button image list enables the display of image buttons.
+Once enabled, the only way to disable the display of button images is to set
+the button image list to NULL.
+
+This function is only available in the generic version.
+
+See also \helpref{AssignButtonsImageList}{wxtreectrlassignbuttonsimagelist}.
+

 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 
 \func{void}{SetIndent}{\param{int }{indent}}
 \membersection{wxTreeCtrl::SetIndent}\label{wxtreectrlsetindent}
 
 \func{void}{SetIndent}{\param{int }{indent}}


@@ -589,7 +697,7 @@ See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 
 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 
 
 \func{void}{SetItemBackgroundColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 

-Sets the colour of the items background.
+Sets the colour of the item's background.

 
 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 
 
 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 


@@ -613,11 +721,20 @@ Object with the wxTreeItemData for the given item Id.}
 \end{twocollist}}
 }
 
 \end{twocollist}}
 }
 

+\perlnote{wxPerl provides the following shortcut method:
+\indented{2cm}{
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf SetPlData( item, data )}}{Sets the Perl data
+associated with the Wx::TreeItemData ( it is just the same as
+tree->GetItemData( item )->SetData( data ); ).}
+\end{twocollist}}
+}
+

 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 
 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 
 \membersection{wxTreeCtrl::SetItemFont}\label{wxtreectrlsetitemfont}
 
 \func{void}{SetItemFont}{\param{const wxTreeItemId\&}{ item}, \param{const wxFont\& }{font}}
 

-Sets the items font. All items in the tree should have the same height to avoid
+Sets the item's font. All items in the tree should have the same height to avoid

 text clipping, so the fonts height should be the same for all of them,
 although font attributes may vary.
 
 text clipping, so the fonts height should be the same for all of them,
 although font attributes may vary.
 


@@ -658,7 +775,7 @@ Sets the item label.
 
 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 
 
 \func{void}{SetItemTextColour}{\param{const wxTreeItemId\&}{ item}, \param{const wxColour\& }{col}}
 

-Sets the colour of the items text.
+Sets the colour of the item's text.

 
 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 
 
 \membersection{wxTreeCtrl::SetStateImageList}\label{wxtreectrlsetstateimagelist}
 


@@ -670,6 +787,12 @@ Image list assigned with this method will
 
 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 
 
 See also \helpref{AssignStateImageList}{wxtreectrlassignstateimagelist}.
 

+\func{void}{SetWindowStyle}{\param{long}{styles}}
+
+Sets the mode flags associated with the display of the tree control.
+The new mode takes effect immediately.
+(Generic only; MSW ignores changes.)
+

 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 
 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}
 \membersection{wxTreeCtrl::SortChildren}\label{wxtreectrlsortchildren}
 
 \func{void}{SortChildren}{\param{const wxTreeItemId\&}{ item}}


@@ -752,6 +875,10 @@ wxTreeItemData}
 \end{twocollist}}
 }
 
 \end{twocollist}}
 }
 

+\perlnote{In wxPerl the constructor accepts as parameter an optional scalar,
+ and stores it as client data. You may retrieve this data by calling
+ {\bf GetData()}, and set it by callling {\bf SetData( data ).}
+}

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