added null pointer check and assert

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

diff --git a/docs/latex/wx/treectrl.tex b/docs/latex/wx/treectrl.tex
index 96859ec829f6ed71d1bd40481fff8411801c3081..48fed6862a43e5eb09233daefa6167ef9ab262d9 100644 (file)
--- a/docs/latex/wx/treectrl.tex
+++ b/docs/latex/wx/treectrl.tex
@@ -13,7 +13,7 @@
 
 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,
 
 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,

-which may be tested for validity by calling wxTreeItemId::IsOk.
+which may be tested for validity by calling \helpref{wxTreeItemId::IsOk}{wxtreeitemidisok}.

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


@@ -28,6 +28,10 @@ To intercept events from a tree control, use the event table macros described in
 
 <wx/treectrl.h>
 
 
 <wx/treectrl.h>
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}


@@ -65,8 +69,6 @@ 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\_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}
 \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}


@@ -238,6 +240,28 @@ See also \helpref{SetStateImageList}{wxtreectrlsetstateimagelist}.
 Collapses the given item.
 
 
 Collapses the given item.
 
 

+\membersection{wxTreeCtrl::CollapseAll}\label{wxtreectrlcollapseall}
+
+\func{void}{CollapseAll}{\void}
+
+Collapses the root item.
+
+\wxheading{See also}
+
+\helpref{ExpandAll}{wxtreectrlexpandall}
+
+
+\membersection{wxTreeCtrl::CollapseAllChildren}\label{wxtreectrlcollapseallchildren}
+
+\func{void}{CollapseAllChildren}{\param{const wxTreeItemId\&}{ item}}
+
+Collapses this item and all of its children, recursively.
+
+\wxheading{See also}
+
+\helpref{ExpandAllChildren}{wxtreectrlexpandallchildren}
+
+

 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
 
 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}
 \membersection{wxTreeCtrl::CollapseAndReset}\label{wxtreectrlcollapseandreset}
 
 \func{void}{CollapseAndReset}{\param{const wxTreeItemId\&}{ item}}


@@ -308,7 +332,7 @@ will be sent which can be vetoed as well.
 
 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
 
 
 \func{void}{EndEditLabel}{\param{bool }{cancelEdit}}
 

-Ends label editing. If {\it cancelEdit} is {\tt true}, the edit will be cancelled.
+Ends label editing. If {\it cancelEdit} is \true, the edit will be cancelled.

 
 This function is currently supported under Windows only.
 
 
 This function is currently supported under Windows only.
 


@@ -333,7 +357,7 @@ Expands the given item.
 
 \membersection{wxTreeCtrl::ExpandAll}\label{wxtreectrlexpandall}
 
 
 \membersection{wxTreeCtrl::ExpandAll}\label{wxtreectrlexpandall}
 

-\func{void}{Expand}{\void}
+\func{void}{ExpandAll}{\void}

 
 Expands all items in the tree.
 
 
 Expands all items in the tree.
 


@@ -347,13 +371,13 @@ Expands the given item and all its children recursively.
 
 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
 
 
 \membersection{wxTreeCtrl::GetBoundingRect}\label{wxtreectrlgetitemrect}
 

-\constfunc{bool}{GetBoundingRect}{\param{const wxTreeItemId\&}{ item}, \param{wxRect\& }{rect}, \param{bool }{textOnly = {\tt false}}}
+\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 {\tt true},
+Retrieves the rectangle bounding the {\it item}. If {\it textOnly} is \true,

 only the rectangle around the item's label will be returned, otherwise the
 item's 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 {\tt true} if the rectangle was successfully retrieved or {\tt false}
+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
 item is currently invisible.
 
 if it was not (in this case {\it rect} is not changed) -- for example, if the
 item is currently invisible.
 


@@ -380,9 +404,9 @@ This function is only available in the generic version.
 
 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 
 
 \membersection{wxTreeCtrl::GetChildrenCount}\label{wxtreectrlgetchildrencount}
 

-\constfunc{unsigned int}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = {\tt true}}}
+\constfunc{unsigned int}{GetChildrenCount}{\param{const wxTreeItemId\&}{ item}, \param{bool}{ recursively = \true}}

 
 

