]>
Commit | Line | Data |
---|---|---|
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 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. | |
70 | ||
71 | In the documentation of the list classes below, you should replace wxNode with | |
72 | wxListName::Node and wxObject with the list element type (i.e. the first | |
73 | parameter of WX\_DECLARE\_LIST) for the template lists. | |
74 | ||
75 | \wxheading{Derived from} | |
76 | ||
77 | \helpref{wxObject}{wxobject} | |
78 | ||
79 | \wxheading{Include files} | |
80 | ||
81 | <wx/list.h> | |
82 | ||
83 | \wxheading{Example} | |
84 | ||
85 | It is very common to iterate on a list as follows: | |
86 | ||
87 | \begin{verbatim} | |
88 | ... | |
89 | wxWindow *win1 = new wxWindow(...); | |
90 | wxWindow *win2 = new wxWindow(...); | |
91 | ||
92 | wxList SomeList; | |
93 | SomeList.Append(win1); | |
94 | SomeList.Append(win2); | |
95 | ||
96 | ... | |
97 | ||
98 | wxNode *node = SomeList.GetFirst(); | |
99 | while (node) | |
100 | { | |
101 | wxWindow *win = node->GetData(); | |
102 | ... | |
103 | node = node->GetNext(); | |
104 | } | |
105 | \end{verbatim} | |
106 | ||
107 | To delete nodes in a list as the list is being traversed, replace | |
108 | ||
109 | \begin{verbatim} | |
110 | ... | |
111 | node = node->GetNext(); | |
112 | ... | |
113 | \end{verbatim} | |
114 | ||
115 | with | |
116 | ||
117 | \begin{verbatim} | |
118 | ... | |
119 | delete win; | |
120 | delete node; | |
121 | node = SomeList.GetFirst(); | |
122 | ... | |
123 | \end{verbatim} | |
124 | ||
125 | See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and | |
126 | members for getting to the next or previous node. | |
127 | ||
128 | \wxheading{See also} | |
129 | ||
130 | \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}, | |
131 | \helpref{wxArray}{wxarray} | |
132 | ||
133 | \latexignore{\rtfignore{\wxheading{Members}}} | |
134 | ||
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}\label{wxlistappend} | |
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}\label{wxlistclear} | |
175 | ||
176 | \func{void}{Clear}{\void} | |
177 | ||
178 | Clears the list (but does not delete the client data stored with each node | |
179 | unless you called DeleteContents(TRUE), in which case it deletes data). | |
180 | ||
181 | \membersection{wxList::DeleteContents}\label{wxlistdeletecontents} | |
182 | ||
183 | \func{void}{DeleteContents}{\param{bool}{ destroy}} | |
184 | ||
185 | If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of | |
186 | a node whenever the node is destroyed. The default is FALSE. | |
187 | ||
188 | \membersection{wxList::DeleteNode}\label{wxlistdeletenode} | |
189 | ||
190 | \func{bool}{DeleteNode}{\param{wxNode *}{node}} | |
191 | ||
192 | Deletes the given node from the list, returning TRUE if successful. | |
193 | ||
194 | \membersection{wxList::DeleteObject}\label{wxlistdeleteobject} | |
195 | ||
196 | \func{bool}{DeleteObject}{\param{wxObject *}{object}} | |
197 | ||
198 | Finds the given client {\it object} and deletes the appropriate node from the list, returning | |
199 | TRUE if successful. The application must delete the actual object separately. | |
200 | ||
201 | \membersection{wxList::Find}\label{wxlistfind} | |
202 | ||
203 | \func{wxNode *}{Find}{\param{long}{ key}} | |
204 | ||
205 | \func{wxNode *}{Find}{\param{const wxString\& }{key}} | |
206 | ||
207 | Returns the node whose stored key matches {\it key}. Use on a keyed list only. | |
208 | ||
209 | \membersection{wxList::GetCount}\label{wxlistgetcount} | |
210 | ||
211 | \constfunc{size\_t}{GetCount}{\void} | |
212 | ||
213 | Returns the number of elements in the list. | |
214 | ||
215 | \membersection{wxList::GetFirst}\label{wxlistgetfirst} | |
216 | ||
217 | \func{wxNode *}{GetFirst}{\void} | |
218 | ||
219 | Returns the first node in the list (NULL if the list is empty). | |
220 | ||
221 | \membersection{wxList::GetLast}\label{wxlistgetlast} | |
222 | ||
223 | \func{wxNode *}{GetLast}{\void} | |
224 | ||
225 | Returns the last node in the list (NULL if the list is empty). | |
226 | ||
227 | \membersection{wxList::IndexOf}\label{wxlistindexof} | |
228 | ||
229 | \func{int}{IndexOf}{\param{wxObject*}{ obj }} | |
230 | ||
231 | Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj} | |
232 | is not found in the list. | |
233 | ||
234 | \membersection{wxList::Insert}\label{wxlistinsert} | |
235 | ||
236 | \func{wxNode *}{Insert}{\param{wxObject *}{object}} | |
237 | ||
238 | Insert object at front of list. | |
239 | ||
240 | \func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{object}} | |
241 | ||
242 | Insert object before {\it position}, i.e. the index of the new item in the | |
243 | list will be equal to {\it position}. {\it position} should be less than or | |
244 | equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the | |
245 | same as calling \helpref{Append}{wxlistappend}. | |
246 | ||
247 | \func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{wxObject *}{object}} | |
248 | ||
249 | Inserts the object before the given {\it node}. | |
250 | ||
251 | \membersection{wxList::Item}\label{wxlistitem} | |
252 | ||
253 | \constfunc{wxNode *}{Item}{\param{size\_t }{index}} | |
254 | ||
255 | Returns the node at given position in the list. | |
256 | ||
257 | \membersection{wxList::Member}\label{wxlistmember} | |
258 | ||
259 | \func{wxNode *}{Member}{\param{wxObject *}{object}} | |
260 | ||
261 | {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. | |
262 | ||
263 | Returns the node associated with {\it object} if it is in the list, NULL otherwise. | |
264 | ||
265 | \membersection{wxList::Nth}\label{wxlistnth} | |
266 | ||
267 | \func{wxNode *}{Nth}{\param{int}{ n}} | |
268 | ||
269 | {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead. | |
270 | ||
271 | Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty | |
272 | or the nth node could not be found). | |
273 | ||
274 | \membersection{wxList::Number}\label{wxlistnumber} | |
275 | ||
276 | \func{int}{Number}{\void} | |
277 | ||
278 | {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead. | |
279 | ||
280 | Returns the number of elements in the list. | |
281 | ||
282 | \membersection{wxList::Sort}\label{wxlistsort} | |
283 | ||
284 | \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} | |
285 | ||
286 | \begin{verbatim} | |
287 | // Type of compare function for list sort operation (as in 'qsort') | |
288 | typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2); | |
289 | \end{verbatim} | |
290 | ||
291 | Allows the sorting of arbitrary lists by giving | |
292 | a function to compare two list elements. We use the system {\bf qsort} function | |
293 | for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **), | |
294 | so be careful to dereference appropriately. | |
295 | ||
296 | Example: | |
297 | ||
298 | \begin{verbatim} | |
299 | int listcompare(const void *arg1, const void *arg2) | |
300 | { | |
301 | return(compare(**(wxString **)arg1, // use the wxString 'compare' | |
302 | **(wxString **)arg2)); // function | |
303 | } | |
304 | ||
305 | void main() | |
306 | { | |
307 | wxList list; | |
308 | ||
309 | list.Append(new wxString("DEF")); | |
310 | list.Append(new wxString("GHI")); | |
311 | list.Append(new wxString("ABC")); | |
312 | list.Sort(listcompare); | |
313 | } | |
314 | \end{verbatim} | |
315 |