wxProcess fixes (Detach() added), cleared/corrected wxExecute() documentation

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

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index a3ac3e840e95af830f337aee5f26980668992c00..af43ec1d2cc5c3655f7290f74a8aa27a9e99d20b 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -1,33 +1,100 @@
 \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 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.
+
+While wxList class in the previous versions of wxWindows 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 stricter 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 wxWindows 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\_IMPLEMENT\_LIST} macros like this
+(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
+macros):
+
+\wxheading{Example}
+
+{\small%
+\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 requirment 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.Add(element);      // ok
+    list.Add(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.
 
 \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 = (wxWindow *)node->Data();
     ...
     node = node->Next();
   }
@@ -45,9 +112,9 @@ with
 
 \begin{verbatim}
     ...
-    delete point;
+    delete win;
     delete node;
-    node = SomeList.First();
+    node = SomeList.GetFirst();
     ...
 \end{verbatim}
 
@@ -60,11 +127,11 @@ types (such as char*) may be used with appropriate casting.
 
 \wxheading{See also}
 
-\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}
+\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},
+\helpref{wxArray}{wxarray}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-
 \membersection{wxList::wxList}
 
 \func{}{wxList}{\void}
@@ -110,7 +177,7 @@ The key string is copied and stored by the list implementation.
 
 Clears the list (but does not delete the client data stored with each node).
 
-\membersection{wxList::DeleteContents}
+\membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 
 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 
@@ -138,9 +205,9 @@ 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::GetFirst}
 
-\func{wxNode *}{First}{\void}
+\func{wxNode *}{GetFirst}{\void}
 
 Returns the first node in the list (NULL if the list is empty).
 
@@ -162,9 +229,9 @@ Insert object at front of list.
 Insert object before {\it position}.
 
 
-\membersection{wxList::Last}
+\membersection{wxList::GetLast}
 
-\func{wxNode *}{Last}{\void}
+\func{wxNode *}{GetLast}{\void}
 
 Returns the last node in the list (NULL if the list is empty).