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