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