]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \section{\class{wxList}}\label{wxlist} |
2 | ||
6e6110ee VZ |
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 stricter 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\_IMPLEMENT\_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.Add(element); // ok | |
55 | list.Add(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. | |
a660d684 KB |
70 | |
71 | \wxheading{Derived from} | |
72 | ||
73 | \helpref{wxObject}{wxobject} | |
74 | ||
954b8ae6 JS |
75 | \wxheading{Include files} |
76 | ||
77 | <wx/list.h> | |
78 | ||
a660d684 KB |
79 | \wxheading{Example} |
80 | ||
81 | It is very common to iterate on a list as follows: | |
82 | ||
83 | \begin{verbatim} | |
84 | ... | |
9838df2c JS |
85 | wxWindow *win1 = new wxWindow(...); |
86 | wxWindow *win2 = new wxWindow(...); | |
a660d684 KB |
87 | |
88 | wxList SomeList; | |
9838df2c JS |
89 | SomeList.Append(win1); |
90 | SomeList.Append(win2); | |
a660d684 KB |
91 | |
92 | ... | |
93 | ||
f3a65071 | 94 | wxNode *node = SomeList.GetFirst(); |
a660d684 KB |
95 | while (node) |
96 | { | |
9838df2c | 97 | wxWindow *win = (wxWindow *)node->Data(); |
a660d684 KB |
98 | ... |
99 | node = node->Next(); | |
100 | } | |
101 | \end{verbatim} | |
102 | ||
103 | To delete nodes in a list as the list is being traversed, replace | |
104 | ||
105 | \begin{verbatim} | |
106 | ... | |
107 | node = node->Next(); | |
108 | ... | |
109 | \end{verbatim} | |
110 | ||
111 | with | |
112 | ||
113 | \begin{verbatim} | |
114 | ... | |
9838df2c | 115 | delete win; |
a660d684 | 116 | delete node; |
f3a65071 | 117 | node = SomeList.GetFirst(); |
a660d684 KB |
118 | ... |
119 | \end{verbatim} | |
120 | ||
121 | See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and | |
122 | members for getting to the next or previous node. | |
123 | ||
124 | Note that a cast is required when retrieving the data from a node. Although a | |
125 | node is defined to store objects of type {\bf wxObject} and derived types, other | |
126 | types (such as char*) may be used with appropriate casting. | |
127 | ||
128 | \wxheading{See also} | |
129 | ||
6e6110ee VZ |
130 | \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}, |
131 | \helpref{wxArray}{wxarray} | |
a660d684 KB |
132 | |
133 | \latexignore{\rtfignore{\wxheading{Members}}} | |
134 | ||
a660d684 KB |
135 | \membersection{wxList::wxList} |
136 | ||
137 | \func{}{wxList}{\void} | |
138 | ||
139 | \func{}{wxList}{\param{unsigned int}{ key\_type}} | |
140 | ||
141 | \func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}} | |
142 | ||
143 | \func{}{wxList}{\param{wxObject *}{object}, ...} | |
144 | ||
145 | Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, | |
146 | and indicates what sort of keying is required (if any). | |
147 | ||
148 | {\it objects} is an array of {\it n} objects with which to initialize the list. | |
149 | ||
150 | The variable-length argument list constructor must be supplied with a | |
151 | terminating NULL. | |
152 | ||
153 | \membersection{wxList::\destruct{wxList}} | |
154 | ||
155 | \func{}{\destruct{wxList}}{\void} | |
156 | ||
157 | Destroys the list. Also destroys any remaining nodes, but does not destroy | |
158 | client data held in the nodes. | |
159 | ||
160 | \membersection{wxList::Append} | |
161 | ||
162 | \func{wxNode *}{Append}{\param{wxObject *}{object}} | |
163 | ||
164 | \func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}} | |
165 | ||
166 | \func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}} | |
167 | ||
168 | Appends a new {\bf wxNode} to the end of the list and puts a pointer to the | |
169 | \rtfsp{\it object} in the node. The last two forms store a key with the object for | |
170 | later retrieval using the key. The new node is returned in each case. | |
171 | ||
172 | The key string is copied and stored by the list implementation. | |
173 | ||
174 | \membersection{wxList::Clear} | |
175 | ||
176 | \func{void}{Clear}{\void} | |
177 | ||
178 | Clears the list (but does not delete the client data stored with each node). | |
179 | ||
6be663cf | 180 | \membersection{wxList::DeleteContents}\label{wxlistdeletecontents} |
a660d684 KB |
181 | |
182 | \func{void}{DeleteContents}{\param{bool}{ destroy}} | |
183 | ||
184 | If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of | |
185 | a node whenever the node is destroyed. The default is FALSE. | |
186 | ||
187 | \membersection{wxList::DeleteNode} | |
188 | ||
189 | \func{bool}{DeleteNode}{\param{wxNode *}{node}} | |
190 | ||
191 | Deletes the given node from the list, returning TRUE if successful. | |
192 | ||
193 | \membersection{wxList::DeleteObject} | |
194 | ||
195 | \func{bool}{DeleteObject}{\param{wxObject *}{object}} | |
196 | ||
197 | Finds the given client {\it object} and deletes the appropriate node from the list, returning | |
198 | TRUE if successful. The application must delete the actual object separately. | |
199 | ||
200 | \membersection{wxList::Find} | |
201 | ||
202 | \func{wxNode *}{Find}{\param{long}{ key}} | |
203 | ||
204 | \func{wxNode *}{Find}{\param{const wxString\& }{key}} | |
205 | ||
206 | Returns the node whose stored key matches {\it key}. Use on a keyed list only. | |
207 | ||
f3a65071 | 208 | \membersection{wxList::GetFirst} |
a660d684 | 209 | |
f3a65071 | 210 | \func{wxNode *}{GetFirst}{\void} |
a660d684 KB |
211 | |
212 | Returns the first node in the list (NULL if the list is empty). | |
213 | ||
77c5eefb VZ |
214 | \membersection{wxList::IndexOf} |
215 | ||
216 | \func{int}{IndexOf}{\param{wxObject*}{ obj }} | |
217 | ||
f3339684 | 218 | Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} |
77c5eefb VZ |
219 | is not found in the list. |
220 | ||
a660d684 KB |
221 | \membersection{wxList::Insert} |
222 | ||
223 | \func{wxNode *}{Insert}{\param{wxObject *}{object}} | |
224 | ||
225 | Insert object at front of list. | |
226 | ||
227 | \func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}} | |
228 | ||
229 | Insert object before {\it position}. | |
230 | ||
231 | ||
f3a65071 | 232 | \membersection{wxList::GetLast} |
a660d684 | 233 | |
f3a65071 | 234 | \func{wxNode *}{GetLast}{\void} |
a660d684 KB |
235 | |
236 | Returns the last node in the list (NULL if the list is empty). | |
237 | ||
238 | \membersection{wxList::Member} | |
239 | ||
240 | \func{wxNode *}{Member}{\param{wxObject *}{object}} | |
241 | ||
242 | Returns the node associated with {\it object} if it is in the list, NULL otherwise. | |
243 | ||
244 | \membersection{wxList::Nth} | |
245 | ||
246 | \func{wxNode *}{Nth}{\param{int}{ n}} | |
247 | ||
248 | Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty | |
249 | or the nth node could not be found). | |
250 | ||
251 | \membersection{wxList::Number} | |
252 | ||
253 | \func{int}{Number}{\void} | |
254 | ||
255 | Returns the number of elements in the list. | |
256 | ||
257 | \membersection{wxList::Sort} | |
258 | ||
259 | \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} | |
260 | ||
261 | \begin{verbatim} | |
262 | // Type of compare function for list sort operation (as in 'qsort') | |
263 | typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2); | |
264 | \end{verbatim} | |
265 | ||
266 | Allows the sorting of arbitrary lists by giving | |
267 | a function to compare two list elements. We use the system {\bf qsort} function | |
268 | for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **), | |
269 | so be careful to dereference appropriately. | |
270 | ||
271 | Example: | |
272 | ||
273 | \begin{verbatim} | |
274 | int listcompare(const void *arg1, const void *arg2) | |
275 | { | |
276 | return(compare(**(wxString **)arg1, // use the wxString 'compare' | |
277 | **(wxString **)arg2)); // function | |
278 | } | |
279 | ||
280 | void main() | |
281 | { | |
282 | wxList list; | |
283 | ||
284 | list.Append(new wxString("DEF")); | |
285 | list.Append(new wxString("GHI")); | |
286 | list.Append(new wxString("ABC")); | |
287 | list.Sort(listcompare); | |
288 | } | |
289 | \end{verbatim} | |
290 | ||
291 |