X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/77c5eefb1f06a8956231d2cbe1526e4de526cac5..9cc73180521b0df3d99ad2003e74acbe126d8c81:/docs/latex/wx/list.tex?ds=sidebyside diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index a3ac3e840e..b6e9b6b463 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -1,35 +1,109 @@ \section{\class{wxList}}\label{wxlist} -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. +wxList classes provide linked list functionality for wxWidgets, 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, +but please note that this feature is {\bf deprecated}. +See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage +when random access is required. + +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 *} +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): + +\wxheading{Example} + +\begin{verbatim} + // this part might be in a header or source (.cpp) file + class MyListElement + { + ... // whatever + }; + + // declare our list class: this macro declares and partly implements MyList + // class (which derives from wxListBase) + WX_DECLARE_LIST(MyListElement, MyList); + + ... + + // 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(17); // error: incorrect type + + // let's iterate over the list + for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() ) + { + MyListElement *current = node->GetData(); + + ...process the current element... + } +\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. 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, 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 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{Example} It is very common to iterate on a list as follows: \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.First(); + wxNode *node = SomeList.GetFirst(); while (node) { - wxPoint *point = (wxPoint *)node->Data(); + wxWindow *win = node->GetData(); ... - node = node->Next(); + node = node->GetNext(); } \end{verbatim} @@ -37,7 +111,7 @@ To delete nodes in a list as the list is being traversed, replace \begin{verbatim} ... - node = node->Next(); + node = node->GetNext(); ... \end{verbatim} @@ -45,35 +119,33 @@ with \begin{verbatim} ... - delete point; + delete win; delete node; - node = SomeList.First(); + 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. -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} +\helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}, +\helpref{wxArray}{wxarray} \latexignore{\rtfignore{\wxheading{Members}}} - -\membersection{wxList::wxList} +\membersection{wxList::wxList}\label{wxlistctor} \func{}{wxList}{\void} -\func{}{wxList}{\param{unsigned int}{ key\_type}} +\func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}} + +\func{}{wxList}{\param{T *}{object}, ...} -\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}} +{\bf Note}: keyed lists are deprecated and should not be used in new code. -\func{}{wxList}{\param{wxObject *}{object}, ...} +\func{}{wxList}{\param{unsigned int}{ key\_type}} Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, and indicates what sort of keying is required (if any). @@ -83,111 +155,158 @@ and indicates what sort of keying is required (if any). The variable-length argument list constructor must be supplied with a terminating NULL. -\membersection{wxList::\destruct{wxList}} +\membersection{wxList::\destruct{wxList}}\label{wxlistdtor} \func{}{\destruct{wxList}}{\void} 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{T *}{object}} -\func{wxNode *}{Append}{\param{wxObject *}{object}} +{\bf Note}: keyed lists are deprecated and should not be used in new code. -\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}} +\func{wxNode *}{Append}{\param{long}{ key}, \param{T *}{object}} -\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}} +\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{T *}{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. +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} +\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({\tt true}), in which case it deletes data). -\membersection{wxList::DeleteContents} +\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 the client contents of +a node whenever the node is destroyed. The default is {\tt false}. -\membersection{wxList::DeleteNode} +\membersection{wxList::DeleteNode}\label{wxlistdeletenode} -\func{bool}{DeleteNode}{\param{wxNode *}{node}} +\func{bool}{DeleteNode}{\param{wxNode *}{node}} -Deletes the given node from the list, returning TRUE if successful. +Deletes the given node from the list, returning {\tt true} if successful. -\membersection{wxList::DeleteObject} +\membersection{wxList::DeleteObject}\label{wxlistdeleteobject} -\func{bool}{DeleteObject}{\param{wxObject *}{object}} +\func{bool}{DeleteObject}{\param{T *}{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. +{\tt true} if successful. The application must delete the actual object separately. + +\membersection{wxList::Erase}\label{wxlisterase} -\membersection{wxList::Find} +\func{void}{Erase}{\param{wxNode *}{node}} -\func{wxNode *}{Find}{\param{long}{ key}} +Removes element at given position. -\func{wxNode *}{Find}{\param{const wxString\& }{key}} +\membersection{wxList::Find}\label{wxlistfind} + +\func{wxNode *}{Find}{\param{T *}{ object}} + +Returns the node whose client date is {\it object} or NULL if none found. + +{\bf Note}: keyed lists are deprecated and should not be used in new code. + +\func{wxNode *}{Find}{\param{long}{ key}} + +\func{wxNode *}{Find}{\param{const wxString\& }{key}} Returns the node whose stored key matches {\it key}. Use on a keyed list only. -\membersection{wxList::First} +\membersection{wxList::GetCount}\label{wxlistgetcount} + +\constfunc{size\_t}{GetCount}{\void} -\func{wxNode *}{First}{\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). -\func{int}{IndexOf}{\param{wxObject*}{ obj }} +\membersection{wxList::IndexOf}\label{wxlistindexof} -Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} +\func{int}{IndexOf}{\param{T*}{ obj }} + +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{wxNode *}{Insert}{\param{T *}{object}} Insert object at front of list. -\func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}} +\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{T *}{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{T *}{object}} -\membersection{wxList::Last} +Inserts the object before the given {\it node}. -\func{wxNode *}{Last}{\void} +\membersection{wxList::IsEmpty}\label{wxlistisempty} -Returns the last node in the list (NULL if the list is empty). +\constfunc{bool}{IsEmpty}{\void} + +Returns {\tt true} if the list is empty, {\tt false} otherwise. + +% Use different label name to avoid clashing with wxListItem label +\membersection{wxList::Item}\label{wxlistitemfunc} + +\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}} +\func{wxNode *}{Member}{\param{T *}{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}} -\func{wxNode *}{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} +{\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}} @@ -198,8 +317,12 @@ Returns the number of elements in the list. 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: @@ -221,4 +344,3 @@ Example: } \end{verbatim} -