-Returns the number of items in the branch. If {\it recursively} is {\tt true}, returns the total number
+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.
 
 
 of descendants, otherwise only one level of children is counted.
 
 


@@ -415,7 +439,7 @@ 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 variable.
 
 enumeration on one and the same object simultaneously). The cookie passed to
 GetFirstChild and GetNextChild should be the same variable.
 

-Returns an invalid tree item (i.e. IsOk() returns {\tt false}) if there are no further children.
+Returns an invalid tree item (i.e. IsOk() returns \false) if there are no further children.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 


@@ -579,7 +603,10 @@ Returns an invalid tree item if there are no further siblings.
 
 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 
 
 \constfunc{wxTreeItemId}{GetNextVisible}{\param{const wxTreeItemId\&}{ item}}
 

-Returns the next visible item.
+Returns the next visible item or an invalid item if this item is the last
+visible one.
+
+Notice that the \arg{item} itself must be visible.

 
 
 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}
 
 
 \membersection{wxTreeCtrl::GetItemParent}\label{wxtreectrlgetitemparent}


@@ -606,7 +633,10 @@ Returns an invalid tree item if there are no further children.
 
 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 
 
 \constfunc{wxTreeItemId}{GetPrevVisible}{\param{const wxTreeItemId\&}{ item}}
 

-Returns the previous visible item.
+Returns the previous visible item or an invalid item if this item is the first
+visible one.
+
+Notice that the \arg{item} itself must be visible.

 
 
 \membersection{wxTreeCtrl::GetQuickBestSize}\label{wxtreectrlgetquickbestsize}
 
 
 \membersection{wxTreeCtrl::GetQuickBestSize}\label{wxtreectrlgetquickbestsize}


@@ -632,8 +662,8 @@ Returns the root item for the tree control.
 
 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 
 
 \constfunc{int}{GetItemSelectedImage}{\param{const wxTreeItemId\& }{item}}
 

-Gets the selected item image (this function is obsolete, use
-{\tt GetItemImage(item, wxTreeItemIcon\_Selected}) instead).
+Gets the selected item image (this function is obsolete, use 
+{\tt GetItemImage(item, wxTreeItemIcon\_Selected)} instead).

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


@@ -723,37 +753,44 @@ both selected and unselected items.
 
 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 
 
 \constfunc{bool}{IsBold}{\param{const wxTreeItemId\& }{item}}
 

-Returns {\tt true} if the given item is in bold state.
+Returns \true if the given item is in bold state.

 
 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 
 
 
 See also: \helpref{SetItemBold}{wxtreectrlsetitembold}
 
 

+\membersection{wxTreeCtrl::IsEmpty}\label{wxtreectrlisempty}
+
+\constfunc{bool}{IsEmpty}{}
+
+Returns \true if the control is empty (i.e. has no items, even no root one).
+
+

 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 
 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 
 \membersection{wxTreeCtrl::IsExpanded}\label{wxtreectrlisexpanded}
 
 \constfunc{bool}{IsExpanded}{\param{const wxTreeItemId\&}{ item}}
 

-Returns {\tt true} if the item is expanded (only makes sense if it has children).
+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}}
 
 
 
 \membersection{wxTreeCtrl::IsSelected}\label{wxtreectrlisselected}
 
 \constfunc{bool}{IsSelected}{\param{const wxTreeItemId\&}{ item}}
 

-Returns {\tt true} if the item is selected.
+Returns \true if the item is selected.

 
 
 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 
 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 
 
 
 \membersection{wxTreeCtrl::IsVisible}\label{wxtreectrlisvisible}
 
 \constfunc{bool}{IsVisible}{\param{const wxTreeItemId\&}{ item}}
 

-Returns {\tt true} if the item is visible (it might be outside the view, or not expanded).
+Returns \true if the item is visible on the screen.

 
 
 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 
 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 
 
 
 \membersection{wxTreeCtrl::ItemHasChildren}\label{wxtreectrlitemhaschildren}
 
 \constfunc{bool}{ItemHasChildren}{\param{const wxTreeItemId\&}{ item}}
 

-Returns {\tt true} if the item has children.
+Returns \true if the item has children.

 
 
 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}
 
 
 \membersection{wxTreeCtrl::OnCompareItems}\label{wxtreectrloncompareitems}


