X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bb250157d95834afa04fa7fc188833248450d65c..19cf1ef3a7077dd99a90f141847b8a9b67b318c9:/docs/latex/wx/list.tex diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index 83c051a0d0..50482dd315 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -1,31 +1,38 @@ -\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\_DEFINE\_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). 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 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,253 +40,209 @@ 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.Append(element); // ok + 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() ) + // 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... + } + + // 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} \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). +\membersection{wxList::wxList}\label{wxlistctor} -{\it objects} is an array of {\it n} objects with which to initialize the list. +\func{}{wxList}{\void} -The variable-length argument list constructor must be supplied with a -terminating NULL. +\func{}{wxList}{\param{size\_t}{ count}, \param{T *}{elements[]}} -\membersection{wxList::\destruct{wxList}} +Constructors. -\func{}{\destruct{wxList}}{\void} +\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} -Destroys the list. Also destroys any remaining nodes, but does not destroy -client data held in the nodes. +\func{}{\destruct{wxList}}{\void} -\membersection{wxList::Append}\label{wxlistappend} +Destroys 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::Append}\label{wxlistappend} -\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}} +\func{wxList::compatibility\_iterator }{Append}{\param{T *}{object}} -\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}} +Appends the pointer to \rtfsp{\it object} to the list. -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}\label{wxlistclear} +\membersection{wxList::Clear}\label{wxlistclear} \func{void}{Clear}{\void} -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). +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}\label{wxlistdeletenode} +\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}\label{wxlistdeleteobject} +\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}\label{wxlistfind} +\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}\label{wxlistgetfirst} +\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}\label{wxlistgetlast} +\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}\label{wxlistindexof} +\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}\label{wxlistinsert} +\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}\label{wxlistmember} +% 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. + +\membersection{wxList::Member}\label{wxlistmember} -Returns the node associated with {\it object} if it is in the list, NULL otherwise. +\constfunc{wxList::compatibility\_iterator}{Member}{\param{T *}{ object}} -\membersection{wxList::Nth}\label{wxlistnth} +{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. + +\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}{wxlistitem} 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 or the nth node could not be found). -\membersection{wxList::Number}\label{wxlistnumber} +\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}\label{wxlistsort} +\membersection{wxList::Sort}\label{wxlistsort} \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} @@ -288,28 +251,7 @@ 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. - -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} +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.