wxEvent::Skip() clarification added

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

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 3af91125d335dbeb1cf9a1dc083546869e1d51ca..af43ec1d2cc5c3655f7290f74a8aa27a9e99d20b 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -1,33 +1,100 @@
 \section{\class{wxList}}\label{wxlist}
 
 \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{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}
   ...
 \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;
 
   wxList SomeList;

-  SomeList.Append(point1);
-  SomeList.Append(point2);
+  SomeList.Append(win1);
+  SomeList.Append(win2);

 
   ...
 
 
   ...
 

-  wxNode *node = SomeList.First();
+  wxNode *node = SomeList.GetFirst();

   while (node)
   {
   while (node)
   {

-    wxPoint *point = (wxPoint *)node->Data();
+    wxWindow *win = (wxWindow *)node->Data();

     ...
     node = node->Next();
   }
     ...
     node = node->Next();
   }


@@ -45,9 +112,9 @@ with
 
 \begin{verbatim}
     ...
 
 \begin{verbatim}
     ...

-    delete point;
+    delete win;

     delete node;
     delete node;

-    node = SomeList.First();
+    node = SomeList.GetFirst();

     ...
 \end{verbatim}
 
     ...
 \end{verbatim}
 


@@ -60,11 +127,11 @@ types (such as char*) may be used with appropriate casting.
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}
+\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},
+\helpref{wxArray}{wxarray}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-

 \membersection{wxList::wxList}
 
 \func{}{wxList}{\void}
 \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).
 
 
 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}}
 
 
 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 


@@ -138,12 +205,19 @@ 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::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).
 
 
 Returns the first node in the list (NULL if the list is empty).
 

+\membersection{wxList::IndexOf}
+
+\func{int}{IndexOf}{\param{wxObject*}{ 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}
 
 \func{wxNode *}{Insert}{\param{wxObject *}{object}}
 \membersection{wxList::Insert}
 
 \func{wxNode *}{Insert}{\param{wxObject *}{object}}


@@ -155,9 +229,9 @@ Insert object at front of list.
 Insert object before {\it position}.
 
 
 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).
 
 
 Returns the last node in the list (NULL if the list is empty).