X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6e6110ee8194ee39944dffd57cce9f22cd8b961e..80d2803f703d1b238f42725504f08266ef02defe:/docs/latex/wx/list.tex?ds=sidebyside

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 80abf3d7b7..663ac42594 100644
--- 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)
-    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>
-    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
@@ -68,11 +68,17 @@ 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.
 
+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}
 
-{\bf WARNING: } the rest of documentation may be out-of-date.
+\wxheading{Include files}
+
+<wx/list.h>
 
 \wxheading{Example}
 
@@ -80,21 +86,21 @@ It is very common to iterate on a list as follows:
 
 \begin{verbatim}
   ...
-  wxPoint *point1 = new wxPoint(100, 100);
-  wxPoint *point2 = new wxPoint(200, 200);
+  wxWindow *win1 = new wxWindow(...);
+  wxWindow *win2 = new wxWindow(...);
 
   wxList SomeList;
-  SomeList.Append(point1);
-  SomeList.Append(point2);
+  SomeList.Append(win1);
+  SomeList.Append(win2);
 
   ...
 
-  wxNode *node = SomeList.First();
+  wxNode *node = SomeList.GetFirst();
   while (node)
   {
-    wxPoint *point = (wxPoint *)node->Data();
+    wxWindow *win = node->GetData();
     ...
-    node = node->Next();
+    node = node->GetNext();
   }
 \end{verbatim}
 
@@ -102,7 +108,7 @@ To delete nodes in a list as the list is being traversed, replace
 
 \begin{verbatim}
     ...
-    node = node->Next();
+    node = node->GetNext();
     ...
 \end{verbatim}
 
@@ -110,19 +116,15 @@ with
 
 \begin{verbatim}
     ...
-    delete point;
+    delete win;
     delete node;
-    node = SomeList.First();
+    node = SomeList.GetFirst();
     ...
 \end{verbatim}
 
 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},
@@ -155,7 +157,7 @@ terminating NULL.
 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}}
 
@@ -169,33 +171,34 @@ later retrieval using the key. The new node is returned in each case.
 
 The key string is copied and stored by the list implementation.
 
-\membersection{wxList::Clear}
+\membersection{wxList::Clear}\label{wxlistclear}
 
 \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}
+\membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 
 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 
 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.
 
-\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.
 
-\membersection{wxList::Find}
+\membersection{wxList::Find}\label{wxlistfind}
 
 \func{wxNode *}{Find}{\param{long}{ key}}
 
@@ -203,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.
 
-\membersection{wxList::First}
+\membersection{wxList::GetCount}\label{wxlistgetcount}
 
-\func{wxNode *}{First}{\void}
+\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).
 
-\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 }}
 
-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.
 
-\membersection{wxList::Insert}
+\membersection{wxList::Insert}\label{wxlistinsert}
 
 \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::Last}
+Inserts the object before the given {\it node}.
 
-\func{wxNode *}{Last}{\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}}
 
+{\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.
 
-\membersection{wxList::Nth}
+\membersection{wxList::Nth}\label{wxlistnth}
 
 \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).
 
-\membersection{wxList::Number}
+\membersection{wxList::Number}\label{wxlistnumber}
 
 \func{int}{Number}{\void}
 
+{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
+
 Returns the number of elements in the list.
 
-\membersection{wxList::Sort}
+\membersection{wxList::Sort}\label{wxlistsort}
 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 
@@ -286,4 +313,3 @@ Example:
   }
 \end{verbatim}
 
-