added install

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

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index 80abf3d7b70b99d86b0012b02af1672acf36dd36..6073e3a2ef7c852ac04c2c6ae9fc0a5ed4705e2a 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -3,13 +3,13 @@
 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.
 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
+See \helpref{wxHashMap}{wxhashmap}\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
 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
+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 wxWindows because of portability issues).
 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).


@@ -19,13 +19,12 @@ 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
 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
+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}
 
 (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
 \begin{verbatim}
     // this part might be in a header or source (.cpp) file
     class MyListElement


@@ -35,24 +34,24 @@ macros):
 
     // declare our list class: this macro declares and partly implements MyList
     // class (which derives from wxListBase)
 
     // declare our list class: this macro declares and partly implements MyList
     // class (which derives from wxListBase)

-    WX_DECLARE_LIST(MyListElement, MyList)
+    WX_DECLARE_LIST(MyListElement, MyList);

 
     ...
 
 
     ...
 

-    // the only requirment for the rest is to be AFTER the full declaration of
+    // 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>
     // 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)
+    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;
 
     // 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
+    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() )
 
     // let's iterate over the list
     for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )


@@ -62,17 +61,26 @@ macros):
         ...process the current element...
     }
 \end{verbatim}
         ...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
 
 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.
+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{Derived from}
 
 \helpref{wxObject}{wxobject}
 

-{\bf WARNING: } the rest of documentation may be out-of-date.
+\wxheading{Include files}
+
+<wx/list.h>

 
 \wxheading{Example}
 
 
 \wxheading{Example}
 


@@ -80,21 +88,21 @@ It is very common to iterate on a list as follows:
 
 \begin{verbatim}
   ...
 
 \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 = node->GetData();

     ...
     ...

-    node = node->Next();
+    node = node->GetNext();

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


@@ -102,7 +110,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}
 


@@ -110,19 +118,15 @@ with
 
 \begin{verbatim}
     ...
 
 \begin{verbatim}
     ...

-    delete point;
+    delete win;

     delete node;
     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.
 
     ...
 \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},
 \wxheading{See also}
 
 \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},


@@ -136,9 +140,9 @@ types (such as char*) may be used with appropriate casting.
 
 \func{}{wxList}{\param{unsigned int}{ key\_type}}
 
 
 \func{}{wxList}{\param{unsigned int}{ key\_type}}
 

-\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}
+\func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}}

 
 

-\func{}{wxList}{\param{wxObject *}{object}, ...}
+\func{}{wxList}{\param{T *}{object}, ...}

 
 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
 and indicates what sort of keying is required (if any).
 
 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
 and indicates what sort of keying is required (if any).


@@ -155,104 +159,141 @@ terminating NULL.
 Destroys the list.  Also destroys any remaining nodes, but does not destroy
 client data held in the nodes.
 
 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}}
+\func{wxNode<T> *}{Append}{\param{long}{ key}, \param{T *}{object}}

 
 

-\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}}
+\func{wxNode<T> *}{Append}{\param{const wxString\& }{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.
+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.
 
 
 The key string is copied and stored by the list implementation.
 

-\membersection{wxList::Clear}
+\membersection{wxList::Clear}\label{wxlistclear}

 
 \func{void}{Clear}{\void}
 
 
 \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}}
 
 
 \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
 
 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::Find}
+\membersection{wxList::Find}\label{wxlistfind}

 
 

-\func{wxNode *}{Find}{\param{long}{ key}}
+\func{wxNode<T> *}{Find}{\param{T *}{ object}}

 
 

-\func{wxNode *}{Find}{\param{const wxString\& }{key}}
+Returns the node whose client date is {\it object} or NULL if none found.
+
+\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.
 
 
 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}

 
 

-\func{wxNode *}{First}{\void}
+Returns the number of elements in the list.
+
+\membersection{wxList::GetFirst}\label{wxlistgetfirst}
+
+\func{wxNode<T> *}{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}
+\membersection{wxList::GetLast}\label{wxlistgetlast}
+
+\func{wxNode<T> *}{GetLast}{\void}
+
+Returns the last node in the list (NULL if the list is empty).

 
 

-\func{int}{IndexOf}{\param{wxObject*}{ obj }}
+\membersection{wxList::IndexOf}\label{wxlistindexof}

 
 

-Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj}
+\func{int}{IndexOf}{\param{T*}{ obj }}
+
+Returns the index of {\it obj} within the list or wxNOT\_FOUND if {\it obj} 

 is not found in the list.
 
 is not found in the list.
 

-\membersection{wxList::Insert}
+\membersection{wxList::Insert}\label{wxlistinsert}

 
 

-\func{wxNode *}{Insert}{\param{wxObject *}{object}}
+\func{wxNode<T> *}{Insert}{\param{T *}{object}}

 
 Insert object at front of list.
 
 
 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.
 
 
 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).
 
 
 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}
 
 
 \func{int}{Number}{\void}
 

+{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
+

 Returns the number of elements in the list.
 
 Returns the number of elements in the list.
 

-\membersection{wxList::Sort}
+\membersection{wxList::Sort}\label{wxlistsort}

 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 
 
 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 


@@ -263,8 +304,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
 
 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:
 
 
 Example:
 


@@ -286,4 +331,3 @@ Example:
   }
 \end{verbatim}
 
   }
 \end{verbatim}
 

-