docs update for Greg's wxGenericTreeCtrl patch

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@12730 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/treectrl.tex

@@ -20,17 +20,43 @@ To intercept events from a tree control, use the event table macros described in
 
 \twocolwidtha{5cm}
 \begin{twocollist}\itemsep=0pt
-\twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style to show + and - buttons to the
+\twocolitem{\windowstyle{wxTR\_EDIT\_LABELS}}{Use this style
-left of parent items. Win32 only. }
+if you wish the user to be able to edit labels in the tree control.}
-\twocolitem{\windowstyle{wxTR\_NO\_LINES}}{Use this style to hide vertical lines.
+\twocolitem{\windowstyle{wxTR\_NO\_BUTTONS}}{For convenience
-Win32 only. }
+to document that no buttons are to be drawn.}
-\twocolitem{\windowstyle{wxTR\_LINES\_AT\_ROOT}}{Use this style to show lines at the
+\twocolitem{\windowstyle{wxTR\_HAS\_BUTTONS}}{Use this style
-tree root. Win32 only.}
+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
+\twocolitem{\windowstyle{wxTR\_TWIST\_BUTTONS}}{Use this style
-able to edit labels in the tree control.}
+to show Mac-style twister buttons to the left of parent items.
-\twocolitem{\windowstyle{wxTR\_MULTIPLE}}{Use this style to allow the user to
+If both wxTR\_HAS\_BUTTONS and wxTR\_TWIST\_BUTTONS are given,
-select more than one item in the control - by default, only one item may be
+twister buttons are generated.  Generic only.}
-selected.}
+\twocolitem{\windowstyle{wxTR\_NO\_LINES}}{Use this style
+to hide vertical level connectors.}
+\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}.
@@ -123,6 +149,9 @@ Destructor, destroying the list control.
 
 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.
 
@@ -133,15 +162,35 @@ both selected and unselected items.
 
 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.
 
+\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
-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}.
 
@@ -150,7 +199,8 @@ See also \helpref{SetImageList}{wxtreectrlsetimagelist}.
 \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}.
 
@@ -233,8 +283,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,
-only the rectangle around the items label will be returned, otherwise the
+only the rectangle around the item's label will be returned, otherwise the
-items image is also taken into account.
+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
@@ -247,6 +297,14 @@ item is currently invisible.
 \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}}
@@ -520,6 +578,9 @@ returned as a tuple.}
 
 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.
 
@@ -578,6 +639,9 @@ See also: \helpref{SortChildren}{wxtreectrlsortchildren}
 
 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.
 
@@ -593,6 +657,22 @@ Scrolls the specified item into view.
 
 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}}
@@ -613,7 +693,7 @@ See also \helpref{AssignImageList}{wxtreectrlassignimagelist}.
 
 \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}
 
@@ -650,7 +730,7 @@ tree->GetItemData( item )->SetData( data ); ).}
 
 \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.
 
@@ -691,7 +771,7 @@ Sets the item label.
 
 \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}
 
@@ -703,6 +783,12 @@ Image list assigned with this method will
 
 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}}