1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4 %% Author: wxWidgets Team
8 %% Copyright: (c) wxWidgets Team
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxList<T>
}}\label{wxlist
}
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*
}.
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.
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
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.
42 // this part might be in a header or source (.cpp) file
48 // this macro declares and partly implements MyList class
49 WX_DECLARE_LIST(MyListElement, MyList);
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
57 #include <wx/listimpl.cpp>
58 WX_DEFINE_LIST(MyList);
62 MyListElement element;
63 list.Append(&element); // ok
64 list.Append(
17); // error: incorrect type
66 // let's iterate over the list in STL syntax
67 MyList::iterator iter;
68 for (iter = list.begin(); iter != list.end(); ++iter)
70 MyListElement *current = *iter;
72 ...process the current element...
75 // the same with the legacy API from the old wxList class
76 MyList::compatibility_iterator node = list.GetFirst();
79 MyListElement *current = node->GetData();
81 ...process the current element...
83 node = node->GetNext();
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.
94 \wxheading{Include files
}
100 \helpref{wxBase
}{librarieslist
}
104 \helpref{wxArray<T>
}{wxarray
},
105 \helpref{wxVector<T>
}{wxvector
}
107 \latexignore{\rtfignore{\wxheading{Members
}}}
109 \membersection{wxList<T>::wxList<T>
}\label{wxlistctor
}
111 \func{}{wxList<T>
}{\void}
113 \func{}{wxList<T>
}{\param{size
\_t}{ count
},
\param{T *
}{elements
[]}}
117 \membersection{wxList<T>::
\destruct{wxList<T>
}}\label{wxlistdtor
}
119 \func{}{\destruct{wxList<T>
}}{\void}
121 Destroys the list, but does not delete the objects stored in the list
122 unless you called DeleteContents(
{\tt true
} ).
124 \membersection{wxList<T>::Append
}\label{wxlistappend
}
126 \func{wxList<T>::compatibility
\_iterator }{Append
}{\param{T *
}{object
}}
128 Appends the pointer to
\rtfsp{\it object
} to the list.
130 \membersection{wxList<T>::Clear
}\label{wxlistclear1
}
132 \func{void
}{Clear
}{\void}
134 Clears the list, but does not delete the objects stored in the list
135 unless you called DeleteContents(
{\tt true
} ).
137 \membersection{wxList<T>::DeleteContents
}\label{wxlistdeletecontents
}
139 \func{void
}{DeleteContents
}{\param{bool
}{ destroy
}}
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
}.
145 \membersection{wxList<T>::DeleteNode
}\label{wxlistdeletenode
}
147 \func{bool
}{DeleteNode
}{\param{const compatibility
\_iterator &
}{iter
}}
149 Deletes the given element refered to by
{\tt iter
} from the list,
150 returning
{\tt true
} if successful.
152 \membersection{wxList<T>::DeleteObject
}\label{wxlistdeleteobject
}
154 \func{bool
}{DeleteObject
}{\param{T *
}{object
}}
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
160 \membersection{wxList<T>::Erase
}\label{wxlisterase
}
162 \func{void
}{Erase
}{\param{const compatibility
\_iterator &
}{iter
}}
164 Removes element refered to be
{\tt iter
}.
166 \membersection{wxList<T>::Find
}\label{wxlistfind
}
168 \constfunc{wxList<T>::compatibility
\_iterator}{Find
}{\param{T *
}{ object
}}
170 Returns the iterator refering to
{\it object
} or NULL if none found.
172 \membersection{wxList<T>::GetCount
}\label{wxlistgetcount
}
174 \constfunc{size
\_t}{GetCount
}{\void}
176 Returns the number of elements in the list.
178 \membersection{wxList<T>::GetFirst
}\label{wxlistgetfirst
}
180 \constfunc{wxList<T>::compatibility
\_iterator}{GetFirst
}{\void}
182 Returns the first iterator in the list (NULL if the list is empty).
184 \membersection{wxList<T>::GetLast
}\label{wxlistgetlast
}
186 \constfunc{wxList<T>::compatibility
\_iterator}{GetLast
}{\void}
188 Returns the last iterator in the list (NULL if the list is empty).
190 \membersection{wxList<T>::IndexOf
}\label{wxlistindexof
}
192 \constfunc{int
}{IndexOf
}{\param{T*
}{ obj
}}
194 Returns the index of
{\it obj
} within the list or
{\tt wxNOT
\_FOUND} if
195 {\it obj
} is not found in the list.
197 \membersection{wxList<T>::Insert
}\label{wxlistinsert1
}
199 \func{wxList<T>::compatibility
\_iterator}{Insert
}{\param{T *
}{object
}}
201 Insert object at the front of list.
203 \func{wxList<T>::compatibility
\_iterator}{Insert
}{\param{size
\_t }{position
},
\param{T *
}{object
}}
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
}.
210 \func{wxList<T>::compatibility
\_iterator}{Insert
}{\param{compatibility
\_iterator}{iter
},
\param{T *
}{object
}}
212 Inserts the object before the object refered to be
{\it iter
}.
214 \membersection{wxList<T>::IsEmpty
}\label{wxlistisempty
}
216 \constfunc{bool
}{IsEmpty
}{\void}
218 Returns
{\tt true
} if the list is empty,
{\tt false
} otherwise.
220 % Use different label name to avoid clashing with wxListItem label
221 \membersection{wxList<T>::Item
}\label{wxlistitemfunc
}
223 \constfunc{wxList<T>::compatibility
\_iterator}{Item
}{\param{size
\_t }{index
}}
225 Returns the iterator refering to the object at the given
226 {\tt index
} in the list.
228 \membersection{wxList<T>::Member
}\label{wxlistmember
}
230 \constfunc{wxList<T>::compatibility
\_iterator}{Member
}{\param{T *
}{ object
}}
232 {\bf NB:
} This function is deprecated, use
\helpref{Find
}{wxlistfind
} instead.
234 \membersection{wxList<T>::Nth
}\label{wxlistnth
}
236 \constfunc{wxList<T>::compatibility
\_iterator}{Nth
}{\param{int
}{n
}}
238 {\bf NB:
} This function is deprecated, use
\helpref{Item
}{wxlistitemfunc
} instead.
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).
243 \membersection{wxList<T>::Number
}\label{wxlistnumber
}
245 \constfunc{int
}{Number
}{\void}
247 {\bf NB:
} This function is deprecated, use
\helpref{GetCount
}{wxlistgetcount
} instead.
249 Returns the number of elements in the list.
251 \membersection{wxList<T>::Sort
}\label{wxlistsort
}
253 \func{void
}{Sort
}{\param{wxSortCompareFunction
}{ compfunc
}}
256 // Type of compare function for list sort operation (as in 'qsort')
257 typedef int
(*wxSortCompareFunction)(const void *elem1, const void *elem2);
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
266 \membersection{wxList<T>::assign}\label{wxlistassign}
268 \func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
271 \func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
274 \membersection{wxList<T>::back}\label{wxlistback}
276 \func{reference}{back}{\void}
278 \constfunc{const\_reference}{back}{\void}
280 Returns the last item of the list.
282 \membersection{wxList<T>::begin}\label{wxlistbegin}
284 \func{iterator}{begin}{\void}
286 \constfunc{const\_iterator}{begin}{\void}
288 Returns a (const) iterator pointing to the beginning of the list.
290 \membersection{wxList<T>::clear}\label{wxlistclear}
292 \func{void}{clear}{\void}
294 Removes all items from the list.
296 \membersection{wxList<T>::empty}\label{wxlistempty}
298 \constfunc{bool}{empty}{\void}
300 Returns {\it true} if the list is empty.
302 \membersection{wxList<T>::end}\label{wxlistend}
304 \func{iterator}{end}{\void}
306 \constfunc{const\_iterator}{end}{\void}
308 Returns a (const) iterator pointing at the end of the list.
310 \membersection{wxList<T>::erase}\label{wxlisterase2}
312 \func{iterator}{erase}{\param{const iterator\& }{it}}
314 Erases the item pointed to by {\it it}.
316 \func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}}
318 Erases the items from {\it first} to {\it last}.
320 \membersection{wxList<T>::front}\label{wxlistfront}
322 \func{reference}{front}{\void}
324 \constfunc{const\_reference}{front}{\void}
326 Returns the first item in the list.
328 \membersection{wxList<T>::insert}\label{wxlistinsert}
330 \func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}}
332 \func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
334 \func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
336 Inserts an item (or several) at the given position.
338 \membersection{wxList<T>::max\_size}\label{wxlistmaxsize}
340 \constfunc{size\_type}{max\_size}{\void}
342 Returns the largest possible size of the list.
344 \membersection{wxList<T>::pop\_back}\label{wxlistpopback}
346 \func{void}{pop\_back}{\void}
348 Removes the last item from the list.
350 \membersection{wxList<T>::pop\_front}\label{wxlistpopfront}
352 \func{void}{pop\_front}{\void}
354 Removes the first item from the list.
356 \membersection{wxList<T>::push\_back}\label{wxlistpushback}
358 \func{void}{push\_back}{\param{const\_reference }{v = value\_type()}}
360 Adds an item to end of the list.
362 \membersection{wxList<T>::push\_front}\label{wxlistpushfront}
364 \func{void}{push\_front}{\param{const\_reference }{v = value\_type()}}
366 Adds an item to the front of the list.
368 \membersection{wxList<T>::rbegin}\label{wxlistrbegin}
370 \func{reverse\_iterator}{rbegin}{\void}
372 \constfunc{const\_reverse\_iterator}{rbegin}{\void}
374 Returns a (const) reverse iterator pointing to the beginning of the
377 \membersection{wxList<T>::remove}\label{wxlistremove}
379 \func{void}{remove}{\param{const\_reference }{v}}
381 Removes an item from the list.
383 \membersection{wxList<T>::rend}\label{wxlistrend}
385 \func{reverse\_iterator}{rend}{\void}
387 \constfunc{const\_reverse\_iterator}{rend}{\void}
389 Returns a (const) reverse iterator pointing to the end of the
392 \membersection{wxList<T>::resize}\label{wxlistresize}
394 \func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}}
396 Resizes the list. If the the list is enlarges items with
397 the value {\it v} are appended to the list.
399 \membersection{wxList<T>::reverse}\label{wxlistreverse}
401 \func{void}{reverse}{\void}
405 \membersection{wxList<T>::size}\label{wxlistsize}
407 \constfunc{size\_type}{size}{\void}
409 Returns the size of the list.
411 \membersection{wxList<T>::splice}\label{wxlistsplice}
413 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}}
415 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}}
417 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}}
419 Moves part of the list into another list, starting from {\it first} and
420 ending at {\it last} if specified.