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

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.
 
+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}
@@ -94,9 +98,9 @@ It is very common to iterate on a list as follows:
   wxNode *node = SomeList.GetFirst();
   while (node)
   {
-    wxWindow *win = (wxWindow *)node->Data();
+    wxWindow *win = node->GetData();
     ...
-    node = node->Next();
+    node = node->GetNext();
   }
 \end{verbatim}
 
@@ -104,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}
 
@@ -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.
 
-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},
@@ -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.
 
+\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::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 }}
@@ -224,27 +236,37 @@ is not found in the 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}}
 
+{\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}}
 
+{\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).
 
@@ -252,6 +274,8 @@ or the nth node could not be found).
 
 \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}

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); }
+        // 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);
 
@@ -402,6 +406,8 @@ private:
             { 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); }        \
                                                                             \