+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: list.tex
+%% Purpose: wxList
+%% Author: wxWidgets Team
+%% Modified by:
+%% Created:
+%% RCS-ID: $Id$
+%% Copyright: (c) wxWidgets Team
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
-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
+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
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
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
// MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
// usually it will be found in the source file and not in the header
// MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
// usually it will be found in the source file and not in the header
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
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
-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).
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).
-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.
\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}.
-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.
-\func{wxNode *}{Find}{\param{const wxString\& }{key}}
+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 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}
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}
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}.
-\constfunc{wxNode *}{Item}{\param{size\_t }{index}}
+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 {\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).
int listcompare(const void *arg1, const void *arg2)
{
return(compare(**(wxString **)arg1, // use the wxString 'compare'
int listcompare(const void *arg1, const void *arg2)
{
return(compare(**(wxString **)arg1, // use the wxString 'compare'
projects / wxWidgets.git / blobdiff