@@ -848,9 +885,9 @@ Sets the colour of the item's background.
 
 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 
 
 \membersection{wxTreeCtrl::SetItemBold}\label{wxtreectrlsetitembold}
 

-\func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = {\tt true}}}
+\func{void}{SetItemBold}{\param{const wxTreeItemId\& }{item}, \param{bool}{ bold = \true}}

 
 

-Makes item appear in bold font if {\it bold} parameter is {\tt true} or resets it to
+Makes item appear in bold font if {\it bold} parameter is \true or resets it to

 the normal state.
 
 See also: \helpref{IsBold}{wxtreectrlisbold}
 the normal state.
 
 See also: \helpref{IsBold}{wxtreectrlisbold}


@@ -880,7 +917,7 @@ tree->GetItemData(item)->SetData(data).}
 
 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
 
 
 \membersection{wxTreeCtrl::SetItemDropHighlight}\label{wxtreectrlsetitemdrophighlight}
 

-\func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = {\tt true}}}
+\func{void}{SetItemDropHighlight}{\param{const wxTreeItemId\&}{ item}, \param{bool}{highlight = \true}}

 
 Gives the item the visual feedback for Drag'n'Drop actions, which is
 useful if something is dragged from the outside onto the tree control
 
 Gives the item the visual feedback for Drag'n'Drop actions, which is
 useful if something is dragged from the outside onto the tree control


@@ -902,7 +939,7 @@ although font attributes may vary.
 
 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 
 
 \membersection{wxTreeCtrl::SetItemHasChildren}\label{wxtreectrlsetitemhaschildren}
 

-\func{void}{SetItemHasChildren}{\param{const wxTreeItemId\&}{ item}, \param{bool }{hasChildren = {\tt true}}}
+\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,
 
 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,


@@ -923,7 +960,8 @@ for the description of the {\it which} parameter.
 
 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 
 
 \func{void}{SetItemSelectedImage}{\param{const wxTreeItemId\&}{ item}, \param{int }{selImage}}
 

-Sets the selected item image (this function is obsolete, use {\tt SetItemImage(item, wxTreeItemIcon\_Selected}) instead).
+Sets the selected item image (this function is obsolete, use 
+{\tt SetItemImage(item, wxTreeItemIcon\_Selected)} instead).

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


@@ -1023,3 +1061,64 @@ all items if it does have this style.
 
 Unselects the given item. This works in multiselection controls only.
 
 
 Unselects the given item. This works in multiselection controls only.
 

+
+
+
+
+%% the wxTreeItemId opaque class
+
+
+\section{\class{wxTreeItemId}}\label{wxtreeitemid}
+
+An opaque reference to a tree item.
+
+
+\wxheading{Derived from}
+
+None
+
+\wxheading{Include files}
+
+<wx/treebase.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
+\wxheading{See also}
+
+\helpref{wxTreeCtrl}{wxtreectrl}, \helpref{wxTreeItemData}{wxtreeitemdata},\\
+\helpref{wxTreeCtrl overview}{wxtreectrloverview}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxTreeItemId::wxTreeItemId}\label{wxtreeitemidconstr}
+
+\func{}{wxTreeItemId}{\void}
+
+Default constructor. wxTreemItemIds are not meant to be constructed explicitly by
+the user; they are returned by the \helpref{wxTreeCtrl}{wxtreectrl} functions instead.
+
+
+\membersection{wxTreeItemId::IsOk}\label{wxtreeitemidisok}
+
+\constfunc{bool}{IsOk}{}
+
+Returns \true if this instance is referencing a valid tree item.
+
+
+\membersection{Operators}\label{wxtreeitemidoperators}
+
+\constfunc{void}{operator $!$}{}
+
+Antonym of \helpref{IsOk}{wxtreeitemidisok}, i.e. returns \true only if the
+item is not valid.
+
+
+\constfunc{bool}{operator $==$}{\param{const wxTreeItemId\& }{item}}
+
+\constfunc{bool}{operator $!=$}{\param{const wxTreeItemId\& }{item}}
+
+Operators for comparison between \helpref{wxTreeItemId}{wxtreeitemid} objects.
+