added wxList::Insert(size_t); updated wxList documentation

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

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 8cdcdf03f81fa30caf4bfb717b3da8b50885f727..f3fd9c8e1bb6ef41f2d950e7fda242be09be71bd 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -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},


@@ -205,12 +205,24 @@ 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::GetCount}\label{wxlistgetcount}
+
+\constfunc{size\_t}{GetCount}{\void}
+
+Returns the number of elements in the list.
+

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

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

 \membersection{wxList::IndexOf}
 
 \func{int}{IndexOf}{\param{wxObject*}{ obj }}
 \membersection{wxList::IndexOf}
 
 \func{int}{IndexOf}{\param{wxObject*}{ obj }}


@@ -224,27 +236,37 @@ is not found in the list.
 
 Insert object at front of list.
 
 
 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}
 
 \func{wxNode *}{Member}{\param{wxObject *}{object}}
 
 
 \membersection{wxList::Member}
 
 \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}
 
 \func{wxNode *}{Nth}{\param{int}{ n}}
 
 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 
 \membersection{wxList::Nth}
 
 \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).
 


@@ -252,6 +274,8 @@ or the nth node could not be found).
 
 \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.
 
 \membersection{wxList::Sort}
 Returns the number of elements in the list.
 
 \membersection{wxList::Sort}

diff --git a/include/wx/list.h b/include/wx/list.h
index 496093094638fa4fdcf176f2b9395913075acdb7..7cad34a4207dd9b7592cae7c981f11e16807c947 100644 (file)
--- a/include/wx/list.h
+++ b/include/wx/list.h
@@ -267,6 +267,10 @@ protected:
     wxNodeBase *Append(void *object);
         // insert a new item at the beginning of the list
     wxNodeBase *Insert(void *object) { return Insert( (wxNodeBase*)NULL, object); }
     wxNodeBase *Append(void *object);
         // insert a new item at the beginning of the list
     wxNodeBase *Insert(void *object) { return Insert( (wxNodeBase*)NULL, object); }

+        // insert a new item at the given position
+    wxNodeBase *Insert(size_t pos, void *object)
+        { return pos == GetCount() ? Append(object)
+                                   : Insert(Item(pos), object); }

         // insert before given node or at front of list if prev == NULL
     wxNodeBase *Insert(wxNodeBase *prev, void *object);
 
         // insert before given node or at front of list if prev == NULL
     wxNodeBase *Insert(wxNodeBase *prev, void *object);
 


@@ -402,6 +406,8 @@ private:
             { return (nodetype *)wxListBase::Append(object); }              \
         nodetype *Insert(Tbase *object)                                     \
             { return (nodetype *)Insert((nodetype*)NULL, object); }         \
             { return (nodetype *)wxListBase::Append(object); }              \
         nodetype *Insert(Tbase *object)                                     \
             { return (nodetype *)Insert((nodetype*)NULL, object); }         \

+        nodetype *Insert(size_t pos, Tbase *object)                         \
+            { return (nodetype *)wxListBase::Insert(pos, object); }         \

         nodetype *Insert(nodetype *prev, Tbase *object)                     \
             { return (nodetype *)wxListBase::Insert(prev, object); }        \
                                                                             \
         nodetype *Insert(nodetype *prev, Tbase *object)                     \
             { return (nodetype *)wxListBase::Insert(prev, object); }        \
                                                                             \