]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/list.tex
don't crash when setting tooltip for a picker without text control
[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}}\label{wxlist}
13
14 wxList classes provide linked list functionality for wxWidgets, and for an
15 application if it wishes. Depending on the form of constructor used, a list
16 can be keyed on integer or string keys to provide a primitive look-up ability,
17 but please note that this feature is {\bf deprecated}.
18 See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage
19 when random access is required.
20
21 While wxList class in the previous versions of wxWidgets only could contain
22 elements of type wxObject and had essentially untyped interface (thus allowing
23 you to put apples in the list and read back oranges from it), the new wxList
24 classes family may contain elements of any type and has much more strict type
25 checking. Unfortunately, it also requires an additional line to be inserted in
26 your program for each list class you use (which is the only solution short of
27 using templates which is not done in wxWidgets because of portability issues).
28
29 The general idea is to have the base class wxListBase working with {\it void *}
30 data but make all of its dangerous (because untyped) functions protected, so
31 that they can only be used from derived classes which, in turn, expose a type
32 safe interface. With this approach a new wxList-like class must be defined for
33 each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done
34 with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this
35 (notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
36 macros):
37
38 \wxheading{Example}
39
40 \begin{verbatim}
41 // this part might be in a header or source (.cpp) file
42 class MyListElement
43 {
44 ... // whatever
45 };
46
47 // declare our list class: this macro declares and partly implements MyList
48 // class (which derives from wxListBase)
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 // now MyList class may be used as a usual wxList, but all of its methods
61 // will take/return the objects of the right (i.e. MyListElement) type. You
62 // also have MyList::Node type which is the type-safe version of wxNode.
63 MyList list;
64 MyListElement element;
65 list.Append(&element); // ok
66 list.Append(17); // error: incorrect type
67
68 // let's iterate over the list
69 for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
70 {
71 MyListElement *current = node->GetData();
72
73 ...process the current element...
74 }
75 \end{verbatim}
76
77 For compatibility with previous versions wxList and wxStringList classes are
78 still defined, but their usage is deprecated and they will disappear in the
79 future versions completely. The use of the latter is especially discouraged as
80 it is not only unsafe but is also much less efficient than
81 \helpref{wxArrayString}{wxarraystring} class.
82
83 In the documentation of the list classes below, the template notations are
84 used even though these classes are not really templates at all -- but it helps
85 to think about them as if they were. You should replace wxNode<T> with
86 wxListName::Node and T itself with the list element type (i.e. the first
87 parameter of WX\_DECLARE\_LIST).
88
89 \wxheading{Derived from}
90
91 \helpref{wxObject}{wxobject}
92
93 \wxheading{Include files}
94
95 <wx/list.h>
96
97 \wxheading{Example}
98
99 It is very common to iterate on a list as follows:
100
101 \begin{verbatim}
102 ...
103 wxWindow *win1 = new wxWindow(...);
104 wxWindow *win2 = new wxWindow(...);
105
106 wxList SomeList;
107 SomeList.Append(win1);
108 SomeList.Append(win2);
109
110 ...
111
112 wxNode *node = SomeList.GetFirst();
113 while (node)
114 {
115 wxWindow *win = node->GetData();
116 ...
117 node = node->GetNext();
118 }
119 \end{verbatim}
120
121 To delete nodes in a list as the list is being traversed, replace
122
123 \begin{verbatim}
124 ...
125 node = node->GetNext();
126 ...
127 \end{verbatim}
128
129 with
130
131 \begin{verbatim}
132 ...
133 delete win;
134 delete node;
135 node = SomeList.GetFirst();
136 ...
137 \end{verbatim}
138
139 See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
140 members for getting to the next or previous node.
141
142 \wxheading{See also}
143
144 \helpref{wxNode}{wxnode},
145 \helpref{wxArray}{wxarray}
146
147 \latexignore{\rtfignore{\wxheading{Members}}}
148
149 \membersection{wxList::wxList}\label{wxlistctor}
150
151 \func{}{wxList}{\void}
152
153 \func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}}
154
155 \func{}{wxList}{\param{T *}{object}, ...}
156
157 {\bf Note}: keyed lists are deprecated and should not be used in new code.
158
159 \func{}{wxList}{\param{unsigned int}{ key\_type}}
160
161 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
162 and indicates what sort of keying is required (if any).
163
164 {\it objects} is an array of {\it n} objects with which to initialize the list.
165
166 The variable-length argument list constructor must be supplied with a
167 terminating NULL.
168
169 \membersection{wxList::\destruct{wxList}}\label{wxlistdtor}
170
171 \func{}{\destruct{wxList}}{\void}
172
173 Destroys the list. Also destroys any remaining nodes, but does not destroy
174 client data held in the nodes.
175
176 \membersection{wxList::Append}\label{wxlistappend}
177
178 \func{wxNode<T> *}{Append}{\param{T *}{object}}
179
180 {\bf Note}: keyed lists are deprecated and should not be used in new code.
181
182 \func{wxNode<T> *}{Append}{\param{long}{ key}, \param{T *}{object}}
183
184 \func{wxNode<T> *}{Append}{\param{const wxString\& }{key}, \param{T *}{object}}
185
186 Appends a new \helpref{wxNode}{wxnode} to the end of the list and puts a
187 pointer to the \rtfsp{\it object} in the node. The last two forms store a key
188 with the object for later retrieval using the key. The new node is returned in
189 each case.
190
191 The key string is copied and stored by the list implementation.
192
193 \membersection{wxList::Clear}\label{wxlistclear}
194
195 \func{void}{Clear}{\void}
196
197 Clears the list (but does not delete the client data stored with each node
198 unless you called DeleteContents({\tt true}), in which case it deletes data).
199
200 \membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
201
202 \func{void}{DeleteContents}{\param{bool}{ destroy}}
203
204 If {\it destroy} is {\tt true}, instructs the list to call {\it delete} on the client contents of
205 a node whenever the node is destroyed. The default is {\tt false}.
206
207 \membersection{wxList::DeleteNode}\label{wxlistdeletenode}
208
209 \func{bool}{DeleteNode}{\param{wxNode<T> *}{node}}
210
211 Deletes the given node from the list, returning {\tt true} if successful.
212
213 \membersection{wxList::DeleteObject}\label{wxlistdeleteobject}
214
215 \func{bool}{DeleteObject}{\param{T *}{object}}
216
217 Finds the given client {\it object} and deletes the appropriate node from the list, returning
218 {\tt true} if successful. The application must delete the actual object separately.
219
220 \membersection{wxList::Erase}\label{wxlisterase}
221
222 \func{void}{Erase}{\param{wxNode<T> *}{node}}
223
224 Removes element at given position.
225
226 \membersection{wxList::Find}\label{wxlistfind}
227
228 \func{wxNode<T> *}{Find}{\param{T *}{ object}}
229
230 Returns the node whose client data is {\it object} or NULL if none found.
231
232 {\bf Note}: keyed lists are deprecated and should not be used in new code.
233
234 \func{wxNode<T> *}{Find}{\param{long}{ key}}
235
236 \func{wxNode<T> *}{Find}{\param{const wxString\& }{key}}
237
238 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
239
240 \membersection{wxList::GetCount}\label{wxlistgetcount}
241
242 \constfunc{size\_t}{GetCount}{\void}
243
244 Returns the number of elements in the list.
245
246 \membersection{wxList::GetFirst}\label{wxlistgetfirst}
247
248 \func{wxNode<T> *}{GetFirst}{\void}
249
250 Returns the first node in the list (NULL if the list is empty).
251
252 \membersection{wxList::GetLast}\label{wxlistgetlast}
253
254 \func{wxNode<T> *}{GetLast}{\void}
255
256 Returns the last node in the list (NULL if the list is empty).
257
258 \membersection{wxList::IndexOf}\label{wxlistindexof}
259
260 \func{int}{IndexOf}{\param{T*}{ obj }}
261
262 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if {\it obj}
263 is not found in the list.
264
265 \membersection{wxList::Insert}\label{wxlistinsert}
266
267 \func{wxNode<T> *}{Insert}{\param{T *}{object}}
268
269 Insert object at front of list.
270
271 \func{wxNode<T> *}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
272
273 Insert object before {\it position}, i.e. the index of the new item in the
274 list will be equal to {\it position}. {\it position} should be less than or
275 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
276 same as calling \helpref{Append}{wxlistappend}.
277
278 \func{wxNode<T> *}{Insert}{\param{wxNode<T> *}{node}, \param{T *}{object}}
279
280 Inserts the object before the given {\it node}.
281
282 \membersection{wxList::IsEmpty}\label{wxlistisempty}
283
284 \constfunc{bool}{IsEmpty}{\void}
285
286 Returns {\tt true} if the list is empty, {\tt false} otherwise.
287
288 % Use different label name to avoid clashing with wxListItem label
289 \membersection{wxList::Item}\label{wxlistitemfunc}
290
291 \constfunc{wxNode<T> *}{Item}{\param{size\_t }{index}}
292
293 Returns the node at given position in the list.
294
295 \membersection{wxList::Member}\label{wxlistmember}
296
297 \func{wxNode<T> *}{Member}{\param{T *}{object}}
298
299 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
300
301 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
302
303 \membersection{wxList::Nth}\label{wxlistnth}
304
305 \func{wxNode<T> *}{Nth}{\param{int}{ n}}
306
307 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
308
309 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
310 or the nth node could not be found).
311
312 \membersection{wxList::Number}\label{wxlistnumber}
313
314 \func{int}{Number}{\void}
315
316 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
317
318 Returns the number of elements in the list.
319
320 \membersection{wxList::Sort}\label{wxlistsort}
321
322 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
323
324 \begin{verbatim}
325 // Type of compare function for list sort operation (as in 'qsort')
326 typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
327 \end{verbatim}
328
329 Allows the sorting of arbitrary lists by giving
330 a function to compare two list elements. We use the system {\bf qsort} function
331 for the actual sorting process.
332
333 If you use untyped wxList the sort function receives pointers to wxObject
334 pointers (wxObject **), so be careful to dereference appropriately - but,
335 of course, a better solution is to use list of appropriate type defined with
336 {\tt WX\_DECLARE\_LIST}.
337
338 Example:
339
340 \begin{verbatim}
341 int listcompare(const void *arg1, const void *arg2)
342 {
343 return(compare(**(wxString **)arg1, // use the wxString 'compare'
344 **(wxString **)arg2)); // function
345 }
346
347 void main()
348 {
349 wxList list;
350
351 list.Append(new wxString("DEF"));
352 list.Append(new wxString("GHI"));
353 list.Append(new wxString("ABC"));
354 list.Sort(listcompare);
355 }
356 \end{verbatim}