docs/latex/wx/list.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        list.tex
   3 %% Purpose:     wxList
   4 %% Author:      wxWidgets Team
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets Team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxList}}\label{wxlist}
  13
  14 wxList classes provide linked list functionality for wxWidgets, and for an
  15 application if it wishes.  Depending on the form of constructor used, a list
  16 can be keyed on integer or string keys to provide a primitive look-up ability,
  17 but please note that this feature is {\bf deprecated}.
  18 See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage
  19 when random access is required.
  20
  21 While wxList class in the previous versions of wxWidgets only could contain
  22 elements of type wxObject and had essentially untyped interface (thus allowing
  23 you to put apples in the list and read back oranges from it), the new wxList
  24 classes family may contain elements of any type and has much more strict type
  25 checking. Unfortunately, it also requires an additional line to be inserted in
  26 your program for each list class you use (which is the only solution short of
  27 using templates which is not done in wxWidgets because of portability issues).
  28
  29 The general idea is to have the base class wxListBase working with {\it void *}
  30 data but make all of its dangerous (because untyped) functions protected, so
  31 that they can only be used from derived classes which, in turn, expose a type
  32 safe interface. With this approach a new wxList-like class must be defined for
  33 each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done
  34 with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this
  35 (notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
  36 macros):
  37
  38 \wxheading{Example}
  39
  40 \begin{verbatim}
  41     // this part might be in a header or source (.cpp) file
  42     class MyListElement
  43     {
  44         ... // whatever
  45     };
  46
  47     // declare our list class: this macro declares and partly implements MyList
  48     // class (which derives from wxListBase)
  49     WX_DECLARE_LIST(MyListElement, MyList);
  50
  51     ...
  52
  53     // the only requirement for the rest is to be AFTER the full declaration of
  54     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
  55     // usually it will be found in the source file and not in the header
  56
  57     #include <wx/listimpl.cpp>
  58     WX_DEFINE_LIST(MyList);
  59
  60     // now MyList class may be used as a usual wxList, but all of its methods
  61     // will take/return the objects of the right (i.e. MyListElement) type. You
  62     // also have MyList::Node type which is the type-safe version of wxNode.
  63     MyList list;
  64     MyListElement element;
  65     list.Append(&element);     // ok
  66     list.Append(17);           // error: incorrect type
  67
  68     // let's iterate over the list
  69     for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
  70     {
  71         MyListElement *current = node->GetData();
  72
  73         ...process the current element...
  74     }
  75 \end{verbatim}
  76
  77 For compatibility with previous versions wxList and wxStringList classes are
  78 still defined, but their usage is deprecated and they will disappear in the
  79 future versions completely. The use of the latter is especially discouraged as
  80 it is not only unsafe but is also much less efficient than
  81 \helpref{wxArrayString}{wxarraystring} class.
  82
  83 In the documentation of the list classes below, the template notations are
  84 used even though these classes are not really templates at all -- but it helps
  85 to think about them as if they were. You should replace wxNode<T> with
  86 wxListName::Node and T itself with the list element type (i.e. the first
  87 parameter of WX\_DECLARE\_LIST).
  88
  89 \wxheading{Derived from}
  90
  91 \helpref{wxObject}{wxobject}
  92
  93 \wxheading{Include files}
  94
  95 <wx/list.h>
  96
  97 \wxheading{Example}
  98
  99 It is very common to iterate on a list as follows:
 100
 101 \begin{verbatim}
 102   ...
 103   wxWindow *win1 = new wxWindow(...);
 104   wxWindow *win2 = new wxWindow(...);
 105
 106   wxList SomeList;
 107   SomeList.Append(win1);
 108   SomeList.Append(win2);
 109
 110   ...
 111
 112   wxNode *node = SomeList.GetFirst();
 113   while (node)
 114   {
 115     wxWindow *win = node->GetData();
 116     ...
 117     node = node->GetNext();
 118   }
 119 \end{verbatim}
 120
 121 To delete nodes in a list as the list is being traversed, replace
 122
 123 \begin{verbatim}
 124     ...
 125     node = node->GetNext();
 126     ...
 127 \end{verbatim}
 128
 129 with
 130
 131 \begin{verbatim}
 132     ...
 133     delete win;
 134     delete node;
 135     node = SomeList.GetFirst();
 136     ...
 137 \end{verbatim}
 138
 139 See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
 140 members for getting to the next or previous node.
 141
 142 \wxheading{See also}
 143
 144 \helpref{wxNode}{wxnode},
 145 \helpref{wxArray}{wxarray}
 146
 147 \latexignore{\rtfignore{\wxheading{Members}}}
 148
 149 \membersection{wxList::wxList}\label{wxlistctor}
 150
 151 \func{}{wxList}{\void}
 152
 153 \func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}}
 154
 155 \func{}{wxList}{\param{T *}{object}, ...}
 156
 157 {\bf Note}: keyed lists are deprecated and should not be used in new code.
 158
 159 \func{}{wxList}{\param{unsigned int}{ key\_type}}
 160
 161 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
 162 and indicates what sort of keying is required (if any).
 163
 164 {\it objects} is an array of {\it n} objects with which to initialize the list.
 165
 166 The variable-length argument list constructor must be supplied with a
 167 terminating NULL.
 168
 169 \membersection{wxList::\destruct{wxList}}\label{wxlistdtor}
 170
 171 \func{}{\destruct{wxList}}{\void}
 172
 173 Destroys the list.  Also destroys any remaining nodes, but does not destroy
 174 client data held in the nodes.
 175
 176 \membersection{wxList::Append}\label{wxlistappend}
 177
 178 \func{wxNode<T> *}{Append}{\param{T *}{object}}
 179
 180 {\bf Note}: keyed lists are deprecated and should not be used in new code.
 181
 182 \func{wxNode<T> *}{Append}{\param{long}{ key}, \param{T *}{object}}
 183
 184 \func{wxNode<T> *}{Append}{\param{const wxString\& }{key}, \param{T *}{object}}
 185
 186 Appends a new \helpref{wxNode}{wxnode} to the end of the list and puts a
 187 pointer to the \rtfsp{\it object} in the node.  The last two forms store a key
 188 with the object for later retrieval using the key. The new node is returned in
 189 each case.
 190
 191 The key string is copied and stored by the list implementation.
 192
 193 \membersection{wxList::Clear}\label{wxlistclear}
 194
 195 \func{void}{Clear}{\void}
 196
 197 Clears the list (but does not delete the client data stored with each node
 198 unless you called DeleteContents({\tt true}), in which case it deletes data).
 199
 200 \membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
 201
 202 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 203
 204 If {\it destroy} is {\tt true}, instructs the list to call {\it delete} on the client contents of
 205 a node whenever the node is destroyed. The default is {\tt false}.
 206
 207 \membersection{wxList::DeleteNode}\label{wxlistdeletenode}
 208
 209 \func{bool}{DeleteNode}{\param{wxNode<T> *}{node}}
 210
 211 Deletes the given node from the list, returning {\tt true} if successful.
 212
 213 \membersection{wxList::DeleteObject}\label{wxlistdeleteobject}
 214
 215 \func{bool}{DeleteObject}{\param{T *}{object}}
 216
 217 Finds the given client {\it object} and deletes the appropriate node from the list, returning
 218 {\tt true} if successful. The application must delete the actual object separately.
 219
 220 \membersection{wxList::Erase}\label{wxlisterase}
 221
 222 \func{void}{Erase}{\param{wxNode<T> *}{node}}
 223
 224 Removes element at given position.
 225
 226 \membersection{wxList::Find}\label{wxlistfind}
 227
 228 \func{wxNode<T> *}{Find}{\param{T *}{ object}}
 229
 230 Returns the node whose client data is {\it object} or NULL if none found.
 231
 232 {\bf Note}: keyed lists are deprecated and should not be used in new code.
 233
 234 \func{wxNode<T> *}{Find}{\param{long}{ key}}
 235
 236 \func{wxNode<T> *}{Find}{\param{const wxString\& }{key}}
 237
 238 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 239
 240 \membersection{wxList::GetCount}\label{wxlistgetcount}
 241
 242 \constfunc{size\_t}{GetCount}{\void}
 243
 244 Returns the number of elements in the list.
 245
 246 \membersection{wxList::GetFirst}\label{wxlistgetfirst}
 247
 248 \func{wxNode<T> *}{GetFirst}{\void}
 249
 250 Returns the first node in the list (NULL if the list is empty).
 251
 252 \membersection{wxList::GetLast}\label{wxlistgetlast}
 253
 254 \func{wxNode<T> *}{GetLast}{\void}
 255
 256 Returns the last node in the list (NULL if the list is empty).
 257
 258 \membersection{wxList::IndexOf}\label{wxlistindexof}
 259
 260 \func{int}{IndexOf}{\param{T*}{ obj }}
 261
 262 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if {\it obj}
 263 is not found in the list.
 264
 265 \membersection{wxList::Insert}\label{wxlistinsert}
 266
 267 \func{wxNode<T> *}{Insert}{\param{T *}{object}}
 268
 269 Insert object at front of list.
 270
 271 \func{wxNode<T> *}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
 272
 273 Insert object before {\it position}, i.e. the index of the new item in the
 274 list will be equal to {\it position}. {\it position} should be less than or
 275 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
 276 same as calling \helpref{Append}{wxlistappend}.
 277
 278 \func{wxNode<T> *}{Insert}{\param{wxNode<T> *}{node}, \param{T *}{object}}
 279
 280 Inserts the object before the given {\it node}.
 281
 282 \membersection{wxList::IsEmpty}\label{wxlistisempty}
 283
 284 \constfunc{bool}{IsEmpty}{\void}
 285
 286 Returns {\tt true} if the list is empty, {\tt false} otherwise.
 287
 288 % Use different label name to avoid clashing with wxListItem label
 289 \membersection{wxList::Item}\label{wxlistitemfunc}
 290
 291 \constfunc{wxNode<T> *}{Item}{\param{size\_t }{index}}
 292
 293 Returns the node at given position in the list.
 294
 295 \membersection{wxList::Member}\label{wxlistmember}
 296
 297 \func{wxNode<T> *}{Member}{\param{T *}{object}}
 298
 299 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
 300
 301 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 302
 303 \membersection{wxList::Nth}\label{wxlistnth}
 304
 305 \func{wxNode<T> *}{Nth}{\param{int}{ n}}
 306
 307 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
 308
 309 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 310 or the nth node could not be found).
 311
 312 \membersection{wxList::Number}\label{wxlistnumber}
 313
 314 \func{int}{Number}{\void}
 315
 316 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
 317
 318 Returns the number of elements in the list.
 319
 320 \membersection{wxList::Sort}\label{wxlistsort}
 321
 322 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 323
 324 \begin{verbatim}
 325   // Type of compare function for list sort operation (as in 'qsort')
 326   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 327 \end{verbatim}
 328
 329 Allows the sorting of arbitrary lists by giving
 330 a function to compare two list elements. We use the system {\bf qsort} function
 331 for the actual sorting process.
 332
 333 If you use untyped wxList the sort function receives pointers to wxObject
 334 pointers (wxObject **), so be careful to dereference appropriately - but,
 335 of course, a better solution is to use list of appropriate type defined with
 336 {\tt WX\_DECLARE\_LIST}.
 337
 338 Example:
 339
 340 \begin{verbatim}
 341   int listcompare(const void *arg1, const void *arg2)
 342   {
 343     return(compare(**(wxString **)arg1,    // use the wxString 'compare'
 344                    **(wxString **)arg2));  // function
 345   }
 346
 347   void main()
 348   {
 349     wxList list;
 350
 351     list.Append(new wxString("DEF"));
 352     list.Append(new wxString("GHI"));
 353     list.Append(new wxString("ABC"));
 354     list.Sort(listcompare);
 355   }
 356 \end{verbatim}