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
}{wxarray
}
106 \latexignore{\rtfignore{\wxheading{Members
}}}
108 \membersection{wxList<T>::wxList<T>
}\label{wxlistctor
}
110 \func{}{wxList<T>
}{\void}
112 \func{}{wxList<T>
}{\param{size
\_t}{ count
},
\param{T *
}{elements
[]}}
116 \membersection{wxList<T>::
\destruct{wxList<T>
}}\label{wxlistdtor
}
118 \func{}{\destruct{wxList<T>
}}{\void}
120 Destroys the list, but does not delete the objects stored in the list
121 unless you called DeleteContents(
{\tt true
} ).
123 \membersection{wxList<T>::Append
}\label{wxlistappend
}
125 \func{wxList<T>::compatibility
\_iterator }{Append
}{\param{T *
}{object
}}
127 Appends the pointer to
\rtfsp{\it object
} to the list.
129 \membersection{wxList<T>::Clear
}\label{wxlistclear
}
131 \func{void
}{Clear
}{\void}
133 Clears the list, but does not delete the objects stored in the list
134 unless you called DeleteContents(
{\tt true
} ).
136 \membersection{wxList<T>::DeleteContents
}\label{wxlistdeletecontents
}
138 \func{void
}{DeleteContents
}{\param{bool
}{ destroy
}}
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
}.
144 \membersection{wxList<T>::DeleteNode
}\label{wxlistdeletenode
}
146 \func{bool
}{DeleteNode
}{\param{const compatibility
\_iterator &
}{iter
}}
148 Deletes the given element refered to by
{\tt iter
} from the list,
149 returning
{\tt true
} if successful.
151 \membersection{wxList<T>::DeleteObject
}\label{wxlistdeleteobject
}
153 \func{bool
}{DeleteObject
}{\param{T *
}{object
}}
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
159 \membersection{wxList<T>::Erase
}\label{wxlisterase
}
161 \func{void
}{Erase
}{\param{const compatibility
\_iterator &
}{iter
}}
163 Removes element refered to be
{\tt iter
}.
165 \membersection{wxList<T>::Find
}\label{wxlistfind
}
167 \constfunc{wxList<T>::compatibility
\_iterator}{Find
}{\param{T *
}{ object
}}
169 Returns the iterator refering to
{\it object
} or NULL if none found.
171 \membersection{wxList<T>::GetCount
}\label{wxlistgetcount
}
173 \constfunc{size
\_t}{GetCount
}{\void}
175 Returns the number of elements in the list.
177 \membersection{wxList<T>::GetFirst
}\label{wxlistgetfirst
}
179 \constfunc{wxList<T>::compatibility
\_iterator}{GetFirst
}{\void}
181 Returns the first iterator in the list (NULL if the list is empty).
183 \membersection{wxList<T>::GetLast
}\label{wxlistgetlast
}
185 \constfunc{wxList<T>::compatibility
\_iterator}{GetLast
}{\void}
187 Returns the last iterator in the list (NULL if the list is empty).
189 \membersection{wxList<T>::IndexOf
}\label{wxlistindexof
}
191 \constfunc{int
}{IndexOf
}{\param{T*
}{ obj
}}
193 Returns the index of
{\it obj
} within the list or
{\tt wxNOT
\_FOUND} if
194 {\it obj
} is not found in the list.
196 \membersection{wxList<T>::Insert
}\label{wxlistinsert
}
198 \func{wxList<T>::compatibility
\_iterator}{Insert
}{\param{T *
}{object
}}
200 Insert object at the front of list.
202 \func{wxList<T>::compatibility
\_iterator}{Insert
}{\param{size
\_t }{position
},
\param{T *
}{object
}}
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
}.
209 \func{wxList<T>::compatibility
\_iterator}{Insert
}{\param{compatibility
\_iterator}{iter
},
\param{T *
}{object
}}
211 Inserts the object before the object refered to be
{\it iter
}.
213 \membersection{wxList<T>::IsEmpty
}\label{wxlistisempty
}
215 \constfunc{bool
}{IsEmpty
}{\void}
217 Returns
{\tt true
} if the list is empty,
{\tt false
} otherwise.
219 % Use different label name to avoid clashing with wxListItem label
220 \membersection{wxList<T>::Item
}\label{wxlistitemfunc
}
222 \constfunc{wxList<T>::compatibility
\_iterator}{Item
}{\param{size
\_t }{index
}}
224 Returns the iterator refering to the object at the given
225 {\tt index
} in the list.
227 \membersection{wxList<T>::Member
}\label{wxlistmember
}
229 \constfunc{wxList<T>::compatibility
\_iterator}{Member
}{\param{T *
}{ object
}}
231 {\bf NB:
} This function is deprecated, use
\helpref{Find
}{wxlistfind
} instead.
233 \membersection{wxList<T>::Nth
}\label{wxlistnth
}
235 \constfunc{wxList<T>::compatibility
\_iterator}{Nth
}{\param{int
}{n
}}
237 {\bf NB:
} This function is deprecated, use
\helpref{Item
}{wxlistitemfunc
} instead.
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).
242 \membersection{wxList<T>::Number
}\label{wxlistnumber
}
244 \constfunc{int
}{Number
}{\void}
246 {\bf NB:
} This function is deprecated, use
\helpref{GetCount
}{wxlistgetcount
} instead.
248 Returns the number of elements in the list.
250 \membersection{wxList<T>::Sort
}\label{wxlistsort
}
252 \func{void
}{Sort
}{\param{wxSortCompareFunction
}{ compfunc
}}
255 // Type of compare function for list sort operation (as in 'qsort')
256 typedef int
(*wxSortCompareFunction)(const void *elem1, const void *elem2);
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
265 \membersection{wxList<T>::assign}\label{wxlistassign}
267 \func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
270 \func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
273 \membersection{wxList<T>::back}\label{wxlistback}
275 \func{reference}{back}{\void}
277 \constfunc{const\_reference}{back}{\void}
279 Returns the last item of the list.
281 \membersection{wxList<T>::begin}\label{wxlistbegin}
283 \func{iterator}{begin}{\void}
285 \constfunc{const\_iterator}{begin}{\void}
287 Returns a (const) iterator pointing to the beginning of the list.
289 \membersection{wxList<T>::clear}\label{wxlistclear}
291 \func{void}{clear}{\void}
293 Removes all items from the list.
295 \membersection{wxList<T>::empty}\label{wxlistempty}
297 \constfunc{bool}{empty}{\void}
299 Returns {\it true} if the list is empty.
301 \membersection{wxList<T>::end}\label{wxlistend}
303 \func{iterator}{end}{\void}
305 \constfunc{const\_iterator}{end}{\void}
307 Returns a (const) iterator pointing at the end of the list.
309 \membersection{wxList<T>::erase}\label{wxlisterase2}
311 \func{iterator}{erase}{\param{const iterator\& }{it}}
313 Erases the item pointed to by {\it it}.
315 \func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}}
317 Erases the items from {\it first} to {\it last}.
319 \membersection{wxList<T>::front}\label{wxlistfront}
321 \func{reference}{front}{\void}
323 \constfunc{const\_reference}{front}{\void}
325 Returns the first item in the list.
327 \membersection{wxList<T>::insert}\label{wxlistinsert}
329 \func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}}
331 \func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}}
333 \func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}}
335 Inserts an item (or several) at the given position.
337 \membersection{wxList<T>::max\_size}\label{wxlistmax\_size}
339 \constfunc{size\_type}{max\_size}{\void}
341 Returns the largest possible size of the list.
343 \membersection{wxList<T>::pop\_back}\label{wxlistpop\_back}
345 \func{void}{pop\_back}{\void}
347 Removes the last item from the list.
349 \membersection{wxList<T>::pop\_front}\label{wxlistpop\_front}
351 \func{void}{pop\_front}{\void}
353 Removes the first item from the list.
355 \membersection{wxList<T>::push\_back}\label{wxlistpush\_back}
357 \func{void}{push\_back}{\param{const\_reference }{v = value\_type()}}
359 Adds an item to end of the list.
361 \membersection{wxList<T>::push\_front}\label{wxlistpush\_front}
363 \func{void}{push\_front}{\param{const\_reference }{v = value\_type()}}
365 Adds an item to the front of the list.
367 \membersection{wxList<T>::rbegin}\label{wxlistrbegin}
369 \func{reverse\_iterator}{rbegin}{\void}
371 \constfunc{const\_reverse\_iterator}{rbegin}{\void}
373 Returns a (const) reverse iterator pointing to the beginning of the
376 \membersection{wxList<T>::remove}\label{wxlistremove}
378 \func{void}{remove}{\param{const\_reference }{v}}
380 Removes an item from the list.
382 \membersection{wxList<T>::rend}\label{wxlistrend}
384 \func{reverse\_iterator}{rend}{\void}
386 \constfunc{const\_reverse\_iterator}{rend}{\void}
388 Returns a (const) reverse iterator pointing to the end of the
391 \membersection{wxList<T>::resize}\label{wxlistresize}
393 \func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}}
395 Resizes the list. If the the list is enlarges items with
396 the value {\it v} are appended to the list.
398 \membersection{wxList<T>::reverse}\label{wxlistreverse}
400 \func{void}{reverse}{\void}
404 \membersection{wxList<T>::size}\label{wxlistsize}
406 \constfunc{size\_type}{size}{\void}
408 Returns the size of the list.
410 \membersection{wxList<T>::splice}\label{wxlistsplice}
412 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}}
414 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}}
416 \func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}}
418 Moves part of the list into another list, starting from {\it first} and
419 ending at {\it last} if specified.