change configure to better detect gstreamer. Check create is valid in mediaplayer...

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

diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex
index f7a6cd830a27d9cf145c59babf1bfa3ee4686a6d..1bce91d35e3abb45f0bf87c0b51a026a150f7f0f 100644 (file)
--- a/docs/latex/wx/list.tex
+++ b/docs/latex/wx/list.tex
@@ -1,18 +1,19 @@
 \section{\class{wxList}}\label{wxlist}
 
 \section{\class{wxList}}\label{wxlist}
 

-wxList classes provide linked list functionality for wxWindows, and for an
+wxList classes provide linked list functionality for wxWidgets, and for an

 application if it wishes.  Depending on the form of constructor used, a list
 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.
+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.
 
 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
+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
 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 wxWindows because of portability issues).
+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
 
 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


@@ -68,9 +69,11 @@ 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.
 
 it is not only unsafe but is also much less efficient than 
 \helpref{wxArrayString}{wxarraystring} class.
 

-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.
+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}
 
 
 \wxheading{Derived from}
 


@@ -127,20 +130,22 @@ members for getting to the next or previous node.
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

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

 \helpref{wxArray}{wxarray}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \helpref{wxArray}{wxarray}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxList::wxList}
+\membersection{wxList::wxList}\label{wxlistctor}

 
 \func{}{wxList}{\void}
 
 
 \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).
 
 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
 and indicates what sort of keying is required (if any).


@@ -150,7 +155,7 @@ and indicates what sort of keying is required (if any).
 The variable-length argument list constructor must be supplied with a
 terminating NULL.
 
 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}
 
 
 \func{}{\destruct{wxList}}{\void}
 


@@ -159,15 +164,18 @@ client data held in the nodes.
 
 \membersection{wxList::Append}\label{wxlistappend}
 
 
 \membersection{wxList::Append}\label{wxlistappend}
 

-\func{wxNode *}{Append}{\param{wxObject *}{object}}
+\func{wxNode<T> *}{Append}{\param{T *}{object}}
+
+{\bf Note}: keyed lists are deprecated and should not be used in new code.

 
 

-\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.
 


@@ -176,33 +184,45 @@ The key string is copied and stored by the list implementation.
 \func{void}{Clear}{\void}
 
 Clears the list (but does not delete the client data stored with each node
 \func{void}{Clear}{\void}
 
 Clears the list (but does not delete the client data stored with each node

-unless you called DeleteContents(TRUE), in which case it deletes data).
+unless you called DeleteContents({\tt true}), in which case it deletes data).

 
 \membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 
 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 
 
 \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}\label{wxlistdeletenode}
 
 
 \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}\label{wxlistdeleteobject}
 
 
 \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::Erase}\label{wxlisterase}
+
+\func{void}{Erase}{\param{wxNode<T> *}{node}}
+
+Removes element at given position.

 
 \membersection{wxList::Find}\label{wxlistfind}
 
 
 \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.
+
+{\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.
 
 
 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 


@@ -214,49 +234,56 @@ Returns the number of elements in the list.
 
 \membersection{wxList::GetFirst}\label{wxlistgetfirst}
 
 
 \membersection{wxList::GetFirst}\label{wxlistgetfirst}
 

-\func{wxNode *}{GetFirst}{\void}
+\func{wxNode<T> *}{GetFirst}{\void}

 
 Returns the first node in the list (NULL if the list is empty).
 
 \membersection{wxList::GetLast}\label{wxlistgetlast}
 
 
 Returns the first node in the list (NULL if the list is empty).
 
 \membersection{wxList::GetLast}\label{wxlistgetlast}
 

-\func{wxNode *}{GetLast}{\void}
+\func{wxNode<T> *}{GetLast}{\void}

 
 Returns the last node in the list (NULL if the list is empty).
 
 \membersection{wxList::IndexOf}\label{wxlistindexof}
 
 
 Returns the last node in the list (NULL if the list is empty).
 
 \membersection{wxList::IndexOf}\label{wxlistindexof}
 

-\func{int}{IndexOf}{\param{wxObject*}{ obj }}
+\func{int}{IndexOf}{\param{T*}{ obj }}

 
 

-Returns the index of {\it obj} within the list or wxNOT\_FOUND if {\it obj} 
+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}
 
 is not found in the list.
 
 \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{size\_t }{position}, \param{wxObject *}{object}}
+\func{wxNode<T> *}{Insert}{\param{size\_t }{position}, \param{T *}{object}}

 
 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}.
 
 
 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}}
+\func{wxNode<T> *}{Insert}{\param{wxNode<T> *}{node}, \param{T *}{object}}

 
 Inserts the object before the given {\it node}.
 
 
 Inserts the object before the given {\it node}.
 

-\membersection{wxList::Item}\label{wxlistitem}
+\membersection{wxList::IsEmpty}\label{wxlistisempty}
+
+\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 *}{Item}{\param{size\_t }{index}}
+\constfunc{wxNode<T> *}{Item}{\param{size\_t }{index}}

 
 Returns the node at given position in the list.
 
 \membersection{wxList::Member}\label{wxlistmember}
 
 
 Returns the node at given position in the list.
 
 \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.
 
 
 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
 


@@ -264,9 +291,9 @@ Returns the node associated with {\it object} if it is in the list, NULL otherwi
 
 \membersection{wxList::Nth}\label{wxlistnth}
 
 
 \membersection{wxList::Nth}\label{wxlistnth}
 

-\func{wxNode *}{Nth}{\param{int}{ n}}
+\func{wxNode<T> *}{Nth}{\param{int}{ n}}

 
 

-{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead.
+{\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).