1998-05-20 10:25:30 -04:00
|
|
|
\section{\class{wxList}}\label{wxlist}
|
|
|
|
|
1999-01-02 18:02:30 -05:00
|
|
|
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.
|
2002-01-29 16:31:16 -05:00
|
|
|
See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage
|
1999-01-02 18:02:30 -05:00
|
|
|
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
|
2000-11-24 09:27:09 -05:00
|
|
|
classes family may contain elements of any type and has much more strict type
|
1999-01-02 18:02:30 -05:00
|
|
|
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
|
2000-11-05 09:04:04 -05:00
|
|
|
with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this
|
1999-01-02 18:02:30 -05:00
|
|
|
(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
|
|
|
|
macros):
|
|
|
|
|
|
|
|
\wxheading{Example}
|
|
|
|
|
|
|
|
\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)
|
1999-06-27 07:26:50 -04:00
|
|
|
WX_DECLARE_LIST(MyListElement, MyList);
|
1999-01-02 18:02:30 -05:00
|
|
|
|
|
|
|
...
|
|
|
|
|
|
|
|
// 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>
|
1999-06-27 07:26:50 -04:00
|
|
|
WX_DEFINE_LIST(MyList);
|
1999-01-02 18:02:30 -05:00
|
|
|
|
|
|
|
// 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;
|
2000-11-05 09:04:04 -05:00
|
|
|
list.Append(element); // ok
|
|
|
|
list.Append(17); // error: incorrect type
|
1999-01-02 18:02:30 -05:00
|
|
|
|
|
|
|
// 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
|
2000-11-06 06:43:17 -05:00
|
|
|
future versions completely. The use of the latter is especially discouraged as
|
|
|
|
it is not only unsafe but is also much less efficient than
|
2000-11-22 06:45:41 -05:00
|
|
|
\helpref{wxArrayString}{wxarraystring} class.
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
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.
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
\wxheading{Derived from}
|
|
|
|
|
|
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
|
1999-02-15 15:41:29 -05:00
|
|
|
\wxheading{Include files}
|
|
|
|
|
|
|
|
<wx/list.h>
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
\wxheading{Example}
|
|
|
|
|
|
|
|
It is very common to iterate on a list as follows:
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
...
|
1999-01-24 09:57:09 -05:00
|
|
|
wxWindow *win1 = new wxWindow(...);
|
|
|
|
wxWindow *win2 = new wxWindow(...);
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
wxList SomeList;
|
1999-01-24 09:57:09 -05:00
|
|
|
SomeList.Append(win1);
|
|
|
|
SomeList.Append(win2);
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
...
|
|
|
|
|
1999-01-21 12:38:28 -05:00
|
|
|
wxNode *node = SomeList.GetFirst();
|
1998-05-20 10:25:30 -04:00
|
|
|
while (node)
|
|
|
|
{
|
1999-12-13 14:30:09 -05:00
|
|
|
wxWindow *win = node->GetData();
|
1998-05-20 10:25:30 -04:00
|
|
|
...
|
1999-12-13 14:30:09 -05:00
|
|
|
node = node->GetNext();
|
1998-05-20 10:25:30 -04:00
|
|
|
}
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
To delete nodes in a list as the list is being traversed, replace
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
...
|
1999-12-13 14:30:09 -05:00
|
|
|
node = node->GetNext();
|
1998-05-20 10:25:30 -04:00
|
|
|
...
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
with
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
...
|
1999-01-24 09:57:09 -05:00
|
|
|
delete win;
|
1998-05-20 10:25:30 -04:00
|
|
|
delete node;
|
1999-01-21 12:38:28 -05:00
|
|
|
node = SomeList.GetFirst();
|
1998-05-20 10:25:30 -04:00
|
|
|
...
|
|
|
|
\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.
|
|
|
|
|
|
|
|
\wxheading{See also}
|
|
|
|
|
1999-01-02 18:02:30 -05:00
|
|
|
\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},
|
|
|
|
\helpref{wxArray}{wxarray}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
|
|
\membersection{wxList::wxList}
|
|
|
|
|
|
|
|
\func{}{wxList}{\void}
|
|
|
|
|
|
|
|
\func{}{wxList}{\param{unsigned int}{ key\_type}}
|
|
|
|
|
|
|
|
\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}
|
|
|
|
|
|
|
|
\func{}{wxList}{\param{wxObject *}{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).
|
|
|
|
|
|
|
|
{\it objects} is an array of {\it n} objects with which to initialize the list.
|
|
|
|
|
|
|
|
The variable-length argument list constructor must be supplied with a
|
|
|
|
terminating NULL.
|
|
|
|
|
|
|
|
\membersection{wxList::\destruct{wxList}}
|
|
|
|
|
|
|
|
\func{}{\destruct{wxList}}{\void}
|
|
|
|
|
|
|
|
Destroys the list. Also destroys any remaining nodes, but does not destroy
|
|
|
|
client data held in the nodes.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Append}\label{wxlistappend}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{wxNode *}{Append}{\param{wxObject *}{object}}
|
|
|
|
|
|
|
|
\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}}
|
|
|
|
|
|
|
|
\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{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.
|
|
|
|
|
|
|
|
The key string is copied and stored by the list implementation.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Clear}\label{wxlistclear}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{void}{Clear}{\void}
|
|
|
|
|
2000-03-11 05:05:09 -05:00
|
|
|
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).
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-01-12 13:28:34 -05:00
|
|
|
\membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\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.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::DeleteNode}\label{wxlistdeletenode}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{bool}{DeleteNode}{\param{wxNode *}{node}}
|
|
|
|
|
|
|
|
Deletes the given node from the list, returning TRUE if successful.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::DeleteObject}\label{wxlistdeleteobject}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{bool}{DeleteObject}{\param{wxObject *}{object}}
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Find}\label{wxlistfind}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{wxNode *}{Find}{\param{long}{ key}}
|
|
|
|
|
|
|
|
\func{wxNode *}{Find}{\param{const wxString\& }{key}}
|
|
|
|
|
|
|
|
Returns the node whose stored key matches {\it key}. Use on a keyed list only.
|
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
\membersection{wxList::GetCount}\label{wxlistgetcount}
|
|
|
|
|
|
|
|
\constfunc{size\_t}{GetCount}{\void}
|
|
|
|
|
|
|
|
Returns the number of elements in the list.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::GetFirst}\label{wxlistgetfirst}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-01-21 12:38:28 -05:00
|
|
|
\func{wxNode *}{GetFirst}{\void}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
Returns the first node in the list (NULL if the list is empty).
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::GetLast}\label{wxlistgetlast}
|
1999-12-13 14:30:09 -05:00
|
|
|
|
|
|
|
\func{wxNode *}{GetLast}{\void}
|
|
|
|
|
|
|
|
Returns the last node in the list (NULL if the list is empty).
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::IndexOf}\label{wxlistindexof}
|
1998-12-02 05:32:03 -05:00
|
|
|
|
|
|
|
\func{int}{IndexOf}{\param{wxObject*}{ obj }}
|
|
|
|
|
2001-02-16 13:49:47 -05:00
|
|
|
Returns the index of {\it obj} within the list or wxNOT\_FOUND if {\it obj}
|
1998-12-02 05:32:03 -05:00
|
|
|
is not found in the list.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Insert}\label{wxlistinsert}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{wxNode *}{Insert}{\param{wxObject *}{object}}
|
|
|
|
|
|
|
|
Insert object at front of list.
|
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{object}}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
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}.
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
\func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{wxObject *}{object}}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
Inserts the object before the given {\it node}.
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
\membersection{wxList::Item}\label{wxlistitem}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
\constfunc{wxNode *}{Item}{\param{size\_t }{index}}
|
|
|
|
|
|
|
|
Returns the node at given position in the list.
|
1998-05-20 10:25:30 -04:00
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Member}\label{wxlistmember}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{wxNode *}{Member}{\param{wxObject *}{object}}
|
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
Returns the node associated with {\it object} if it is in the list, NULL otherwise.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Nth}\label{wxlistnth}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{wxNode *}{Nth}{\param{int}{ n}}
|
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead.
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
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).
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Number}\label{wxlistnumber}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{int}{Number}{\void}
|
|
|
|
|
1999-12-13 14:30:09 -05:00
|
|
|
{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
|
|
|
|
|
1998-05-20 10:25:30 -04:00
|
|
|
Returns the number of elements in the list.
|
|
|
|
|
1999-12-29 09:21:38 -05:00
|
|
|
\membersection{wxList::Sort}\label{wxlistsort}
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
\func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
// Type of compare function for list sort operation (as in 'qsort')
|
|
|
|
typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
|
|
|
|
\end{verbatim}
|
|
|
|
|
|
|
|
Allows the sorting of arbitrary lists by giving
|
|
|
|
a function to compare two list elements. We use the system {\bf qsort} function
|
2000-11-06 06:41:19 -05:00
|
|
|
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}.
|
1998-05-20 10:25:30 -04:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
int listcompare(const void *arg1, const void *arg2)
|
|
|
|
{
|
|
|
|
return(compare(**(wxString **)arg1, // use the wxString 'compare'
|
|
|
|
**(wxString **)arg2)); // function
|
|
|
|
}
|
|
|
|
|
|
|
|
void main()
|
|
|
|
{
|
|
|
|
wxList list;
|
|
|
|
|
|
|
|
list.Append(new wxString("DEF"));
|
|
|
|
list.Append(new wxString("GHI"));
|
|
|
|
list.Append(new wxString("ABC"));
|
|
|
|
list.Sort(listcompare);
|
|
|
|
}
|
|
|
|
\end{verbatim}
|
|
|
|
|