]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/list.tex
added wxFileName::MakeRelativeTo() and the tests/docs for it
[wxWidgets.git] / docs / latex / wx / list.tex
CommitLineData
a660d684
KB
1\section{\class{wxList}}\label{wxlist}
2
6e6110ee
VZ
3wxList classes provide linked list functionality for wxWindows, and for an
4application if it wishes. Depending on the form of constructor used, a list
5can be keyed on integer or string keys to provide a primitive look-up ability.
6See \helpref{wxHashTable}{wxhashtable}\rtfsp for a faster method of storage
7when random access is required.
8
9While wxList class in the previous versions of wxWindows only could contain
10elements of type wxObject and had essentially untyped interface (thus allowing
11you to put apples in the list and read back oranges from it), the new wxList
5442f435 12classes family may contain elements of any type and has much more strict type
6e6110ee
VZ
13checking. Unfortunately, it also requires an additional line to be inserted in
14your program for each list class you use (which is the only solution short of
15using templates which is not done in wxWindows because of portability issues).
16
17The general idea is to have the base class wxListBase working with {\it void *}
18data but make all of its dangerous (because untyped) functions protected, so
19that they can only be used from derived classes which, in turn, expose a type
20safe interface. With this approach a new wxList-like class must be defined for
21each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done
bb250157 22with {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} macros like this
6e6110ee
VZ
23(notice the similarity with WX\_DECLARE\_OBJARRAY and WX\_IMPLEMENT\_OBJARRAY
24macros):
25
26\wxheading{Example}
27
6e6110ee
VZ
28\begin{verbatim}
29 // this part might be in a header or source (.cpp) file
30 class MyListElement
31 {
32 ... // whatever
33 };
34
35 // declare our list class: this macro declares and partly implements MyList
36 // class (which derives from wxListBase)
f776e250 37 WX_DECLARE_LIST(MyListElement, MyList);
6e6110ee
VZ
38
39 ...
40
41 // the only requirment for the rest is to be AFTER the full declaration of
42 // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
43 // usually it will be found in the source file and not in the header
44
45 #include <wx/listimpl.cpp>
f776e250 46 WX_DEFINE_LIST(MyList);
6e6110ee
VZ
47
48 // now MyList class may be used as a usual wxList, but all of its methods
49 // will take/return the objects of the right (i.e. MyListElement) type. You
50 // also have MyList::Node type which is the type-safe version of wxNode.
51 MyList list;
52 MyListElement element;
bb250157
VZ
53 list.Append(element); // ok
54 list.Append(17); // error: incorrect type
6e6110ee
VZ
55
56 // let's iterate over the list
57 for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
58 {
59 MyListElement *current = node->GetData();
60
61 ...process the current element...
62 }
63\end{verbatim}
6e6110ee
VZ
64
65For compatibility with previous versions wxList and wxStringList classes are
66still defined, but their usage is deprecated and they will disappear in the
703f03c3
VZ
67future versions completely. The use of the latter is especially discouraged as
68it is not only unsafe but is also much less efficient than
35d367d8 69\helpref{wxArrayString}{wxarraystring} class.
a660d684 70
d8996187
VZ
71In the documentation of the list classes below, you should replace wxNode with
72wxListName::Node and wxObject with the list element type (i.e. the first
73parameter of WX\_DECLARE\_LIST) for the template lists.
74
a660d684
KB
75\wxheading{Derived from}
76
77\helpref{wxObject}{wxobject}
78
954b8ae6
JS
79\wxheading{Include files}
80
81<wx/list.h>
82
a660d684
KB
83\wxheading{Example}
84
85It is very common to iterate on a list as follows:
86
87\begin{verbatim}
88 ...
9838df2c
JS
89 wxWindow *win1 = new wxWindow(...);
90 wxWindow *win2 = new wxWindow(...);
a660d684
KB
91
92 wxList SomeList;
9838df2c
JS
93 SomeList.Append(win1);
94 SomeList.Append(win2);
a660d684
KB
95
96 ...
97
f3a65071 98 wxNode *node = SomeList.GetFirst();
a660d684
KB
99 while (node)
100 {
d8996187 101 wxWindow *win = node->GetData();
a660d684 102 ...
d8996187 103 node = node->GetNext();
a660d684
KB
104 }
105\end{verbatim}
106
107To delete nodes in a list as the list is being traversed, replace
108
109\begin{verbatim}
110 ...
d8996187 111 node = node->GetNext();
a660d684
KB
112 ...
113\end{verbatim}
114
115with
116
117\begin{verbatim}
118 ...
9838df2c 119 delete win;
a660d684 120 delete node;
f3a65071 121 node = SomeList.GetFirst();
a660d684
KB
122 ...
123\end{verbatim}
124
125See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
126members for getting to the next or previous node.
127
a660d684
KB
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
145Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
146and 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
150The variable-length argument list constructor must be supplied with a
151terminating NULL.
152
153\membersection{wxList::\destruct{wxList}}
154
155\func{}{\destruct{wxList}}{\void}
156
157Destroys the list. Also destroys any remaining nodes, but does not destroy
158client data held in the nodes.
159
e12be2f7 160\membersection{wxList::Append}\label{wxlistappend}
a660d684
KB
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
168Appends 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
170later retrieval using the key. The new node is returned in each case.
171
172The key string is copied and stored by the list implementation.
173
e12be2f7 174\membersection{wxList::Clear}\label{wxlistclear}
a660d684
KB
175
176\func{void}{Clear}{\void}
177
ba9f095e
VS
178Clears the list (but does not delete the client data stored with each node
179unless you called DeleteContents(TRUE), in which case it deletes data).
a660d684 180
6be663cf 181\membersection{wxList::DeleteContents}\label{wxlistdeletecontents}
a660d684
KB
182
183\func{void}{DeleteContents}{\param{bool}{ destroy}}
184
185If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
186a node whenever the node is destroyed. The default is FALSE.
187
e12be2f7 188\membersection{wxList::DeleteNode}\label{wxlistdeletenode}
a660d684
KB
189
190\func{bool}{DeleteNode}{\param{wxNode *}{node}}
191
192Deletes the given node from the list, returning TRUE if successful.
193
e12be2f7 194\membersection{wxList::DeleteObject}\label{wxlistdeleteobject}
a660d684
KB
195
196\func{bool}{DeleteObject}{\param{wxObject *}{object}}
197
198Finds the given client {\it object} and deletes the appropriate node from the list, returning
199TRUE if successful. The application must delete the actual object separately.
200
e12be2f7 201\membersection{wxList::Find}\label{wxlistfind}
a660d684
KB
202
203\func{wxNode *}{Find}{\param{long}{ key}}
204
205\func{wxNode *}{Find}{\param{const wxString\& }{key}}
206
207Returns the node whose stored key matches {\it key}. Use on a keyed list only.
208
d8996187
VZ
209\membersection{wxList::GetCount}\label{wxlistgetcount}
210
211\constfunc{size\_t}{GetCount}{\void}
212
213Returns the number of elements in the list.
214
e12be2f7 215\membersection{wxList::GetFirst}\label{wxlistgetfirst}
a660d684 216
f3a65071 217\func{wxNode *}{GetFirst}{\void}
a660d684
KB
218
219Returns the first node in the list (NULL if the list is empty).
220
e12be2f7 221\membersection{wxList::GetLast}\label{wxlistgetlast}
d8996187
VZ
222
223\func{wxNode *}{GetLast}{\void}
224
225Returns the last node in the list (NULL if the list is empty).
226
e12be2f7 227\membersection{wxList::IndexOf}\label{wxlistindexof}
77c5eefb
VZ
228
229\func{int}{IndexOf}{\param{wxObject*}{ obj }}
230
cd4915e2 231Returns the index of {\it obj} within the list or wxNOT\_FOUND if {\it obj}
77c5eefb
VZ
232is not found in the list.
233
e12be2f7 234\membersection{wxList::Insert}\label{wxlistinsert}
a660d684
KB
235
236\func{wxNode *}{Insert}{\param{wxObject *}{object}}
237
238Insert object at front of list.
239
d8996187 240\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{object}}
a660d684 241
d8996187
VZ
242Insert object before {\it position}, i.e. the index of the new item in the
243list will be equal to {\it position}. {\it position} should be less than or
244equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
245same as calling \helpref{Append}{wxlistappend}.
a660d684 246
d8996187 247\func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{wxObject *}{object}}
a660d684 248
d8996187 249Inserts the object before the given {\it node}.
a660d684 250
d8996187 251\membersection{wxList::Item}\label{wxlistitem}
a660d684 252
d8996187
VZ
253\constfunc{wxNode *}{Item}{\param{size\_t }{index}}
254
255Returns the node at given position in the list.
a660d684 256
e12be2f7 257\membersection{wxList::Member}\label{wxlistmember}
a660d684
KB
258
259\func{wxNode *}{Member}{\param{wxObject *}{object}}
260
d8996187
VZ
261{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
262
a660d684
KB
263Returns the node associated with {\it object} if it is in the list, NULL otherwise.
264
e12be2f7 265\membersection{wxList::Nth}\label{wxlistnth}
a660d684
KB
266
267\func{wxNode *}{Nth}{\param{int}{ n}}
268
d8996187
VZ
269{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead.
270
a660d684
KB
271Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
272or the nth node could not be found).
273
e12be2f7 274\membersection{wxList::Number}\label{wxlistnumber}
a660d684
KB
275
276\func{int}{Number}{\void}
277
d8996187
VZ
278{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
279
a660d684
KB
280Returns the number of elements in the list.
281
e12be2f7 282\membersection{wxList::Sort}\label{wxlistsort}
a660d684
KB
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
291Allows the sorting of arbitrary lists by giving
292a function to compare two list elements. We use the system {\bf qsort} function
064998bf
VZ
293for the actual sorting process.
294
295If you use untyped wxList the sort function receives pointers to wxObject
296pointers (wxObject **), so be careful to dereference appropriately - but,
297of course, a better solution is to use list of appropriate type defined with
298{\tt WX\_DECLARE\_LIST}.
a660d684
KB
299
300Example:
301
302\begin{verbatim}
303 int listcompare(const void *arg1, const void *arg2)
304 {
305 return(compare(**(wxString **)arg1, // use the wxString 'compare'
306 **(wxString **)arg2)); // function
307 }
308
309 void main()
310 {
311 wxList list;
312
313 list.Append(new wxString("DEF"));
314 list.Append(new wxString("GHI"));
315 list.Append(new wxString("ABC"));
316 list.Sort(listcompare);
317 }
318\end{verbatim}
319