X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..066f3611df971be93b2ec46b82c2f05f3ff9a422:/docs/latex/wx/list.tex diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index 3af91125d3..cb54ec86cf 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -1,186 +1,254 @@ -\section{\class{wxList}}\label{wxlist} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: list.tex +%% Purpose: wxList +%% Author: wxWidgets Team +%% Modified by: +%% Created: +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxList}}\label{wxlist} + +The wxList class provides linked list functionality. It has been written +to be type safe and to provide the full API of the STL std::list container and +should be used like it. The exception is that wxList actually stores +pointers and therefore its iterators return pointers and not references +to the actual objets in the list (see example below) and {\it value\_type} +is defined as {\it T*}. + + +Unfortunately, the +new wxList class requires that you declare and define each wxList +class in your program. This is done with {\it WX\_DECLARE\_LIST} and +{\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able +to provide a proper template class providing both the STL std::list +and the old wxList API in the future. + +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 will actually derive from std::list and just add a legacy +compatibility layer for the old wxList class. -This class provides 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. See \helpref{wxHashTable}{wxhashtable}\rtfsp -for a faster method of storage when random access is required. +\wxheading{Example} -\wxheading{Derived from} +\begin{verbatim} + // this part might be in a header or source (.cpp) file + class MyListElement + { + ... // whatever + }; -\helpref{wxObject}{wxobject} + // this macro declares and partly implements MyList class + WX_DECLARE_LIST(MyListElement, MyList); -\wxheading{Example} + ... -It is very common to iterate on a list as follows: + // the only requirement 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 -\begin{verbatim} - ... - wxPoint *point1 = new wxPoint(100, 100); - wxPoint *point2 = new wxPoint(200, 200); + #include + WX_DEFINE_LIST(MyList); - wxList SomeList; - SomeList.Append(point1); - SomeList.Append(point2); - ... + MyList list; + MyListElement element; + list.Append(&element); // ok + list.Append(17); // error: incorrect type - wxNode *node = SomeList.First(); - while (node) - { - wxPoint *point = (wxPoint *)node->Data(); - ... - node = node->Next(); - } -\end{verbatim} + // let's iterate over the list in STL syntax + MyList::iterator iter; + for (iter = list.begin(); iter != list.end(); ++iter) + { + MyListElement *current = *iter; -To delete nodes in a list as the list is being traversed, replace + ...process the current element... + } -\begin{verbatim} - ... - node = node->Next(); - ... -\end{verbatim} + // the same with the legacy API from the old wxList class + MyList::compatibility_iterator node = list.GetFirst(); + while (node) + { + MyListElement *current = node->GetData(); -with + ...process the current element... + + node = node->GetNext(); + } -\begin{verbatim} - ... - delete point; - delete node; - node = SomeList.First(); - ... \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. +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 +it is not only unsafe but is also much less efficient than +\helpref{wxArrayString}{wxarraystring} class. -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{Include files} + + + +\wxheading{Library} + +\helpref{wxBase}{librarieslist} \wxheading{See also} -\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist} +\helpref{wxArray}{wxarray}, +\helpref{wxVector}{wxvector} \latexignore{\rtfignore{\wxheading{Members}}} +\membersection{wxList::wxList}\label{wxlistctor} -\membersection{wxList::wxList} +\func{}{wxList}{\void} -\func{}{wxList}{\void} +\func{}{wxList}{\param{size\_t}{ count}, \param{T *}{elements[]}} -\func{}{wxList}{\param{unsigned int}{ key\_type}} +Constructors. -\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}} +\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} -\func{}{wxList}{\param{wxObject *}{object}, ...} +\func{}{\destruct{wxList}}{\void} -Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, -and indicates what sort of keying is required (if any). +Destroys the list, but does not delete the objects stored in the list +unless you called DeleteContents({\tt true} ). -{\it objects} is an array of {\it n} objects with which to initialize the list. +\membersection{wxList::Append}\label{wxlistappend} -The variable-length argument list constructor must be supplied with a -terminating NULL. +\func{wxList::compatibility\_iterator }{Append}{\param{T *}{object}} -\membersection{wxList::\destruct{wxList}} +Appends the pointer to \rtfsp{\it object} to the list. -\func{}{\destruct{wxList}}{\void} +\membersection{wxList::Clear}\label{wxlistclear} -Destroys the list. Also destroys any remaining nodes, but does not destroy -client data held in the nodes. +\func{void}{Clear}{\void} -\membersection{wxList::Append} +Clears the list, but does not delete the objects stored in the list +unless you called DeleteContents({\tt true} ). -\func{wxNode *}{Append}{\param{wxObject *}{object}} +\membersection{wxList::DeleteContents}\label{wxlistdeletecontents} -\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}} +\func{void}{DeleteContents}{\param{bool}{ destroy}} -\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}} +If {\it destroy} is {\tt true}, instructs the list to call {\it delete} +on objects stored in the list whenever they are removed. +The default is {\tt false}. -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. +\membersection{wxList::DeleteNode}\label{wxlistdeletenode} -The key string is copied and stored by the list implementation. +\func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}} -\membersection{wxList::Clear} +Deletes the given element refered to by {\tt iter} from the list, +returning {\tt true} if successful. -\func{void}{Clear}{\void} +\membersection{wxList::DeleteObject}\label{wxlistdeleteobject} -Clears the list (but does not delete the client data stored with each node). +\func{bool}{DeleteObject}{\param{T *}{object}} -\membersection{wxList::DeleteContents} +Finds the given {\it object} and removes it from the list, returning +{\tt true} if successful. The application must delete the actual object +separately. -\func{void}{DeleteContents}{\param{bool}{ destroy}} +\membersection{wxList::Erase}\label{wxlisterase} + +\func{void}{Erase}{\param{const compatibility\_iterator &}{iter}} + +Removes element refered to be {\tt iter}. + +\membersection{wxList::Find}\label{wxlistfind} + +\constfunc{wxList::compatibility\_iterator}{Find}{\param{T *}{ object}} + +Returns the iterator refering to {\it object} or NULL if none found. + +\membersection{wxList::GetCount}\label{wxlistgetcount} -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. +\constfunc{size\_t}{GetCount}{\void} -\membersection{wxList::DeleteNode} +Returns the number of elements in the list. + +\membersection{wxList::GetFirst}\label{wxlistgetfirst} -\func{bool}{DeleteNode}{\param{wxNode *}{node}} +\constfunc{wxList::compatibility\_iterator}{GetFirst}{\void} -Deletes the given node from the list, returning TRUE if successful. +Returns the first iterator in the list (NULL if the list is empty). -\membersection{wxList::DeleteObject} +\membersection{wxList::GetLast}\label{wxlistgetlast} -\func{bool}{DeleteObject}{\param{wxObject *}{object}} +\constfunc{wxList::compatibility\_iterator}{GetLast}{\void} -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. +Returns the last iterator in the list (NULL if the list is empty). -\membersection{wxList::Find} +\membersection{wxList::IndexOf}\label{wxlistindexof} -\func{wxNode *}{Find}{\param{long}{ key}} +\constfunc{int}{IndexOf}{\param{T*}{ obj }} -\func{wxNode *}{Find}{\param{const wxString\& }{key}} +Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if +{\it obj} is not found in the list. -Returns the node whose stored key matches {\it key}. Use on a keyed list only. +\membersection{wxList::Insert}\label{wxlistinsert} -\membersection{wxList::First} +\func{wxList::compatibility\_iterator}{Insert}{\param{T *}{object}} -\func{wxNode *}{First}{\void} +Insert object at the front of list. -Returns the first node in the list (NULL if the list is empty). +\func{wxList::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}} -\membersection{wxList::Insert} +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{wxObject *}{object}} +\func{wxList::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}} -Insert object at front of list. +Inserts the object before the object refered to be {\it iter}. -\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}} +\membersection{wxList::IsEmpty}\label{wxlistisempty} -Insert object before {\it position}. +\constfunc{bool}{IsEmpty}{\void} +Returns {\tt true} if the list is empty, {\tt false} otherwise. -\membersection{wxList::Last} +% Use different label name to avoid clashing with wxListItem label +\membersection{wxList::Item}\label{wxlistitemfunc} -\func{wxNode *}{Last}{\void} +\constfunc{wxList::compatibility\_iterator}{Item}{\param{size\_t }{index}} -Returns the last node in the list (NULL if the list is empty). +Returns the iterator refering to the object at the given +{\tt index} in the list. -\membersection{wxList::Member} +\membersection{wxList::Member}\label{wxlistmember} -\func{wxNode *}{Member}{\param{wxObject *}{object}} +\constfunc{wxList::compatibility\_iterator}{Member}{\param{T *}{ object}} -Returns the node associated with {\it object} if it is in the list, NULL otherwise. +{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. -\membersection{wxList::Nth} +\membersection{wxList::Nth}\label{wxlistnth} -\func{wxNode *}{Nth}{\param{int}{ n}} +\constfunc{wxList::compatibility\_iterator}{Nth}{\param{int }{n}} + +{\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). -\membersection{wxList::Number} +\membersection{wxList::Number}\label{wxlistnumber} + +\constfunc{int}{Number}{\void} -\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}} @@ -189,29 +257,164 @@ Returns the number of elements in the list. 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 -for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **), -so be careful to dereference appropriately. +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. -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} +\membersection{wxList::assign}\label{wxlistassign} + +\func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} + + +\func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} + + +\membersection{wxList::back}\label{wxlistback} + +\func{reference}{back}{\void} + +\constfunc{const\_reference}{back}{\void} + +Returns the last item of the list. + +\membersection{wxList::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::clear}\label{wxlistclear} + +\func{void}{clear}{\void} + +Removes all items from the list. + +\membersection{wxList::empty}\label{wxlistempty} + +\constfunc{bool}{empty}{\void} + +Returns {\it true} if the list is empty. + +\membersection{wxList::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::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::front}\label{wxlistfront} + +\func{reference}{front}{\void} + +\constfunc{const\_reference}{front}{\void} + +Returns the first item in the list. + +\membersection{wxList::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::max\_size}\label{wxlistmaxsize} + +\constfunc{size\_type}{max\_size}{\void} + +Returns the largest possible size of the list. + +\membersection{wxList::pop\_back}\label{wxlistpopback} + +\func{void}{pop\_back}{\void} + +Removes the last item from the list. + +\membersection{wxList::pop\_front}\label{wxlistpopfront} + +\func{void}{pop\_front}{\void} + +Removes the first item from the list. + +\membersection{wxList::push\_back}\label{wxlistpushback} + +\func{void}{push\_back}{\param{const\_reference }{v = value\_type()}} + +Adds an item to end of the list. + +\membersection{wxList::push\_front}\label{wxlistpushfront} + +\func{void}{push\_front}{\param{const\_reference }{v = value\_type()}} + +Adds an item to the front of the list. + +\membersection{wxList::rbegin}\label{wxlistrbegin} + +\func{reverse\_iterator}{rbegin}{\void} + +\constfunc{const\_reverse\_iterator}{rbegin}{\void} + +Returns a (const) reverse iterator pointing to the beginning of the +reversed list. + +\membersection{wxList::remove}\label{wxlistremove} + +\func{void}{remove}{\param{const\_reference }{v}} + +Removes an item from the list. + +\membersection{wxList::rend}\label{wxlistrend} + +\func{reverse\_iterator}{rend}{\void} + +\constfunc{const\_reverse\_iterator}{rend}{\void} + +Returns a (const) reverse iterator pointing to the end of the +reversed list. + +\membersection{wxList::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::reverse}\label{wxlistreverse} + +\func{void}{reverse}{\void} + +Reverses the list. + +\membersection{wxList::size}\label{wxlistsize} + +\constfunc{size\_type}{size}{\void} + +Returns the size of the list. + +\membersection{wxList::splice}\label{wxlistsplice} + +\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList\& }{l}} + +\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList\& }{l}, \param{const iterator\& }{first}} + +\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList\& }{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.