Added project files for STC; fixed wxStringList memory leaks; small doc changes;

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

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index af43ec1d2cc5c3655f7290f74a8aa27a9e99d20b..663ac4259483feaa1473cc4a64bfd4bafb9e8252 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -35,7 +35,7 @@ macros):
 
     // declare our list class: this macro declares and partly implements MyList
     // class (which derives from wxListBase)
 
     // declare our list class: this macro declares and partly implements MyList
     // class (which derives from wxListBase)

-    WX_DECLARE_LIST(MyListElement, MyList)
+    WX_DECLARE_LIST(MyListElement, MyList);

 
     ...
 
 
     ...
 


@@ -44,7 +44,7 @@ macros):
     // usually it will be found in the source file and not in the header
 
     #include <wx/listimpl.cpp>
     // usually it will be found in the source file and not in the header
 
     #include <wx/listimpl.cpp>

-    WX_DEFINE_LIST(MyList)
+    WX_DEFINE_LIST(MyList);

 
     // now MyList class may be used as a usual wxList, but all of its methods
     // will take/return the objects of the right (i.e. MyListElement) type. You
 
     // now MyList class may be used as a usual wxList, but all of its methods
     // will take/return the objects of the right (i.e. MyListElement) type. You


@@ -68,6 +68,10 @@ For compatibility with previous versions wxList and wxStringList classes are
 still defined, but their usage is deprecated and they will disappear in the
 future versions completely.
 
 still defined, but their usage is deprecated and they will disappear in the
 future versions completely.
 

+In the documentation of the list classes below, you should replace wxNode with
+wxListName::Node and wxObject with the list element type (i.e. the first
+parameter of WX\_DECLARE\_LIST) for the template lists.
+

 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}


@@ -94,9 +98,9 @@ It is very common to iterate on a list as follows:
   wxNode *node = SomeList.GetFirst();
   while (node)
   {
   wxNode *node = SomeList.GetFirst();
   while (node)
   {

-    wxWindow *win = (wxWindow *)node->Data();
+    wxWindow *win = node->GetData();

     ...
     ...

-    node = node->Next();
+    node = node->GetNext();

   }
 \end{verbatim}
 
   }
 \end{verbatim}
 


@@ -104,7 +108,7 @@ To delete nodes in a list as the list is being traversed, replace
 
 \begin{verbatim}
     ...
 
 \begin{verbatim}
     ...

-    node = node->Next();
+    node = node->GetNext();

     ...
 \end{verbatim}
 
     ...
 \end{verbatim}
 


@@ -121,10 +125,6 @@ with
 See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
 members for getting to the next or previous node.
 
 See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
 members for getting to the next or previous node.
 

-Note that a cast is required when retrieving the data from a node.  Although a
-node is defined to store objects of type {\bf wxObject} and derived types, other
-types (such as char*) may be used with appropriate casting.
-

 \wxheading{See also}
 
 \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},
 \wxheading{See also}
 
 \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},


@@ -157,7 +157,7 @@ terminating NULL.
 Destroys the list.  Also destroys any remaining nodes, but does not destroy
 client data held in the nodes.
 
 Destroys the list.  Also destroys any remaining nodes, but does not destroy
 client data held in the nodes.
 

-\membersection{wxList::Append}
+\membersection{wxList::Append}\label{wxlistappend}

 
 \func{wxNode *}{Append}{\param{wxObject *}{object}}
 
 
 \func{wxNode *}{Append}{\param{wxObject *}{object}}
 


@@ -171,11 +171,12 @@ later retrieval using the key. The new node is returned in each case.
 
 The key string is copied and stored by the list implementation.
 
 
 The key string is copied and stored by the list implementation.
 

-\membersection{wxList::Clear}
+\membersection{wxList::Clear}\label{wxlistclear}

 
 \func{void}{Clear}{\void}
 
 
 \func{void}{Clear}{\void}
 

-Clears the list (but does not delete the client data stored with each node).
+Clears the list (but does not delete the client data stored with each node
+unless you called DeleteContents(TRUE), in which case it deletes data).

 
 \membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 
 
 \membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 


@@ -184,20 +185,20 @@ Clears the list (but does not delete the client data stored with each node).
 If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
 a node whenever the node is destroyed. The default is FALSE.
 
 If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
 a node whenever the node is destroyed. The default is FALSE.
 

