X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..9379c0d752144826342fa2688a77aa5cccea3d9b:/docs/latex/wx/list.tex?ds=sidebyside

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 3af91125d3..5144cf38d3 100644
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -1,35 +1,120 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        list.tex
+%% Purpose:     wxList
+%% Author:      wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxWidgets Team
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \section{\class{wxList}}\label{wxlist}
 
-This class provides linked list functionality for wxWindows, and for an application
-if it wishes.  Depending on the form of constructor used, a list can be keyed on
-integer or string keys to provide a primitive look-up ability. See \helpref{wxHashTable}{wxhashtable}\rtfsp
-for a faster method of storage when random access is required.
+wxList classes provide linked list functionality for wxWidgets, and for an
+application if it wishes.  Depending on the form of constructor used, a list
+can be keyed on integer or string keys to provide a primitive look-up ability,
+but please note that this feature is {\bf deprecated}.
+See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage
+when random access is required.
+
+While wxList class in the previous versions of wxWidgets only could contain
+elements of type wxObject and had essentially untyped interface (thus allowing
+you to put apples in the list and read back oranges from it), the new wxList
+classes family may contain elements of any type and has much more strict type
+checking. Unfortunately, it also requires an additional line to be inserted in
+your program for each list class you use (which is the only solution short of
+using templates which is not done in wxWidgets because of portability issues).
+
+The general idea is to have the base class wxListBase working with {\it void *}
+data but make all of its dangerous (because untyped) functions protected, so
+that they can only be used from derived classes which, in turn, expose a type
+safe interface. With this approach a new wxList-like class must be defined for
+each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done
+with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this
+(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
+macros):
+
+\wxheading{Example}
+
+\begin{verbatim}
+    // this part might be in a header or source (.cpp) file
+    class MyListElement
+    {
+        ... // whatever
+    };
+
+    // declare our list class: this macro declares and partly implements MyList
+    // class (which derives from wxListBase)
+    WX_DECLARE_LIST(MyListElement, MyList);
+
+    ...
+
+    // the only requirement for the rest is to be AFTER the full declaration of
+    // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
+    // usually it will be found in the source file and not in the header
+
+    #include <wx/listimpl.cpp>
+    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
+    // also have MyList::Node type which is the type-safe version of wxNode.
+    MyList list;
+    MyListElement element;
+    list.Append(&element);     // ok
+    list.Append(17);           // error: incorrect type
+
+    // let's iterate over the list
+    for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
+    {
+        MyListElement *current = node->GetData();
+
+        ...process the current element...
+    }
+\end{verbatim}
+
+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. The use of the latter is especially discouraged as
+it is not only unsafe but is also much less efficient than
+\helpref{wxArrayString}{wxarraystring} class.
+
+In the documentation of the list classes below, the template notations are
+used even though these classes are not really templates at all -- but it helps
+to think about them as if they were. You should replace wxNode<T> with
+wxListName::Node and T itself with the list element type (i.e. the first
+parameter of WX\_DECLARE\_LIST).
 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 
+\wxheading{Include files}
+
+<wx/list.h>
+
 \wxheading{Example}
 
 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}
 
@@ -37,7 +122,7 @@ To delete nodes in a list as the list is being traversed, replace
 
 \begin{verbatim}
     ...
-    node = node->Next();
+    node = node->GetNext();
     ...
 \end{verbatim}
 
@@ -45,35 +130,33 @@ 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}
+\helpref{wxNode}{wxnode},
+\helpref{wxArray}{wxarray}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-
-\membersection{wxList::wxList}
+\membersection{wxList::wxList}\label{wxlistctor}
 
 \func{}{wxList}{\void}
 
-\func{}{wxList}{\param{unsigned int}{ key\_type}}
+\func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}}
+
+\func{}{wxList}{\param{T *}{object}, ...}
 
-\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}
+{\bf Note}: keyed lists are deprecated and should not be used in new code.
 
-\func{}{wxList}{\param{wxObject *}{object}, ...}
+\func{}{wxList}{\param{unsigned int}{ key\_type}}
 
 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
 and indicates what sort of keying is required (if any).
@@ -83,104 +166,158 @@ and indicates what sort of keying is required (if any).
 The variable-length argument list constructor must be supplied with a
 terminating NULL.
 
-\membersection{wxList::\destruct{wxList}}
+\membersection{wxList::\destruct{wxList}}\label{wxlistdtor}
 
 \func{}{\destruct{wxList}}{\void}
 
 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<T> *}{Append}{\param{T *}{object}}
 
-\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}}
+{\bf Note}: keyed lists are deprecated and should not be used in new code.
 
-\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}}
+\func{wxNode<T> *}{Append}{\param{long}{ key}, \param{T *}{object}}
 
