]>
Commit | Line | Data |
---|---|---|
1ac74d83 WS |
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 | ||
83e51c48 RR |
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 | |
cb367500 RR |
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 | |
83e51c48 RR |
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 | |
cb367500 RR |
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. | |
83e51c48 | 34 | |
7e57f04a | 35 | Note that if you compile wxWidgets in STL mode (wxUSE\_STL defined as 1) |
83e51c48 RR |
36 | then wxList<T> will actually derive from std::list and just add a legacy |
37 | compatibility layer for the old wxList class. | |
38 | ||
6e6110ee VZ |
39 | \wxheading{Example} |
40 | ||
6e6110ee VZ |
41 | \begin{verbatim} |
42 | // this part might be in a header or source (.cpp) file | |
43 | class MyListElement | |
44 | { | |
45 | ... // whatever | |
46 | }; | |
47 | ||
83e51c48 | 48 | // this macro declares and partly implements MyList class |
f776e250 | 49 | WX_DECLARE_LIST(MyListElement, MyList); |
6e6110ee VZ |
50 | |
51 | ... | |
52 | ||
2edb0bde | 53 | // the only requirement for the rest is to be AFTER the full declaration of |
6e6110ee VZ |
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> | |
f776e250 | 58 | WX_DEFINE_LIST(MyList); |
6e6110ee | 59 | |
83e51c48 | 60 | |
6e6110ee VZ |
61 | MyList list; |
62 | MyListElement element; | |
1ac74d83 | 63 | list.Append(&element); // ok |
bb250157 | 64 | list.Append(17); // error: incorrect type |
6e6110ee | 65 | |
83e51c48 RR |
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) | |
6e6110ee VZ |
78 | { |
79 | MyListElement *current = node->GetData(); | |
80 | ||
81 | ...process the current element... | |
83e51c48 RR |
82 | |
83 | node = node->GetNext(); | |
6e6110ee | 84 | } |
83e51c48 | 85 | |
6e6110ee | 86 | \end{verbatim} |
6e6110ee VZ |
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 | |
703f03c3 | 90 | future versions completely. The use of the latter is especially discouraged as |
1ac74d83 | 91 | it is not only unsafe but is also much less efficient than |
35d367d8 | 92 | \helpref{wxArrayString}{wxarraystring} class. |
a660d684 | 93 | |
954b8ae6 JS |
94 | \wxheading{Include files} |
95 | ||
96 | <wx/list.h> | |
97 | ||
a7af285d VZ |
98 | \wxheading{Library} |
99 | ||
100 | \helpref{wxBase}{librarieslist} | |
101 | ||
a660d684 KB |
102 | \wxheading{See also} |
103 | ||
6e6110ee | 104 | \helpref{wxArray}{wxarray} |
a660d684 KB |
105 | |
106 | \latexignore{\rtfignore{\wxheading{Members}}} | |
107 | ||
83e51c48 | 108 | \membersection{wxList<T>::wxList<T>}\label{wxlistctor} |
2bbd97f4 | 109 | |
83e51c48 | 110 | \func{}{wxList<T>}{\void} |
a660d684 | 111 | |
7e57f04a | 112 | \func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}} |
a660d684 | 113 | |
83e51c48 | 114 | Constructors. |
a660d684 | 115 | |
83e51c48 | 116 | \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor} |
a660d684 | 117 | |
83e51c48 | 118 | \func{}{\destruct{wxList<T>}}{\void} |
a660d684 | 119 | |
83e51c48 RR |
120 | Destroys the list, but does not delete the objects stored in the list |
121 | unless you called DeleteContents({\tt true} ). | |
a660d684 | 122 | |
83e51c48 | 123 | \membersection{wxList<T>::Append}\label{wxlistappend} |
a660d684 | 124 | |
e7ec3618 | 125 | \func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}} |
a660d684 | 126 | |
83e51c48 | 127 | Appends the pointer to \rtfsp{\it object} to the list. |
2bbd97f4 | 128 | |
83e51c48 | 129 | \membersection{wxList<T>::Clear}\label{wxlistclear} |
a660d684 KB |
130 | |
131 | \func{void}{Clear}{\void} | |
132 | ||
83e51c48 RR |
133 | Clears the list, but does not delete the objects stored in the list |
134 | unless you called DeleteContents({\tt true} ). | |
a660d684 | 135 | |
83e51c48 | 136 | \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents} |
a660d684 KB |
137 | |
138 | \func{void}{DeleteContents}{\param{bool}{ destroy}} | |
139 | ||
83e51c48 RR |
140 | If {\it destroy} is {\tt true}, instructs the list to call {\it delete} |
141 | on objects stored in the list whenever they are removed. | |
142 | The default is {\tt false}. | |
a660d684 | 143 | |
83e51c48 | 144 | \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode} |
a660d684 | 145 | |
e7ec3618 | 146 | \func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}} |
a660d684 | 147 | |
83e51c48 RR |
148 | Deletes the given element refered to by {\tt iter} from the list, |
149 | returning {\tt true} if successful. | |
a660d684 | 150 | |
83e51c48 | 151 | \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject} |
a660d684 | 152 | |
2b5f62a0 | 153 | \func{bool}{DeleteObject}{\param{T *}{object}} |
a660d684 | 154 | |
83e51c48 RR |
155 | Finds the given {\it object} and removes it from the list, returning |
156 | {\tt true} if successful. The application must delete the actual object | |
157 | separately. | |
e0ad14ca | 158 | |
83e51c48 | 159 | \membersection{wxList<T>::Erase}\label{wxlisterase} |
a660d684 | 160 | |
e7ec3618 | 161 | \func{void}{Erase}{\param{const compatibility\_iterator &}{iter}} |
a660d684 | 162 | |
83e51c48 | 163 | Removes element refered to be {\tt iter}. |
2b5f62a0 | 164 | |
83e51c48 | 165 | \membersection{wxList<T>::Find}\label{wxlistfind} |
2bbd97f4 | 166 | |
e7ec3618 | 167 | \constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}} |
2b5f62a0 | 168 | |
83e51c48 | 169 | Returns the iterator refering to {\it object} or NULL if none found. |
a660d684 | 170 | |
83e51c48 | 171 | \membersection{wxList<T>::GetCount}\label{wxlistgetcount} |
d8996187 VZ |
172 | |
173 | \constfunc{size\_t}{GetCount}{\void} | |
174 | ||
175 | Returns the number of elements in the list. | |
176 | ||
83e51c48 | 177 | \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst} |
a660d684 | 178 | |
e7ec3618 | 179 | \constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void} |
a660d684 | 180 | |
83e51c48 | 181 | Returns the first iterator in the list (NULL if the list is empty). |
a660d684 | 182 | |
83e51c48 | 183 | \membersection{wxList<T>::GetLast}\label{wxlistgetlast} |
d8996187 | 184 | |
e7ec3618 | 185 | \constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void} |
d8996187 | 186 | |
83e51c48 | 187 | Returns the last iterator in the list (NULL if the list is empty). |
d8996187 | 188 | |
83e51c48 | 189 | \membersection{wxList<T>::IndexOf}\label{wxlistindexof} |
77c5eefb | 190 | |
83e51c48 | 191 | \constfunc{int}{IndexOf}{\param{T*}{ obj }} |
77c5eefb | 192 | |
83e51c48 RR |
193 | Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if |
194 | {\it obj} is not found in the list. | |
77c5eefb | 195 | |
83e51c48 | 196 | \membersection{wxList<T>::Insert}\label{wxlistinsert} |
a660d684 | 197 | |
e7ec3618 | 198 | \func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}} |
a660d684 | 199 | |
83e51c48 | 200 | Insert object at the front of list. |
a660d684 | 201 | |
e7ec3618 | 202 | \func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}} |
a660d684 | 203 | |
d8996187 VZ |
204 | Insert object before {\it position}, i.e. the index of the new item in the |
205 | list will be equal to {\it position}. {\it position} should be less than or | |
206 | equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the | |
207 | same as calling \helpref{Append}{wxlistappend}. | |
a660d684 | 208 | |
e7ec3618 | 209 | \func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}} |
a660d684 | 210 | |
83e51c48 | 211 | Inserts the object before the object refered to be {\it iter}. |
a660d684 | 212 | |
83e51c48 | 213 | \membersection{wxList<T>::IsEmpty}\label{wxlistisempty} |
b79a8705 VZ |
214 | |
215 | \constfunc{bool}{IsEmpty}{\void} | |
216 | ||
cc81d32f | 217 | Returns {\tt true} if the list is empty, {\tt false} otherwise. |
b79a8705 | 218 | |
0b0625e9 | 219 | % Use different label name to avoid clashing with wxListItem label |
83e51c48 | 220 | \membersection{wxList<T>::Item}\label{wxlistitemfunc} |
a660d684 | 221 | |
e7ec3618 | 222 | \constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}} |
d8996187 | 223 | |
83e51c48 RR |
224 | Returns the iterator refering to the object at the given |
225 | {\tt index} in the list. | |
a660d684 | 226 | |
83e51c48 | 227 | \membersection{wxList<T>::Member}\label{wxlistmember} |
a660d684 | 228 | |
e7ec3618 | 229 | \constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}} |
a660d684 | 230 | |
d8996187 VZ |
231 | {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. |
232 | ||
83e51c48 | 233 | \membersection{wxList<T>::Nth}\label{wxlistnth} |
a660d684 | 234 | |
e7ec3618 | 235 | \constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}} |
a660d684 | 236 | |
0b0625e9 | 237 | {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead. |
d8996187 | 238 | |
a660d684 KB |
239 | Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty |
240 | or the nth node could not be found). | |
241 | ||
83e51c48 | 242 | \membersection{wxList<T>::Number}\label{wxlistnumber} |
a660d684 | 243 | |
83e51c48 | 244 | \constfunc{int}{Number}{\void} |
a660d684 | 245 | |
d8996187 VZ |
246 | {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead. |
247 | ||
a660d684 KB |
248 | Returns the number of elements in the list. |
249 | ||
83e51c48 | 250 | \membersection{wxList<T>::Sort}\label{wxlistsort} |
a660d684 KB |
251 | |
252 | \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} | |
253 | ||
254 | \begin{verbatim} | |
255 | // Type of compare function for list sort operation (as in 'qsort') | |
256 | typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2); | |
257 | \end{verbatim} | |
258 | ||
83e51c48 RR |
259 | Allows the sorting of arbitrary lists by giving a function to compare |
260 | two list elements. We use the system {\bf qsort} function for the actual | |
261 | sorting process. | |
a660d684 | 262 | |
cb367500 RR |
263 | |
264 | ||
265 | \membersection{wxList<T>::assign}\label{wxlistassign} | |
266 | ||
267 | \func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} | |
268 | ||
269 | ||
270 | \func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} | |
271 | ||
272 | ||
273 | \membersection{wxList<T>::back}\label{wxlistback} | |
274 | ||
275 | \func{reference}{back}{\void} | |
276 | ||
277 | \constfunc{const\_reference}{back}{\void} | |
278 | ||
279 | Returns the last item of the list. | |
280 | ||
281 | \membersection{wxList<T>::begin}\label{wxlistbegin} | |
282 | ||
283 | \func{iterator}{begin}{\void} | |
284 | ||
285 | \constfunc{const\_iterator}{begin}{\void} | |
286 | ||
287 | Returns a (const) iterator pointing to the beginning of the list. | |
288 | ||
289 | \membersection{wxList<T>::clear}\label{wxlistclear} | |
290 | ||
291 | \func{void}{clear}{\void} | |
292 | ||
293 | Removes all items from the list. | |
294 | ||
295 | \membersection{wxList<T>::empty}\label{wxlistempty} | |
296 | ||
297 | \constfunc{bool}{empty}{\void} | |
298 | ||
299 | Returns {\it true} if the list is empty. | |
300 | ||
301 | \membersection{wxList<T>::end}\label{wxlistend} | |
302 | ||
303 | \func{iterator}{end}{\void} | |
304 | ||
305 | \constfunc{const\_iterator}{end}{\void} | |
306 | ||
307 | Returns a (const) iterator pointing at the end of the list. | |
308 | ||
309 | \membersection{wxList<T>::erase}\label{wxlisterase2} | |
310 | ||
311 | \func{iterator}{erase}{\param{const iterator\& }{it}} | |
312 | ||
313 | Erases the item pointed to by {\it it}. | |
314 | ||
315 | \func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}} | |
316 | ||
317 | Erases the items from {\it first} to {\it last}. | |
318 | ||
319 | \membersection{wxList<T>::front}\label{wxlistfront} | |
320 | ||
321 | \func{reference}{front}{\void} | |
322 | ||
323 | \constfunc{const\_reference}{front}{\void} | |
324 | ||
325 | Returns the first item in the list. | |
326 | ||
327 | \membersection{wxList<T>::insert}\label{wxlistinsert} | |
328 | ||
329 | \func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}} | |
330 | ||
331 | \func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} | |
332 | ||
333 | \func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} | |
334 | ||
335 | Inserts an item (or several) at the given position. | |
336 | ||
337 | \membersection{wxList<T>::max\_size}\label{wxlistmax\_size} | |
338 | ||
339 | \constfunc{size\_type}{max\_size}{\void} | |
340 | ||
341 | Returns the largest possible size of the list. | |
342 | ||
343 | \membersection{wxList<T>::pop\_back}\label{wxlistpop\_back} | |
344 | ||
345 | \func{void}{pop\_back}{\void} | |
346 | ||
347 | Removes the last item from the list. | |
348 | ||
349 | \membersection{wxList<T>::pop\_front}\label{wxlistpop\_front} | |
350 | ||
351 | \func{void}{pop\_front}{\void} | |
352 | ||
353 | Removes the first item from the list. | |
354 | ||
355 | \membersection{wxList<T>::push\_back}\label{wxlistpush\_back} | |
356 | ||
357 | \func{void}{push\_back}{\param{const\_reference }{v = value\_type()}} | |
358 | ||
359 | Adds an item to end of the list. | |
360 | ||
361 | \membersection{wxList<T>::push\_front}\label{wxlistpush\_front} | |
362 | ||
363 | \func{void}{push\_front}{\param{const\_reference }{v = value\_type()}} | |
364 | ||
365 | Adds an item to the front of the list. | |
366 | ||
367 | \membersection{wxList<T>::rbegin}\label{wxlistrbegin} | |
368 | ||
369 | \func{reverse\_iterator}{rbegin}{\void} | |
370 | ||
371 | \constfunc{const\_reverse\_iterator}{rbegin}{\void} | |
372 | ||
373 | Returns a (const) reverse iterator pointing to the beginning of the | |
374 | reversed list. | |
375 | ||
376 | \membersection{wxList<T>::remove}\label{wxlistremove} | |
377 | ||
378 | \func{void}{remove}{\param{const\_reference }{v}} | |
379 | ||
380 | Removes an item from the list. | |
381 | ||
382 | \membersection{wxList<T>::rend}\label{wxlistrend} | |
383 | ||
384 | \func{reverse\_iterator}{rend}{\void} | |
385 | ||
386 | \constfunc{const\_reverse\_iterator}{rend}{\void} | |
387 | ||
388 | Returns a (const) reverse iterator pointing to the end of the | |
389 | reversed list. | |
390 | ||
391 | \membersection{wxList<T>::resize}\label{wxlistresize} | |
392 | ||
393 | \func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}} | |
394 | ||
395 | Resizes the list. If the the list is enlarges items with | |
396 | the value {\it v} are appended to the list. | |
397 | ||
398 | \membersection{wxList<T>::reverse}\label{wxlistreverse} | |
399 | ||
400 | \func{void}{reverse}{\void} | |
401 | ||
402 | Reverses the list. | |
403 | ||
404 | \membersection{wxList<T>::size}\label{wxlistsize} | |
405 | ||
406 | \constfunc{size\_type}{size}{\void} | |
407 | ||
408 | Returns the size of the list. | |
409 | ||
410 | \membersection{wxList<T>::splice}\label{wxlistsplice} | |
411 | ||
412 | \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}} | |
413 | ||
414 | \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}} | |
415 | ||
416 | \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}} | |
417 | ||
418 | Moves part of the list into another list, starting from {\it first} and | |
419 | ending at {\it last} if specified. |