-\membersection{wxList::DeleteNode}
+\membersection{wxList::DeleteNode}\label{wxlistdeletenode}

 
 \func{bool}{DeleteNode}{\param{wxNode *}{node}}
 
 Deletes the given node from the list, returning TRUE if successful.
 
 
 \func{bool}{DeleteNode}{\param{wxNode *}{node}}
 
 Deletes the given node from the list, returning TRUE if successful.
 

-\membersection{wxList::DeleteObject}
+\membersection{wxList::DeleteObject}\label{wxlistdeleteobject}

 
 \func{bool}{DeleteObject}{\param{wxObject *}{object}}
 
 Finds the given client {\it object} and deletes the appropriate node from the list, returning
 TRUE if successful. The application must delete the actual object separately.
 
 
 \func{bool}{DeleteObject}{\param{wxObject *}{object}}
 
 Finds the given client {\it object} and deletes the appropriate node from the list, returning
 TRUE if successful. The application must delete the actual object separately.
 

-\membersection{wxList::Find}
+\membersection{wxList::Find}\label{wxlistfind}

 
 \func{wxNode *}{Find}{\param{long}{ key}}
 
 
 \func{wxNode *}{Find}{\param{long}{ key}}
 


@@ -205,56 +206,80 @@ TRUE if successful. The application must delete the actual object separately.
 
 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 
 
 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 

-\membersection{wxList::GetFirst}
+\membersection{wxList::GetCount}\label{wxlistgetcount}
+
+\constfunc{size\_t}{GetCount}{\void}
+
+Returns the number of elements in the list.
+
+\membersection{wxList::GetFirst}\label{wxlistgetfirst}

 
 \func{wxNode *}{GetFirst}{\void}
 
 Returns the first node in the list (NULL if the list is empty).
 
 
 \func{wxNode *}{GetFirst}{\void}
 
 Returns the first node in the list (NULL if the list is empty).
 

-\membersection{wxList::IndexOf}
+\membersection{wxList::GetLast}\label{wxlistgetlast}
+
+\func{wxNode *}{GetLast}{\void}
+
+Returns the last node in the list (NULL if the list is empty).
+
+\membersection{wxList::IndexOf}\label{wxlistindexof}

 
 \func{int}{IndexOf}{\param{wxObject*}{ obj }}
 
 
 \func{int}{IndexOf}{\param{wxObject*}{ obj }}
 

-Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj}
+Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} 

 is not found in the list.
 
 is not found in the list.
 

-\membersection{wxList::Insert}
+\membersection{wxList::Insert}\label{wxlistinsert}

 
 \func{wxNode *}{Insert}{\param{wxObject *}{object}}
 
 Insert object at front of list.
 
 
 \func{wxNode *}{Insert}{\param{wxObject *}{object}}
 
 Insert object at front of list.
 

-\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
+\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{object}}

 
 

-Insert object before {\it position}.
+Insert object before {\it position}, i.e. the index of the new item in the
+list will be equal to {\it position}. {\it position} should be less than or
+equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
+same as calling \helpref{Append}{wxlistappend}.

 
 

+\func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{wxObject *}{object}}

 
 

-\membersection{wxList::GetLast}
+Inserts the object before the given {\it node}.

 
 

-\func{wxNode *}{GetLast}{\void}
+\membersection{wxList::Item}\label{wxlistitem}

 
 

-Returns the last node in the list (NULL if the list is empty).
+\constfunc{wxNode *}{Item}{\param{size\_t }{index}}
+
+Returns the node at given position in the list.

 
 

-\membersection{wxList::Member}
+\membersection{wxList::Member}\label{wxlistmember}

 
 \func{wxNode *}{Member}{\param{wxObject *}{object}}
 
 
 \func{wxNode *}{Member}{\param{wxObject *}{object}}
 

+{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
+

 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 
 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 

-\membersection{wxList::Nth}
+\membersection{wxList::Nth}\label{wxlistnth}

 
 \func{wxNode *}{Nth}{\param{int}{ n}}
 
 
 \func{wxNode *}{Nth}{\param{int}{ n}}
 

+{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead.
+

 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 or the nth node could not be found).
 
 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 or the nth node could not be found).
 

-\membersection{wxList::Number}
+\membersection{wxList::Number}\label{wxlistnumber}

 
 \func{int}{Number}{\void}
 
 
 \func{int}{Number}{\void}
 

+{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
+

 Returns the number of elements in the list.
 
 Returns the number of elements in the list.
 

-\membersection{wxList::Sort}
+\membersection{wxList::Sort}\label{wxlistsort}

 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 
 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 


@@ -288,4 +313,3 @@ Example:
   }
 \end{verbatim}
 
   }
 \end{verbatim}
 

-