-Appends a new {\bf wxNode} to the end of the list and puts a pointer to the
-\rtfsp{\it object} in the node.  The last two forms store a key with the object for
-later retrieval using the key. The new node is returned in each case.
+\func{wxNode<T> *}{Append}{\param{const wxString\& }{key}, \param{T *}{object}}
+
+Appends a new \helpref{wxNode}{wxnode} to the end of the list and puts a
+pointer to the \rtfsp{\it object} in the node.  The last two forms store a key
+with the object for 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({\tt 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.
+If {\it destroy} is {\tt true}, instructs the list to call {\it delete} on the client contents of
+a node whenever the node is destroyed. The default is {\tt false}.
 
-\membersection{wxList::DeleteNode}
+\membersection{wxList::DeleteNode}\label{wxlistdeletenode}
 
-\func{bool}{DeleteNode}{\param{wxNode *}{node}}
+\func{bool}{DeleteNode}{\param{wxNode<T> *}{node}}
 
-Deletes the given node from the list, returning TRUE if successful.
+Deletes the given node from the list, returning {\tt true} if successful.
 
-\membersection{wxList::DeleteObject}
+\membersection{wxList::DeleteObject}\label{wxlistdeleteobject}
 
-\func{bool}{DeleteObject}{\param{wxObject *}{object}}
+\func{bool}{DeleteObject}{\param{T *}{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.
+{\tt true} if successful. The application must delete the actual object separately.
+
+\membersection{wxList::Erase}\label{wxlisterase}
+
+\func{void}{Erase}{\param{wxNode<T> *}{node}}
 
-\membersection{wxList::Find}
+Removes element at given position.
 
-\func{wxNode *}{Find}{\param{long}{ key}}
+\membersection{wxList::Find}\label{wxlistfind}
 
-\func{wxNode *}{Find}{\param{const wxString\& }{key}}
+\func{wxNode<T> *}{Find}{\param{T *}{ object}}
+
+Returns the node whose client data is {\it object} or NULL if none found.
+
+{\bf Note}: keyed lists are deprecated and should not be used in new code.
+
+\func{wxNode<T> *}{Find}{\param{long}{ key}}
+
+\func{wxNode<T> *}{Find}{\param{const wxString\& }{key}}
 
 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 
-\membersection{wxList::First}
+\membersection{wxList::GetCount}\label{wxlistgetcount}
+
+\constfunc{size\_t}{GetCount}{\void}
+
+Returns the number of elements in the list.
 
-\func{wxNode *}{First}{\void}
+\membersection{wxList::GetFirst}\label{wxlistgetfirst}
+
+\func{wxNode<T> *}{GetFirst}{\void}
 
 Returns the first node in the list (NULL if the list is empty).
 
-\membersection{wxList::Insert}
+\membersection{wxList::GetLast}\label{wxlistgetlast}
+
+\func{wxNode<T> *}{GetLast}{\void}
+
+Returns the last node in the list (NULL if the list is empty).
+
+\membersection{wxList::IndexOf}\label{wxlistindexof}
+
+\func{int}{IndexOf}{\param{T*}{ obj }}
 
-\func{wxNode *}{Insert}{\param{wxObject *}{object}}
+Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if {\it obj}
+is not found in the list.
+
+\membersection{wxList::Insert}\label{wxlistinsert}
+
+\func{wxNode<T> *}{Insert}{\param{T *}{object}}
 
 Insert object at front of list.
 
-\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
+\func{wxNode<T> *}{Insert}{\param{size\_t }{position}, \param{T *}{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<T> *}{Insert}{\param{wxNode<T> *}{node}, \param{T *}{object}}
 
-\membersection{wxList::Last}
+Inserts the object before the given {\it node}.
 
-\func{wxNode *}{Last}{\void}
+\membersection{wxList::IsEmpty}\label{wxlistisempty}
 
-Returns the last node in the list (NULL if the list is empty).
+\constfunc{bool}{IsEmpty}{\void}
+
+Returns {\tt true} if the list is empty, {\tt false} otherwise.
+
+% Use different label name to avoid clashing with wxListItem label
+\membersection{wxList::Item}\label{wxlistitemfunc}
+
+\constfunc{wxNode<T> *}{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<T> *}{Member}{\param{T *}{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<T> *}{Nth}{\param{int}{ n}}
 
-\func{wxNode *}{Nth}{\param{int}{ n}}
+{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} 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}}
 
@@ -191,8 +328,12 @@ Returns the number of elements in the list.
 
 Allows the sorting of arbitrary lists by giving
 a function to compare two list elements. We use the system {\bf qsort} function
-for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **),
-so be careful to dereference appropriately.
+for the actual sorting process.
+
+If you use untyped wxList the sort function receives pointers to wxObject
+pointers (wxObject **), so be careful to dereference appropriately - but,
+of course, a better solution is to use list of appropriate type defined with
+{\tt WX\_DECLARE\_LIST}.
 
 Example:
 
@@ -200,7 +341,7 @@ Example:
   int listcompare(const void *arg1, const void *arg2)
   {
     return(compare(**(wxString **)arg1,    // use the wxString 'compare'
-                   **(wxString **)arg2));  // function 
+                   **(wxString **)arg2));  // function
   }
 
   void main()
@@ -213,5 +354,3 @@ Example:
     list.Sort(listcompare);
   }
 \end{verbatim}
-
-
