X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..d6d626862232acff773485769ff6cae68f73c2f5:/docs/latex/wx/list.tex diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index 3af91125d3..af43ec1d2c 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -1,33 +1,100 @@ \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 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): + +\wxheading{Example} + +{\small% +\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 requirment 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 + + // 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. \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 = (wxWindow *)node->Data(); ... node = node->Next(); } @@ -45,9 +112,9 @@ with \begin{verbatim} ... - delete point; + delete win; delete node; - node = SomeList.First(); + node = SomeList.GetFirst(); ... \end{verbatim} @@ -60,11 +127,11 @@ 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} \func{}{wxList}{\void} @@ -110,7 +177,7 @@ The key string is copied and stored by the list implementation. Clears the list (but does not delete the client data stored with each node). -\membersection{wxList::DeleteContents} +\membersection{wxList::DeleteContents}\label{wxlistdeletecontents} \func{void}{DeleteContents}{\param{bool}{ destroy}} @@ -138,12 +205,19 @@ TRUE if successful. The application must delete the actual object separately. Returns the node whose stored key matches {\it key}. Use on a keyed list only. -\membersection{wxList::First} +\membersection{wxList::GetFirst} -\func{wxNode *}{First}{\void} +\func{wxNode *}{GetFirst}{\void} Returns the first node in the list (NULL if the list is empty). +\membersection{wxList::IndexOf} + +\func{int}{IndexOf}{\param{wxObject*}{ obj }} + +Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} +is not found in the list. + \membersection{wxList::Insert} \func{wxNode *}{Insert}{\param{wxObject *}{object}} @@ -155,9 +229,9 @@ Insert object at front of list. Insert object before {\it position}. -\membersection{wxList::Last} +\membersection{wxList::GetLast} -\func{wxNode *}{Last}{\void} +\func{wxNode *}{GetLast}{\void} Returns the last node in the list (NULL if the list is empty).