docs/latex/wx/list.tex

   1 \section{\class{wxList}}\label{wxlist}
   2
   3 wxList classes provide linked list functionality for wxWindows, and for an
   4 application if it wishes.  Depending on the form of constructor used, a list
   5 can be keyed on integer or string keys to provide a primitive look-up ability.
   6 See \helpref{wxHashTable}{wxhashtable}\rtfsp for a faster method of storage
   7 when random access is required.
   8
   9 While wxList class in the previous versions of wxWindows only could contain
  10 elements of type wxObject and had essentially untyped interface (thus allowing
  11 you to put apples in the list and read back oranges from it), the new wxList
  12 classes family may contain elements of any type and has much more stricter type
  13 checking. Unfortunately, it also requires an additional line to be inserted in
  14 your program for each list class you use (which is the only solution short of
  15 using templates which is not done in wxWindows because of portability issues).
  16
  17 The general idea is to have the base class wxListBase working with {\it void *}
  18 data but make all of its dangerous (because untyped) functions protected, so
  19 that they can only be used from derived classes which, in turn, expose a type
  20 safe interface. With this approach a new wxList-like class must be defined for
  21 each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done
  22 with {\it WX\_DECLARE\_LIST} and {\it WX\_IMPLEMENT\_LIST} macros like this
  23 (notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
  24 macros):
  25
  26 \wxheading{Example}
  27
  28 {\small%
  29 \begin{verbatim}
  30     // this part might be in a header or source (.cpp) file
  31     class MyListElement
  32     {
  33         ... // whatever
  34     };
  35
  36     // declare our list class: this macro declares and partly implements MyList
  37     // class (which derives from wxListBase)
  38     WX_DECLARE_LIST(MyListElement, MyList)
  39
  40     ...
  41
  42     // the only requirment for the rest is to be AFTER the full declaration of
  43     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
  44     // usually it will be found in the source file and not in the header
  45
  46     #include <wx/listimpl.cpp>
  47     WX_DEFINE_LIST(MyList)
  48
  49     // now MyList class may be used as a usual wxList, but all of its methods
  50     // will take/return the objects of the right (i.e. MyListElement) type. You
  51     // also have MyList::Node type which is the type-safe version of wxNode.
  52     MyList list;
  53     MyListElement element;
  54     list.Add(element);      // ok
  55     list.Add(17);           // error: incorrect type
  56
  57     // let's iterate over the list
  58     for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
  59     {
  60         MyListElement *current = node->GetData();
  61
  62         ...process the current element...
  63     }
  64 \end{verbatim}
  65 }
  66
  67 For compatibility with previous versions wxList and wxStringList classes are
  68 still defined, but their usage is deprecated and they will disappear in the
  69 future versions completely.
  70
  71 \wxheading{Derived from}
  72
  73 \helpref{wxObject}{wxobject}
  74
  75 \wxheading{Example}
  76
  77 It is very common to iterate on a list as follows:
  78
  79 \begin{verbatim}
  80   ...
  81   wxWindow *win1 = new wxWindow(...);
  82   wxWindow *win2 = new wxWindow(...);
  83
  84   wxList SomeList;
  85   SomeList.Append(win1);
  86   SomeList.Append(win2);
  87
  88   ...
  89
  90   wxNode *node = SomeList.GetFirst();
  91   while (node)
  92   {
  93     wxWindow *win = (wxWindow *)node->Data();
  94     ...
  95     node = node->Next();
  96   }
  97 \end{verbatim}
  98
  99 To delete nodes in a list as the list is being traversed, replace
 100
 101 \begin{verbatim}
 102     ...
 103     node = node->Next();
 104     ...
 105 \end{verbatim}
 106
 107 with
 108
 109 \begin{verbatim}
 110     ...
 111     delete win;
 112     delete node;
 113     node = SomeList.GetFirst();
 114     ...
 115 \end{verbatim}
 116
 117 See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
 118 members for getting to the next or previous node.
 119
 120 Note that a cast is required when retrieving the data from a node.  Although a
 121 node is defined to store objects of type {\bf wxObject} and derived types, other
 122 types (such as char*) may be used with appropriate casting.
 123
 124 \wxheading{See also}
 125
 126 \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist},
 127 \helpref{wxArray}{wxarray}
 128
 129 \latexignore{\rtfignore{\wxheading{Members}}}
 130
 131 \membersection{wxList::wxList}
 132
 133 \func{}{wxList}{\void}
 134
 135 \func{}{wxList}{\param{unsigned int}{ key\_type}}
 136
 137 \func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}
 138
 139 \func{}{wxList}{\param{wxObject *}{object}, ...}
 140
 141 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
 142 and indicates what sort of keying is required (if any).
 143
 144 {\it objects} is an array of {\it n} objects with which to initialize the list.
 145
 146 The variable-length argument list constructor must be supplied with a
 147 terminating NULL.
 148
 149 \membersection{wxList::\destruct{wxList}}
 150
 151 \func{}{\destruct{wxList}}{\void}
 152
 153 Destroys the list.  Also destroys any remaining nodes, but does not destroy
 154 client data held in the nodes.
 155
 156 \membersection{wxList::Append}
 157
 158 \func{wxNode *}{Append}{\param{wxObject *}{object}}
 159
 160 \func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}}
 161
 162 \func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}}
 163
 164 Appends a new {\bf wxNode} to the end of the list and puts a pointer to the
 165 \rtfsp{\it object} in the node.  The last two forms store a key with the object for
 166 later retrieval using the key. The new node is returned in each case.
 167
 168 The key string is copied and stored by the list implementation.
 169
 170 \membersection{wxList::Clear}
 171
 172 \func{void}{Clear}{\void}
 173
 174 Clears the list (but does not delete the client data stored with each node).
 175
 176 \membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 177
 178 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 179
 180 If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
 181 a node whenever the node is destroyed. The default is FALSE.
 182
 183 \membersection{wxList::DeleteNode}
 184
 185 \func{bool}{DeleteNode}{\param{wxNode *}{node}}
 186
 187 Deletes the given node from the list, returning TRUE if successful.
 188
 189 \membersection{wxList::DeleteObject}
 190
 191 \func{bool}{DeleteObject}{\param{wxObject *}{object}}
 192
 193 Finds the given client {\it object} and deletes the appropriate node from the list, returning
 194 TRUE if successful. The application must delete the actual object separately.
 195
 196 \membersection{wxList::Find}
 197
 198 \func{wxNode *}{Find}{\param{long}{ key}}
 199
 200 \func{wxNode *}{Find}{\param{const wxString\& }{key}}
 201
 202 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 203
 204 \membersection{wxList::GetFirst}
 205
 206 \func{wxNode *}{GetFirst}{\void}
 207
 208 Returns the first node in the list (NULL if the list is empty).
 209
 210 \membersection{wxList::IndexOf}
 211
 212 \func{int}{IndexOf}{\param{wxObject*}{ obj }}
 213
 214 Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj}
 215 is not found in the list.
 216
 217 \membersection{wxList::Insert}
 218
 219 \func{wxNode *}{Insert}{\param{wxObject *}{object}}
 220
 221 Insert object at front of list.
 222
 223 \func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
 224
 225 Insert object before {\it position}.
 226
 227
 228 \membersection{wxList::GetLast}
 229
 230 \func{wxNode *}{GetLast}{\void}
 231
 232 Returns the last node in the list (NULL if the list is empty).
 233
 234 \membersection{wxList::Member}
 235
 236 \func{wxNode *}{Member}{\param{wxObject *}{object}}
 237
 238 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 239
 240 \membersection{wxList::Nth}
 241
 242 \func{wxNode *}{Nth}{\param{int}{ n}}
 243
 244 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 245 or the nth node could not be found).
 246
 247 \membersection{wxList::Number}
 248
 249 \func{int}{Number}{\void}
 250
 251 Returns the number of elements in the list.
 252
 253 \membersection{wxList::Sort}
 254
 255 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 256
 257 \begin{verbatim}
 258   // Type of compare function for list sort operation (as in 'qsort')
 259   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 260 \end{verbatim}
 261
 262 Allows the sorting of arbitrary lists by giving
 263 a function to compare two list elements. We use the system {\bf qsort} function
 264 for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **),
 265 so be careful to dereference appropriately.
 266
 267 Example:
 268
 269 \begin{verbatim}
 270   int listcompare(const void *arg1, const void *arg2)
 271   {
 272     return(compare(**(wxString **)arg1,    // use the wxString 'compare'
 273                    **(wxString **)arg2));  // function
 274   }
 275
 276   void main()
 277   {
 278     wxList list;
 279
 280     list.Append(new wxString("DEF"));
 281     list.Append(new wxString("GHI"));
 282     list.Append(new wxString("ABC"));
 283     list.Sort(listcompare);
 284   }
 285 \end{verbatim}
 286
 287