Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backported wxList<T> docs

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_8_BRANCH@48217 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Robert Roebling
2007-08-20 13:35:35 +00:00
parent 6396b86b21
commit 3e9e24033f
1 changed files with 260 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

457
docs/latex/wx/list.tex
View File

@@ -2,38 +2,39 @@
%% Name: list.tex %% Name: list.tex
%% Purpose: wxList %% Purpose: wxList
%% Author: wxWidgets Team %% Author: wxWidgets Team
%% Modified by: %% Modified by: Robert Roebling
%% Created: %% Created:
%% RCS-ID: $Id$ %% RCS-ID: $Id$
%% Copyright: (c) wxWidgets Team %% Copyright: (c) wxWidgets Team
%% License: wxWindows license %% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\class{wxList}}\label{wxlist} \section{\class{wxList<T>}}\label{wxlist}
wxList classes provide linked list functionality for wxWidgets, and for an The wxList<T> class provides linked list functionality. It has been written
application if it wishes. Depending on the form of constructor used, a list to be type safe and to provide the full API of the STL std::list container and
can be keyed on integer or string keys to provide a primitive look-up ability, should be used like it. The exception is that wxList<T> actually stores
but please note that this feature is {\bf deprecated}. pointers and therefore its iterators return pointers and not references
See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage to the actual objets in the list (see example below). In other words
when random access is required. {\it value\_type} is defined as {\it T*}.
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
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 *} Unfortunately, the
data but make all of its dangerous (because untyped) functions protected, so new wxList<T> class requires that you declare and define each wxList<T>
that they can only be used from derived classes which, in turn, expose a type class in your program. This is done with {\it WX\_DECLARE\_LIST} and
safe interface. With this approach a new wxList-like class must be defined for {\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able
each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done to provide a proper template class providing both the STL std::list
with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this and the old wxList API in the future.
(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
macros): Please refer to the STL std::list documentation for further
information on how to use the class. Below we documented both
the supported STL and the legacy API that originated from the
old wxList class and which can still be used alternatively for
the the same class.
Note that if you compile wxWidgets in STL mode (wxUSE\_STL defined as 1)
then wxList<T> will actually derive from std::list and just add a legacy
compatibility layer for the old wxList class.
\wxheading{Example} \wxheading{Example}
@@ -44,8 +45,7 @@ macros):
... // whatever ... // whatever
}; };
// declare our list class: this macro declares and partly implements MyList // this macro declares and partly implements MyList class
// class (which derives from wxListBase)
WX_DECLARE_LIST(MyListElement, MyList); WX_DECLARE_LIST(MyListElement, MyList);
... ...
@@ -57,21 +57,32 @@ macros):
#include <wx/listimpl.cpp> #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; MyList list;
MyListElement element; MyListElement element;
list.Append(&element); // ok list.Append(&element); // ok
list.Append(17); // error: incorrect type list.Append(17); // error: incorrect type
// let's iterate over the list // let's iterate over the list in STL syntax
for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() ) MyList::iterator iter;
for (iter = list.begin(); iter != list.end(); ++iter)
{
MyListElement *current = *iter;
...process the current element...
}
// the same with the legacy API from the old wxList class
MyList::compatibility_iterator node = list.GetFirst();
while (node)
{ {
MyListElement *current = node->GetData(); MyListElement *current = node->GetData();
...process the current element... ...process the current element...
node = node->GetNext();
} }
\end{verbatim} \end{verbatim}
For compatibility with previous versions wxList and wxStringList classes are For compatibility with previous versions wxList and wxStringList classes are
@@ -80,244 +91,163 @@ future versions completely. The use of the latter is especially discouraged as
it is not only unsafe but is also much less efficient than it is not only unsafe but is also much less efficient than
\helpref{wxArrayString}{wxarraystring} class. \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{Include files} \wxheading{Include files}
<wx/list.h> <wx/list.h>
\wxheading{Example} \wxheading{Library}
It is very common to iterate on a list as follows: \helpref{wxBase}{librarieslist}
\begin{verbatim}
...
wxWindow *win1 = new wxWindow(...);
wxWindow *win2 = new wxWindow(...);
wxList SomeList;
SomeList.Append(win1);
SomeList.Append(win2);
...
wxNode *node = SomeList.GetFirst();
while (node)
{
wxWindow *win = node->GetData();
...
node = node->GetNext();
}
\end{verbatim}
To delete nodes in a list as the list is being traversed, replace
\begin{verbatim}
...
node = node->GetNext();
...
\end{verbatim}
with
\begin{verbatim}
...
delete win;
delete node;
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.
\wxheading{See also} \wxheading{See also}
\helpref{wxNode}{wxnode},
\helpref{wxArray}{wxarray} \helpref{wxArray}{wxarray}
\latexignore{\rtfignore{\wxheading{Members}}} \latexignore{\rtfignore{\wxheading{Members}}}
\membersection{wxList::wxList}\label{wxlistctor} \membersection{wxList<T>::wxList<T>}\label{wxlistctor}
\func{}{wxList}{\void} \func{}{wxList<T>}{\void}
\func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}} \func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}}
\func{}{wxList}{\param{T *}{object}, ...} Constructors.
{\bf Note}: keyed lists are deprecated and should not be used in new code. \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}
\func{}{wxList}{\param{unsigned int}{ key\_type}} \func{}{\destruct{wxList<T>}}{\void}
Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, Destroys the list, but does not delete the objects stored in the list
and indicates what sort of keying is required (if any). unless you called DeleteContents({\tt true} ).
{\it objects} is an array of {\it n} objects with which to initialize the list. \membersection{wxList<T>::Append}\label{wxlistappend}
The variable-length argument list constructor must be supplied with a \func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}}
terminating NULL.
\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} Appends the pointer to \rtfsp{\it object} to the list.
\func{}{\destruct{wxList}}{\void} \membersection{wxList<T>::Clear}\label{wxlistclear}
Destroys the list. Also destroys any remaining nodes, but does not destroy
client data held in the nodes.
\membersection{wxList::Append}\label{wxlistappend}
\func{wxNode<T> *}{Append}{\param{T *}{object}}
{\bf Note}: keyed lists are deprecated and should not be used in new code.
\func{wxNode<T> *}{Append}{\param{long}{ key}, \param{T *}{object}}
\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.
The key string is copied and stored by the list implementation.
\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 objects stored in the list
unless you called DeleteContents({\tt true}), in which case it deletes data). unless you called DeleteContents({\tt true} ).
\membersection{wxList::DeleteContents}\label{wxlistdeletecontents} \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}
\func{void}{DeleteContents}{\param{bool}{ destroy}} \func{void}{DeleteContents}{\param{bool}{ destroy}}
If {\it destroy} is {\tt true}, instructs the list to call {\it delete} on the client contents of If {\it destroy} is {\tt true}, instructs the list to call {\it delete}
a node whenever the node is destroyed. The default is {\tt false}. on objects stored in the list whenever they are removed.
The default is {\tt false}.
\membersection{wxList::DeleteNode}\label{wxlistdeletenode} \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}
\func{bool}{DeleteNode}{\param{wxNode<T> *}{node}} \func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}}
Deletes the given node from the list, returning {\tt true} if successful. Deletes the given element refered to by {\tt iter} from the list,
returning {\tt true} if successful.
\membersection{wxList::DeleteObject}\label{wxlistdeleteobject} \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}
\func{bool}{DeleteObject}{\param{T *}{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 {\it object} and removes it from the list, returning
{\tt 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} \membersection{wxList<T>::Erase}\label{wxlisterase}
\func{void}{Erase}{\param{wxNode<T> *}{node}} \func{void}{Erase}{\param{const compatibility\_iterator &}{iter}}
Removes element at given position. Removes element refered to be {\tt iter}.
\membersection{wxList::Find}\label{wxlistfind} \membersection{wxList<T>::Find}\label{wxlistfind}
\func{wxNode<T> *}{Find}{\param{T *}{ object}} \constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}}
Returns the node whose client data is {\it object} or NULL if none found. Returns the iterator refering to {\it object} or NULL if none found.
{\bf Note}: keyed lists are deprecated and should not be used in new code. \membersection{wxList<T>::GetCount}\label{wxlistgetcount}
\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.
\membersection{wxList::GetCount}\label{wxlistgetcount}
\constfunc{size\_t}{GetCount}{\void} \constfunc{size\_t}{GetCount}{\void}
Returns the number of elements in the list. Returns the number of elements in the list.
\membersection{wxList::GetFirst}\label{wxlistgetfirst} \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}
\func{wxNode<T> *}{GetFirst}{\void} \constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void}
Returns the first node in the list (NULL if the list is empty). Returns the first iterator in the list (NULL if the list is empty).
\membersection{wxList::GetLast}\label{wxlistgetlast} \membersection{wxList<T>::GetLast}\label{wxlistgetlast}
\func{wxNode<T> *}{GetLast}{\void} \constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void}
Returns the last node in the list (NULL if the list is empty). Returns the last iterator in the list (NULL if the list is empty).
\membersection{wxList::IndexOf}\label{wxlistindexof} \membersection{wxList<T>::IndexOf}\label{wxlistindexof}
\func{int}{IndexOf}{\param{T*}{ obj }} \constfunc{int}{IndexOf}{\param{T*}{ obj }}
Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if {\it obj} Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
is not found in the list. {\it obj} is not found in the list.
\membersection{wxList::Insert}\label{wxlistinsert} \membersection{wxList<T>::Insert}\label{wxlistinsert}
\func{wxNode<T> *}{Insert}{\param{T *}{object}} \func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}}
Insert object at front of list. Insert object at the front of list.
\func{wxNode<T> *}{Insert}{\param{size\_t }{position}, \param{T *}{object}} \func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
Insert object before {\it position}, i.e. the index of the new item in the 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 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 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
same as calling \helpref{Append}{wxlistappend}. same as calling \helpref{Append}{wxlistappend}.
\func{wxNode<T> *}{Insert}{\param{wxNode<T> *}{node}, \param{T *}{object}} \func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}}
Inserts the object before the given {\it node}. Inserts the object before the object refered to be {\it iter}.
\membersection{wxList::IsEmpty}\label{wxlistisempty} \membersection{wxList<T>::IsEmpty}\label{wxlistisempty}
\constfunc{bool}{IsEmpty}{\void} \constfunc{bool}{IsEmpty}{\void}
Returns {\tt true} if the list is empty, {\tt false} otherwise. Returns {\tt true} if the list is empty, {\tt false} otherwise.
% Use different label name to avoid clashing with wxListItem label % Use different label name to avoid clashing with wxListItem label
\membersection{wxList::Item}\label{wxlistitemfunc} \membersection{wxList<T>::Item}\label{wxlistitemfunc}
\constfunc{wxNode<T> *}{Item}{\param{size\_t }{index}} \constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}}
Returns the node at given position in the list. Returns the iterator refering to the object at the given
{\tt index} in the list.
\membersection{wxList::Member}\label{wxlistmember} \membersection{wxList<T>::Member}\label{wxlistmember}
\func{wxNode<T> *}{Member}{\param{T *}{object}} \constfunc{wxList<T>::compatibility\_iterator}{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.
Returns the node associated with {\it object} if it is in the list, NULL otherwise. \membersection{wxList<T>::Nth}\label{wxlistnth}
\membersection{wxList::Nth}\label{wxlistnth} \constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}}
\func{wxNode<T> *}{Nth}{\param{int}{ n}}
{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} 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 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). or the nth node could not be found).
\membersection{wxList::Number}\label{wxlistnumber} \membersection{wxList<T>::Number}\label{wxlistnumber}
\func{int}{Number}{\void} \constfunc{int}{Number}{\void}
{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead. {\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}\label{wxlistsort} \membersection{wxList<T>::Sort}\label{wxlistsort}
\func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
@@ -326,31 +256,164 @@ Returns the number of elements in the list.
typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2); typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
\end{verbatim} \end{verbatim}
Allows the sorting of arbitrary lists by giving Allows the sorting of arbitrary lists by giving a function to compare
a function to compare two list elements. We use the system {\bf qsort} function two list elements. We use the system {\bf qsort} function for the actual
for the actual sorting process. 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:
\begin{verbatim} \membersection{wxList<T>::assign}\label{wxlistassign}
int listcompare(const void *arg1, const void *arg2)
{
return(compare(**(wxString **)arg1, // use the wxString 'compare'
**(wxString **)arg2)); // function
}
void main() \func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
{
wxList list;
list.Append(new wxString("DEF"));
list.Append(new wxString("GHI")); \func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
list.Append(new wxString("ABC"));
list.Sort(listcompare);
} \membersection{wxList<T>::back}\label{wxlistback}
\end{verbatim}
\func{reference}{back}{\void}
\constfunc{const\_reference}{back}{\void}
Returns the last item of the list.
\membersection{wxList<T>::begin}\label{wxlistbegin}
\func{iterator}{begin}{\void}
\constfunc{const\_iterator}{begin}{\void}
Returns a (const) iterator pointing to the beginning of the list.
\membersection{wxList<T>::clear}\label{wxlistclear}
\func{void}{clear}{\void}
Removes all items from the list.
\membersection{wxList<T>::empty}\label{wxlistempty}
\constfunc{bool}{empty}{\void}
Returns {\it true} if the list is empty.
\membersection{wxList<T>::end}\label{wxlistend}
\func{iterator}{end}{\void}
\constfunc{const\_iterator}{end}{\void}
Returns a (const) iterator pointing at the end of the list.
\membersection{wxList<T>::erase}\label{wxlisterase2}
\func{iterator}{erase}{\param{const iterator\& }{it}}
Erases the item pointed to by {\it it}.
\func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}}
Erases the items from {\it first} to {\it last}.
\membersection{wxList<T>::front}\label{wxlistfront}
\func{reference}{front}{\void}
\constfunc{const\_reference}{front}{\void}
Returns the first item in the list.
\membersection{wxList<T>::insert}\label{wxlistinsert}
\func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}}
\func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
\func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
Inserts an item (or several) at the given position.
\membersection{wxList<T>::max\_size}\label{wxlistmax\_size}
\constfunc{size\_type}{max\_size}{\void}
Returns the largest possible size of the list.
\membersection{wxList<T>::pop\_back}\label{wxlistpop\_back}
\func{void}{pop\_back}{\void}
Removes the list item.
\membersection{wxList<T>::pop\_front}\label{wxlistpop\_front}
\func{void}{pop\_front}{\void}
Removes the first item.
\membersection{wxList<T>::push\_back}\label{wxlistpush\_back}
\func{void}{push\_back}{\param{const\_reference }{v = value\_type()}}
Adds an item to end of the list.
\membersection{wxList<T>::push\_front}\label{wxlistpush\_front}
\func{void}{push\_front}{\param{const\_reference }{v = value\_type()}}
Adds an item to the front of the list.
\membersection{wxList<T>::rbegin}\label{wxlistrbegin}
\func{reverse\_iterator}{rbegin}{\void}
\constfunc{const\_reverse\_iterator}{rbegin}{\void}
Returns a (const) reverse iterator pointer to the beginning of the
reversed list.
\membersection{wxList<T>::remove}\label{wxlistremove}
\func{void}{remove}{\param{const\_reference }{v}}
Removes an item from the list.
\membersection{wxList<T>::rend}\label{wxlistrend}
\func{reverse\_iterator}{rend}{\void}
\constfunc{const\_reverse\_iterator}{rend}{\void}
Returns a (const) reverse iterator pointer to the end of the
reversed list.
\membersection{wxList<T>::resize}\label{wxlistresize}
\func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}}
Resizes the list. If the the list is enlarges items with
the value {\it v} are appended to the list.
\membersection{wxList<T>::reverse}\label{wxlistreverse}
\func{void}{reverse}{\void}
Reverses the list.
\membersection{wxList<T>::size}\label{wxlistsize}
\constfunc{size\_type}{size}{\void}
Returns the size of the list.
\membersection{wxList<T>::splice}\label{wxlistsplice}
\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}}
\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}}
\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}}
Moves part of the list into another list, starting from {\it first} and
ending at {\it last} if specified.