X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d8996187144eba2d9a2d0e91e7b78089721967af..066f3611df971be93b2ec46b82c2f05f3ff9a422:/docs/latex/wx/list.tex diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index f3fd9c8e1b..cb54ec86cf 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -1,31 +1,43 @@ -\section{\class{wxList}}\label{wxlist} - -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. -See \helpref{wxHashTable}{wxhashtable}\rtfsp for a faster method of storage -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 -classes family may contain elements of any type and has much more stricter 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 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 -with {\it WX\_DECLARE\_LIST} and {\it WX\_IMPLEMENT\_LIST} macros like this -(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY -macros): +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% 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. \wxheading{Example} -{\small% \begin{verbatim} // this part might be in a header or source (.cpp) file class MyListElement @@ -33,252 +45,210 @@ macros): ... // whatever }; - // declare our list class: this macro declares and partly implements MyList - // class (which derives from wxListBase) + // this macro declares and partly implements MyList class WX_DECLARE_LIST(MyListElement, MyList); ... - // the only requirment for the rest is to be AFTER the full declaration of + // 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 #include 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 in STL syntax + MyList::iterator iter; + for (iter = list.begin(); iter != list.end(); ++iter) + { + MyListElement *current = *iter; + + ...process the current element... + } - // let's iterate over the list - for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() ) + // the same with the legacy API from the old wxList class + MyList::compatibility_iterator node = list.GetFirst(); + while (node) { MyListElement *current = node->GetData(); ...process the current element... + + node = node->GetNext(); } + \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 -future versions completely. - -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} +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. \wxheading{Include files} -\wxheading{Example} - -It is very common to iterate on a list as follows: - -\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} +\wxheading{Library} -See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and -members for getting to the next or previous node. +\helpref{wxBase}{librarieslist} \wxheading{See also} -\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}, -\helpref{wxArray}{wxarray} +\helpref{wxArray}{wxarray}, +\helpref{wxVector}{wxvector} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxList::wxList} +\membersection{wxList::wxList}\label{wxlistctor} -\func{}{wxList}{\void} +\func{}{wxList}{\void} -\func{}{wxList}{\param{unsigned int}{ key\_type}} +\func{}{wxList}{\param{size\_t}{ count}, \param{T *}{elements[]}} -\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}} +Constructors. -\func{}{wxList}{\param{wxObject *}{object}, ...} +\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} -Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, -and indicates what sort of keying is required (if any). +\func{}{\destruct{wxList}}{\void} -{\it objects} is an array of {\it n} objects with which to initialize the list. +Destroys the list, but does not delete the objects stored in the list +unless you called DeleteContents({\tt true} ). -The variable-length argument list constructor must be supplied with a -terminating NULL. +\membersection{wxList::Append}\label{wxlistappend} -\membersection{wxList::\destruct{wxList}} +\func{wxList::compatibility\_iterator }{Append}{\param{T *}{object}} -\func{}{\destruct{wxList}}{\void} +Appends the pointer to \rtfsp{\it object} to the list. -Destroys the list. Also destroys any remaining nodes, but does not destroy -client data held in the nodes. - -\membersection{wxList::Append} - -\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. - -\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 objects stored in the list +unless you called DeleteContents({\tt true} ). -\membersection{wxList::DeleteContents}\label{wxlistdeletecontents} +\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 objects stored in the list whenever they are removed. +The default is {\tt false}. + +\membersection{wxList::DeleteNode}\label{wxlistdeletenode} -\membersection{wxList::DeleteNode} +\func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}} -\func{bool}{DeleteNode}{\param{wxNode *}{node}} +Deletes the given element refered to by {\tt iter} from the list, +returning {\tt true} if successful. -Deletes the given node from the list, returning TRUE if successful. +\membersection{wxList::DeleteObject}\label{wxlistdeleteobject} -\membersection{wxList::DeleteObject} +\func{bool}{DeleteObject}{\param{T *}{object}} -\func{bool}{DeleteObject}{\param{wxObject *}{object}} +Finds the given {\it object} and removes it from the list, returning +{\tt true} if successful. The application must delete the actual object +separately. -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::Erase}\label{wxlisterase} -\membersection{wxList::Find} +\func{void}{Erase}{\param{const compatibility\_iterator &}{iter}} -\func{wxNode *}{Find}{\param{long}{ key}} +Removes element refered to be {\tt iter}. -\func{wxNode *}{Find}{\param{const wxString\& }{key}} +\membersection{wxList::Find}\label{wxlistfind} -Returns the node whose stored key matches {\it key}. Use on a keyed list only. +\constfunc{wxList::compatibility\_iterator}{Find}{\param{T *}{ object}} -\membersection{wxList::GetCount}\label{wxlistgetcount} +Returns the iterator refering to {\it object} or NULL if none found. + +\membersection{wxList::GetCount}\label{wxlistgetcount} \constfunc{size\_t}{GetCount}{\void} Returns the number of elements in the list. -\membersection{wxList::GetFirst} +\membersection{wxList::GetFirst}\label{wxlistgetfirst} -\func{wxNode *}{GetFirst}{\void} +\constfunc{wxList::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} +\membersection{wxList::GetLast}\label{wxlistgetlast} -\func{wxNode *}{GetLast}{\void} +\constfunc{wxList::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} +\membersection{wxList::IndexOf}\label{wxlistindexof} -\func{int}{IndexOf}{\param{wxObject*}{ obj }} +\constfunc{int}{IndexOf}{\param{T*}{ obj }} -Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} -is not found in the list. +Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if +{\it obj} is not found in the list. -\membersection{wxList::Insert} +\membersection{wxList::Insert}\label{wxlistinsert} -\func{wxNode *}{Insert}{\param{wxObject *}{object}} +\func{wxList::compatibility\_iterator}{Insert}{\param{T *}{object}} -Insert object at front of list. +Insert object at the front of list. -\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{object}} +\func{wxList::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 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}} +\func{wxList::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::Item}\label{wxlistitem} +\membersection{wxList::IsEmpty}\label{wxlistisempty} -\constfunc{wxNode *}{Item}{\param{size\_t }{index}} +\constfunc{bool}{IsEmpty}{\void} -Returns the node at given position in the list. +Returns {\tt true} if the list is empty, {\tt false} otherwise. -\membersection{wxList::Member} +% Use different label name to avoid clashing with wxListItem label +\membersection{wxList::Item}\label{wxlistitemfunc} -\func{wxNode *}{Member}{\param{wxObject *}{object}} +\constfunc{wxList::compatibility\_iterator}{Item}{\param{size\_t }{index}} -{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. +Returns the iterator refering to the object at the given +{\tt index} in the list. -Returns the node associated with {\it object} if it is in the list, NULL otherwise. +\membersection{wxList::Member}\label{wxlistmember} -\membersection{wxList::Nth} +\constfunc{wxList::compatibility\_iterator}{Member}{\param{T *}{ object}} + +{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. -\func{wxNode *}{Nth}{\param{int}{ n}} +\membersection{wxList::Nth}\label{wxlistnth} -{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead. +\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} -\func{int}{Number}{\void} +\constfunc{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}} @@ -287,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.