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):
// 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);
...
// 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;
- 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() )
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, 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.
\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}
\begin{verbatim}
...
- wxPoint *point1 = new wxPoint(100, 100);
- wxPoint *point2 = new wxPoint(200, 200);
+ wxWindow *win1 = new wxWindow(...);
+ wxWindow *win2 = new wxWindow(...);
wxList SomeList;
- SomeList.Append(point1);
- SomeList.Append(point2);
+ SomeList.Append(win1);
+ SomeList.Append(win2);
...
wxNode *node = SomeList.GetFirst();
while (node)
{
- wxPoint *point = (wxPoint *)node->Data();
+ wxWindow *win = node->GetData();
...
- node = node->Next();
+ node = node->GetNext();
}
\end{verbatim}
\begin{verbatim}
...
- node = node->Next();
+ node = node->GetNext();
...
\end{verbatim}
\begin{verbatim}
...
- delete point;
+ delete win;
delete node;
node = SomeList.GetFirst();
...
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},
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}}
The key string is copied and stored by the list implementation.
-\membersection{wxList::Clear}
+\membersection{wxList::Clear}\label{wxlistclear}
\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(TRUE), in which case it deletes data).
\membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
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.
-\membersection{wxList::DeleteNode}
+\membersection{wxList::DeleteNode}\label{wxlistdeletenode}
\func{bool}{DeleteNode}{\param{wxNode *}{node}}
Deletes the given node from the list, returning TRUE if successful.
-\membersection{wxList::DeleteObject}
+\membersection{wxList::DeleteObject}\label{wxlistdeleteobject}
\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.
-\membersection{wxList::Find}
+\membersection{wxList::Find}\label{wxlistfind}
\func{wxNode *}{Find}{\param{long}{ key}}
Returns the node whose stored key matches {\it key}. Use on a keyed list only.
-\membersection{wxList::GetFirst}
+\membersection{wxList::GetCount}\label{wxlistgetcount}
+
+\constfunc{size\_t}{GetCount}{\void}
+
+Returns the number of elements in the list.
+
+\membersection{wxList::GetFirst}\label{wxlistgetfirst}
\func{wxNode *}{GetFirst}{\void}
Returns the first node in the list (NULL if the list is empty).
-\membersection{wxList::IndexOf}
+\membersection{wxList::GetLast}\label{wxlistgetlast}
+
+\func{wxNode *}{GetLast}{\void}
+
+Returns the last node in the list (NULL if the list is empty).
+
+\membersection{wxList::IndexOf}\label{wxlistindexof}
\func{int}{IndexOf}{\param{wxObject*}{ obj }}
-Returns the index of {\it obj} within the list or NOT\_FOUND if {\it 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}
+\membersection{wxList::Insert}\label{wxlistinsert}
\func{wxNode *}{Insert}{\param{wxObject *}{object}}
Insert object at front of list.
-\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
+\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{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 *}{Insert}{\param{wxNode *}{node}, \param{wxObject *}{object}}
-\membersection{wxList::GetLast}
+Inserts the object before the given {\it node}.
-\func{wxNode *}{GetLast}{\void}
+\membersection{wxList::Item}\label{wxlistitem}
-Returns the last node in the list (NULL if the list is empty).
+\constfunc{wxNode *}{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}}
+{\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.
-\membersection{wxList::Nth}
+\membersection{wxList::Nth}\label{wxlistnth}
\func{wxNode *}{Nth}{\param{int}{ n}}
+{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} 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).
-\membersection{wxList::Number}
+\membersection{wxList::Number}\label{wxlistnumber}
\func{int}{Number}{\void}
+{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
+
Returns the number of elements in the list.
-\membersection{wxList::Sort}
+\membersection{wxList::Sort}\label{wxlistsort}
\func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
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:
}
\end{verbatim}
-
projects / wxWidgets.git / blobdiff