]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/list.tex
cleanup
[wxWidgets.git] / 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<T>}}\label{wxlist}
13
14 The wxList<T> class provides linked list functionality. It has been written
15 to be type safe and to provide the full API of the STL std::list container and
16 should be used like it. The exception is that wxList<T> actually stores
17 pointers and therefore its iterators return pointers and not references
18 to the actual objets in the list (see example below) and {\it value\_type}
19 is defined as {\it T*}.
20
21
22 Unfortunately, the
23 new wxList<T> class requires that you declare and define each wxList<T>
24 class in your program. This is done with {\it WX\_DECLARE\_LIST} and
25 {\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able
26 to provide a proper template class providing both the STL std::list
27 and the old wxList API in the future.
28
29 Please refer to the STL std::list documentation for further
30 information on how to use the class. Below we documented both
31 the supported STL and the legacy API that originated from the
32 old wxList class and which can still be used alternatively for
33 the the same class.
34
35 Note that if you compile wxWidgets in STL mode (wxUSE\_STL defined as 1)
36 then wxList<T> will actually derive from std::list and just add a legacy
37 compatibility layer for the old wxList class.
38
39 \wxheading{Example}
40
41 \begin{verbatim}
42 // this part might be in a header or source (.cpp) file
43 class MyListElement
44 {
45 ... // whatever
46 };
47
48 // this macro declares and partly implements MyList class
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
61 MyList list;
62 MyListElement element;
63 list.Append(&element); // ok
64 list.Append(17); // error: incorrect type
65
66 // let's iterate over the list in STL syntax
67 MyList::iterator iter;
68 for (iter = list.begin(); iter != list.end(); ++iter)
69 {
70 MyListElement *current = *iter;
71
72 ...process the current element...
73 }
74
75 // the same with the legacy API from the old wxList class
76 MyList::compatibility_iterator node = list.GetFirst();
77 while (node)
78 {
79 MyListElement *current = node->GetData();
80
81 ...process the current element...
82
83 node = node->GetNext();
84 }
85
86 \end{verbatim}
87
88 For compatibility with previous versions wxList and wxStringList classes are
89 still defined, but their usage is deprecated and they will disappear in the
90 future versions completely. The use of the latter is especially discouraged as
91 it is not only unsafe but is also much less efficient than
92 \helpref{wxArrayString}{wxarraystring} class.
93
94 \wxheading{Include files}
95
96 <wx/list.h>
97
98 \wxheading{Library}
99
100 \helpref{wxBase}{librarieslist}
101
102 \wxheading{See also}
103
104 \helpref{wxArray<T>}{wxarray},
105 \helpref{wxVector<T>}{wxvector}
106
107 \latexignore{\rtfignore{\wxheading{Members}}}
108
109 \membersection{wxList<T>::wxList<T>}\label{wxlistctor}
110
111 \func{}{wxList<T>}{\void}
112
113 \func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}}
114
115 Constructors.
116
117 \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}
118
119 \func{}{\destruct{wxList<T>}}{\void}
120
121 Destroys the list, but does not delete the objects stored in the list
122 unless you called DeleteContents({\tt true} ).
123
124 \membersection{wxList<T>::Append}\label{wxlistappend}
125
126 \func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}}
127
128 Appends the pointer to \rtfsp{\it object} to the list.
129
130 \membersection{wxList<T>::Clear}\label{wxlistclear1}
131
132 \func{void}{Clear}{\void}
133
134 Clears the list, but does not delete the objects stored in the list
135 unless you called DeleteContents({\tt true} ).
136
137 \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}
138
139 \func{void}{DeleteContents}{\param{bool}{ destroy}}
140
141 If {\it destroy} is {\tt true}, instructs the list to call {\it delete}
142 on objects stored in the list whenever they are removed.
143 The default is {\tt false}.
144
145 \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}
146
147 \func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}}
148
149 Deletes the given element refered to by {\tt iter} from the list,
150 returning {\tt true} if successful.
151
152 \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}
153
154 \func{bool}{DeleteObject}{\param{T *}{object}}
155
156 Finds the given {\it object} and removes it from the list, returning
157 {\tt true} if successful. The application must delete the actual object
158 separately.
159
160 \membersection{wxList<T>::Erase}\label{wxlisterase}
161
162 \func{void}{Erase}{\param{const compatibility\_iterator &}{iter}}
163
164 Removes element refered to be {\tt iter}.
165
166 \membersection{wxList<T>::Find}\label{wxlistfind}
167
168 \constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}}
169
170 Returns the iterator refering to {\it object} or NULL if none found.
171
172 \membersection{wxList<T>::GetCount}\label{wxlistgetcount}
173
174 \constfunc{size\_t}{GetCount}{\void}
175
176 Returns the number of elements in the list.
177
178 \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}
179
180 \constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void}
181
182 Returns the first iterator in the list (NULL if the list is empty).
183
184 \membersection{wxList<T>::GetLast}\label{wxlistgetlast}
185
186 \constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void}
187
188 Returns the last iterator in the list (NULL if the list is empty).
189
190 \membersection{wxList<T>::IndexOf}\label{wxlistindexof}
191
192 \constfunc{int}{IndexOf}{\param{T*}{ obj }}
193
194 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
195 {\it obj} is not found in the list.
196
197 \membersection{wxList<T>::Insert}\label{wxlistinsert1}
198
199 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}}
200
201 Insert object at the front of list.
202
203 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
204
205 Insert object before {\it position}, i.e. the index of the new item in the
206 list will be equal to {\it position}. {\it position} should be less than or
207 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
208 same as calling \helpref{Append}{wxlistappend}.
209
210 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}}
211
212 Inserts the object before the object refered to be {\it iter}.
213
214 \membersection{wxList<T>::IsEmpty}\label{wxlistisempty}
215
216 \constfunc{bool}{IsEmpty}{\void}
217
218 Returns {\tt true} if the list is empty, {\tt false} otherwise.
219
220 % Use different label name to avoid clashing with wxListItem label
221 \membersection{wxList<T>::Item}\label{wxlistitemfunc}
222
223 \constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}}
224
225 Returns the iterator refering to the object at the given
226 {\tt index} in the list.
227
228 \membersection{wxList<T>::Member}\label{wxlistmember}
229
230 \constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}}
231
232 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
233
234 \membersection{wxList<T>::Nth}\label{wxlistnth}
235
236 \constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}}
237
238 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
239
240 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
241 or the nth node could not be found).
242
243 \membersection{wxList<T>::Number}\label{wxlistnumber}
244
245 \constfunc{int}{Number}{\void}
246
247 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
248
249 Returns the number of elements in the list.
250
251 \membersection{wxList<T>::Sort}\label{wxlistsort}
252
253 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
254
255 \begin{verbatim}
256 // Type of compare function for list sort operation (as in 'qsort')
257 typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
258 \end{verbatim}
259
260 Allows the sorting of arbitrary lists by giving a function to compare
261 two list elements. We use the system {\bf qsort} function for the actual
262 sorting process.
263
264
265
266 \membersection{wxList<T>::assign}\label{wxlistassign}
267
268 \func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
269
270
271 \func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
272
273
274 \membersection{wxList<T>::back}\label{wxlistback}
275
276 \func{reference}{back}{\void}
277
278 \constfunc{const\_reference}{back}{\void}
279
280 Returns the last item of the list.
281
282 \membersection{wxList<T>::begin}\label{wxlistbegin}
283
284 \func{iterator}{begin}{\void}
285
286 \constfunc{const\_iterator}{begin}{\void}
287
288 Returns a (const) iterator pointing to the beginning of the list.
289
290 \membersection{wxList<T>::clear}\label{wxlistclear}
291
292 \func{void}{clear}{\void}
293
294 Removes all items from the list.
295
296 \membersection{wxList<T>::empty}\label{wxlistempty}
297
298 \constfunc{bool}{empty}{\void}
299
300 Returns {\it true} if the list is empty.
301
302 \membersection{wxList<T>::end}\label{wxlistend}
303
304 \func{iterator}{end}{\void}
305
306 \constfunc{const\_iterator}{end}{\void}
307
308 Returns a (const) iterator pointing at the end of the list.
309
310 \membersection{wxList<T>::erase}\label{wxlisterase2}
311
312 \func{iterator}{erase}{\param{const iterator\& }{it}}
313
314 Erases the item pointed to by {\it it}.
315
316 \func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}}
317
318 Erases the items from {\it first} to {\it last}.
319
320 \membersection{wxList<T>::front}\label{wxlistfront}
321
322 \func{reference}{front}{\void}
323
324 \constfunc{const\_reference}{front}{\void}
325
326 Returns the first item in the list.
327
328 \membersection{wxList<T>::insert}\label{wxlistinsert}
329
330 \func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}}
331
332 \func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
333
334 \func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
335
336 Inserts an item (or several) at the given position.
337
338 \membersection{wxList<T>::max\_size}\label{wxlistmaxsize}
339
340 \constfunc{size\_type}{max\_size}{\void}
341
342 Returns the largest possible size of the list.
343
344 \membersection{wxList<T>::pop\_back}\label{wxlistpopback}
345
346 \func{void}{pop\_back}{\void}
347
348 Removes the last item from the list.
349
350 \membersection{wxList<T>::pop\_front}\label{wxlistpopfront}
351
352 \func{void}{pop\_front}{\void}
353
354 Removes the first item from the list.
355
356 \membersection{wxList<T>::push\_back}\label{wxlistpushback}
357
358 \func{void}{push\_back}{\param{const\_reference }{v = value\_type()}}
359
360 Adds an item to end of the list.
361
362 \membersection{wxList<T>::push\_front}\label{wxlistpushfront}
363
364 \func{void}{push\_front}{\param{const\_reference }{v = value\_type()}}
365
366 Adds an item to the front of the list.
367
368 \membersection{wxList<T>::rbegin}\label{wxlistrbegin}
369
370 \func{reverse\_iterator}{rbegin}{\void}
371
372 \constfunc{const\_reverse\_iterator}{rbegin}{\void}
373
374 Returns a (const) reverse iterator pointing to the beginning of the
375 reversed list.
376
377 \membersection{wxList<T>::remove}\label{wxlistremove}
378
379 \func{void}{remove}{\param{const\_reference }{v}}
380
381 Removes an item from the list.
382
383 \membersection{wxList<T>::rend}\label{wxlistrend}
384
385 \func{reverse\_iterator}{rend}{\void}
386
387 \constfunc{const\_reverse\_iterator}{rend}{\void}
388
389 Returns a (const) reverse iterator pointing to the end of the
390 reversed list.
391
392 \membersection{wxList<T>::resize}\label{wxlistresize}
393
394 \func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}}
395
396 Resizes the list. If the the list is enlarges items with
397 the value {\it v} are appended to the list.
398
399 \membersection{wxList<T>::reverse}\label{wxlistreverse}
400
401 \func{void}{reverse}{\void}
402
403 Reverses the list.
404
405 \membersection{wxList<T>::size}\label{wxlistsize}
406
407 \constfunc{size\_type}{size}{\void}
408
409 Returns the size of the list.
410
411 \membersection{wxList<T>::splice}\label{wxlistsplice}
412
413 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}}
414
415 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}}
416
417 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}}
418
419 Moves part of the list into another list, starting from {\it first} and
420 ending at {\it last} if specified.