+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/listimpl.cpp>
+ 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<T> with
+wxListName::Node and T itself with the list element type (i.e. the first
+parameter of WX\_DECLARE\_LIST).
projects / wxWidgets.git / blobdiff