1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
<HTML>
<head><title>wxList</title></head>
<BODY BGCOLOR=#FFFFFF>
<A NAME="wxlist"></A><CENTER>
<A HREF="wx.htm"><img align=center src="contents.gif" BORDER=0 ALT="Contents"></A> <A HREF="wx22.htm#classref"><img align=center src="up.gif" BORDER=0 ALT="Up"></A> <A HREF="wx126.htm#wxlayoutconstraints"><img align=center src="back.gif" BORDER=0 ALT="Previous"></A> <A HREF="wx128.htm#wxlistbox"><img align=center src="forward.gif" BORDER=0 ALT="Next"></A> </CENTER><HR>
<H2>wxList</H2>
<P>
wxList classes provide linked list functionality for wxWindows, and for an
application if it wishes. Depending on the form of constructor used, a list
can be keyed on integer or string keys to provide a primitive look-up ability.
See <A HREF="wx110.htm#wxhashtable">wxHashTable</A> for a faster method of storage
when random access is required.<P>
While wxList class in the previous versions of wxWindows only could contain
elements of type wxObject and had essentially untyped interface (thus allowing
you to put apples in the list and read back oranges from it), the new wxList
classes family may contain elements of any type and has much more stricter type
checking. Unfortunately, it also requires an additional line to be inserted in
your program for each list class you use (which is the only solution short of
using templates which is not done in wxWindows because of portability issues).<P>
The general idea is to have the base class wxListBase working with <I>void *</I>
data but make all of its dangerous (because untyped) functions protected, so
that they can only be used from derived classes which, in turn, expose a type
safe interface. With this approach a new wxList-like class must be defined for
each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done
with <I>WX_DECLARE_LIST</I> and <I>WX_IMPLEMENT_LIST</I> macros like this
(notice the similarity with WX_DECLARE_OBJARRAY and WX_IMPLEMENT_OBJARRAY
macros):<P>
<B><FONT COLOR="#FF0000">Example</FONT></B><P>
<FONT SIZE=2><PRE>
// this part might be in a header or source (.cpp) file
class MyListElement
{
... // whatever
};
// declare our list class: this macro declares and partly implements MyList
// class (which derives from wxListBase)
WX_DECLARE_LIST(MyListElement, MyList)
...
// the only requirment for the rest is to be AFTER the full declaration of
// MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
// usually it will be found in the source file and not in the header
#include <wx/listimpl.cpp>
WX_DEFINE_LIST(MyList)
// now MyList class may be used as a usual wxList, but all of its methods
// will take/return the objects of the right (i.e. MyListElement) type. You
// also have MyList::Node type which is the type-safe version of wxNode.
MyList list;
MyListElement element;
list.Add(element); // ok
list.Add(17); // error: incorrect type
// let's iterate over the list
for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
{
MyListElement *current = node->GetData();
...process the current element...
}
</PRE>
</FONT><P>
For compatibility with previous versions wxList and wxStringList classes are
still defined, but their usage is deprecated and they will disappear in the
future versions completely.<P>
<B><FONT COLOR="#FF0000">Derived from</FONT></B><P>
<A HREF="wx158.htm#wxobject">wxObject</A><P>
<B><FONT COLOR="#FF0000">Include files</FONT></B><P>
<wx/list.h><P>
<B><FONT COLOR="#FF0000">Example</FONT></B><P>
It is very common to iterate on a list as follows:<P>
<PRE>
...
wxWindow *win1 = new wxWindow(...);
wxWindow *win2 = new wxWindow(...);
wxList SomeList;
SomeList.Append(win1);
SomeList.Append(win2);
...
wxNode *node = SomeList.GetFirst();
while (node)
{
wxWindow *win = (wxWindow *)node->Data();
...
node = node->Next();
}
</PRE>
To delete nodes in a list as the list is being traversed, replace<P>
<PRE>
...
node = node->Next();
...
</PRE>
with<P>
<PRE>
...
delete win;
delete node;
node = SomeList.GetFirst();
...
</PRE>
See <A HREF="wx155.htm#wxnode">wxNode</A> for members that retrieve the data associated with a node, and
members for getting to the next or previous node.<P>
Note that a cast is required when retrieving the data from a node. Although a
node is defined to store objects of type <B>wxObject</B> and derived types, other
types (such as char*) may be used with appropriate casting.<P>
<B><FONT COLOR="#FF0000">See also</FONT></B><P>
<A HREF="wx155.htm#wxnode">wxNode</A>, <A HREF="wx225.htm#wxstringlist">wxStringList</A>,
<A HREF="wx27.htm#wxarray">wxArray</A><P>
<B><FONT COLOR="#FF0000">Members</FONT></B><P>
<A HREF="#topic522">wxList::wxList</A><BR>
<A HREF="#topic523">wxList::~wxList</A><BR>
<A HREF="#topic524">wxList::Append</A><BR>
<A HREF="#topic525">wxList::Clear</A><BR>
<A HREF="#wxlistdeletecontents">wxList::DeleteContents</A><BR>
<A HREF="#topic526">wxList::DeleteNode</A><BR>
<A HREF="#topic527">wxList::DeleteObject</A><BR>
<A HREF="#topic528">wxList::Find</A><BR>
<A HREF="#topic529">wxList::GetFirst</A><BR>
<A HREF="#topic530">wxList::IndexOf</A><BR>
<A HREF="#topic531">wxList::Insert</A><BR>
<A HREF="#topic532">wxList::GetLast</A><BR>
<A HREF="#topic533">wxList::Member</A><BR>
<A HREF="#topic534">wxList::Nth</A><BR>
<A HREF="#topic535">wxList::Number</A><BR>
<A HREF="#topic536">wxList::Sort</A><BR>
<P>
<HR>
<A NAME="topic522"></A>
<H3>wxList::wxList</H3>
<P>
<B></B> <B>wxList</B>()<P>
<B></B> <B>wxList</B>(<B>unsigned int</B><I> key_type</I>)<P>
<B></B> <B>wxList</B>(<B>int</B><I> n</I>, <B>wxObject *</B><I>objects[]</I>)<P>
<B></B> <B>wxList</B>(<B>wxObject *</B><I>object</I>, ...)<P>
Constructors. <I>key_type</I> is one of wxKEY_NONE, wxKEY_INTEGER, or wxKEY_STRING,
and indicates what sort of keying is required (if any).<P>
<I>objects</I> is an array of <I>n</I> objects with which to initialize the list.<P>
The variable-length argument list constructor must be supplied with a
terminating NULL.<P>
<HR>
<A NAME="topic523"></A>
<H3>wxList::~wxList</H3>
<P>
<B></B> <B>~wxList</B>()<P>
Destroys the list. Also destroys any remaining nodes, but does not destroy
client data held in the nodes.<P>
<HR>
<A NAME="topic524"></A>
<H3>wxList::Append</H3>
<P>
<B>wxNode *</B> <B>Append</B>(<B>wxObject *</B><I>object</I>)<P>
<B>wxNode *</B> <B>Append</B>(<B>long</B><I> key</I>, <B>wxObject *</B><I>object</I>)<P>
<B>wxNode *</B> <B>Append</B>(<B>const wxString& </B><I>key</I>, <B>wxObject *</B><I>object</I>)<P>
Appends a new <B>wxNode</B> to the end of the list and puts a pointer to the
<I>object</I> in the node. The last two forms store a key with the object for
later retrieval using the key. The new node is returned in each case.<P>
The key string is copied and stored by the list implementation.<P>
<HR>
<A NAME="topic525"></A>
<H3>wxList::Clear</H3>
<P>
<B>void</B> <B>Clear</B>()<P>
Clears the list (but does not delete the client data stored with each node).<P>
<HR>
<A NAME="wxlistdeletecontents"></A>
<H3>wxList::DeleteContents</H3>
<P>
<B>void</B> <B>DeleteContents</B>(<B>bool</B><I> destroy</I>)<P>
If <I>destroy</I> is TRUE, instructs the list to call <I>delete</I> on the client contents of
a node whenever the node is destroyed. The default is FALSE.<P>
<HR>
<A NAME="topic526"></A>
<H3>wxList::DeleteNode</H3>
<P>
<B>bool</B> <B>DeleteNode</B>(<B>wxNode *</B><I>node</I>)<P>
Deletes the given node from the list, returning TRUE if successful.<P>
<HR>
<A NAME="topic527"></A>
<H3>wxList::DeleteObject</H3>
<P>
<B>bool</B> <B>DeleteObject</B>(<B>wxObject *</B><I>object</I>)<P>
Finds the given client <I>object</I> and deletes the appropriate node from the list, returning
TRUE if successful. The application must delete the actual object separately.<P>
<HR>
<A NAME="topic528"></A>
<H3>wxList::Find</H3>
<P>
<B>wxNode *</B> <B>Find</B>(<B>long</B><I> key</I>)<P>
<B>wxNode *</B> <B>Find</B>(<B>const wxString& </B><I>key</I>)<P>
Returns the node whose stored key matches <I>key</I>. Use on a keyed list only.<P>
<HR>
<A NAME="topic529"></A>
<H3>wxList::GetFirst</H3>
<P>
<B>wxNode *</B> <B>GetFirst</B>()<P>
Returns the first node in the list (NULL if the list is empty).<P>
<HR>
<A NAME="topic530"></A>
<H3>wxList::IndexOf</H3>
<P>
<B>int</B> <B>IndexOf</B>(<B>wxObject*</B><I> obj </I>)<P>
Returns the index of <I>obj</I> within the list or NOT_FOUND if <I>obj</I>
is not found in the list.<P>
<HR>
<A NAME="topic531"></A>
<H3>wxList::Insert</H3>
<P>
<B>wxNode *</B> <B>Insert</B>(<B>wxObject *</B><I>object</I>)<P>
Insert object at front of list.<P>
<B>wxNode *</B> <B>Insert</B>(<B>wxNode *</B><I>position</I>, <B>wxObject *</B><I>object</I>)<P>
Insert object before <I>position</I>.<P>
<HR>
<A NAME="topic532"></A>
<H3>wxList::GetLast</H3>
<P>
<B>wxNode *</B> <B>GetLast</B>()<P>
Returns the last node in the list (NULL if the list is empty).<P>
<HR>
<A NAME="topic533"></A>
<H3>wxList::Member</H3>
<P>
<B>wxNode *</B> <B>Member</B>(<B>wxObject *</B><I>object</I>)<P>
Returns the node associated with <I>object</I> if it is in the list, NULL otherwise.<P>
<HR>
<A NAME="topic534"></A>
<H3>wxList::Nth</H3>
<P>
<B>wxNode *</B> <B>Nth</B>(<B>int</B><I> n</I>)<P>
Returns the <I>nth</I> node in the list, indexing from zero (NULL if the list is empty
or the nth node could not be found).<P>
<HR>
<A NAME="topic535"></A>
<H3>wxList::Number</H3>
<P>
<B>int</B> <B>Number</B>()<P>
Returns the number of elements in the list.<P>
<HR>
<A NAME="topic536"></A>
<H3>wxList::Sort</H3>
<P>
<B>void</B> <B>Sort</B>(<B>wxSortCompareFunction</B><I> compfunc</I>)<P>
<PRE>
// Type of compare function for list sort operation (as in 'qsort')
typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
</PRE>
Allows the sorting of arbitrary lists by giving
a function to compare two list elements. We use the system <B>qsort</B> function
for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **),
so be careful to dereference appropriately.<P>
Example:<P>
<PRE>
int listcompare(const void *arg1, const void *arg2)
{
return(compare(**(wxString **)arg1, // use the wxString 'compare'
**(wxString **)arg2)); // function
}
void main()
{
wxList list;
list.Append(new wxString("DEF"));
list.Append(new wxString("GHI"));
list.Append(new wxString("ABC"));
list.Sort(listcompare);
}
</PRE>
</BODY></HTML>
|
