1 \section{\class{wxList
}}\label{wxlist
}
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.
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).
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
30 // this part might be in a header or source (.cpp) file
36 // declare our list class: this macro declares and partly implements MyList
37 // class (which derives from wxListBase)
38 WX_DECLARE_LIST(MyListElement, MyList)
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
46 #include <wx/listimpl.cpp>
47 WX_DEFINE_LIST(MyList)
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.
53 MyListElement element;
54 list.Add(element); // ok
55 list.Add(
17); // error: incorrect type
57 // let's iterate over the list
58 for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
60 MyListElement *current = node->GetData();
62 ...process the current element...
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.
71 \wxheading{Derived from
}
73 \helpref{wxObject
}{wxobject
}
75 {\bf WARNING:
} the rest of documentation may be out-of-date.
79 It is very common to iterate on a list as follows:
83 wxPoint *point1 = new wxPoint(
100,
100);
84 wxPoint *point2 = new wxPoint(
200,
200);
87 SomeList.Append(point1);
88 SomeList.Append(point2);
92 wxNode *node = SomeList.First();
95 wxPoint *point = (wxPoint *)node->Data();
101 To delete nodes in a list as the list is being traversed, replace
115 node = SomeList.First();
119 See
\helpref{wxNode
}{wxnode
} for members that retrieve the data associated with a node, and
120 members for getting to the next or previous node.
122 Note that a cast is required when retrieving the data from a node. Although a
123 node is defined to store objects of type
{\bf wxObject
} and derived types, other
124 types (such as char*) may be used with appropriate casting.
128 \helpref{wxNode
}{wxnode
},
\helpref{wxStringList
}{wxstringlist
},
129 \helpref{wxArray
}{wxarray
}
131 \latexignore{\rtfignore{\wxheading{Members
}}}
133 \membersection{wxList::wxList
}
135 \func{}{wxList
}{\void}
137 \func{}{wxList
}{\param{unsigned int
}{ key
\_type}}
139 \func{}{wxList
}{\param{int
}{ n
},
\param{wxObject *
}{objects
[]}}
141 \func{}{wxList
}{\param{wxObject *
}{object
}, ...
}
143 Constructors.
{\it key
\_type} is one of wxKEY
\_NONE, wxKEY
\_INTEGER, or wxKEY
\_STRING,
144 and indicates what sort of keying is required (if any).
146 {\it objects
} is an array of
{\it n
} objects with which to initialize the list.
148 The variable-length argument list constructor must be supplied with a
151 \membersection{wxList::
\destruct{wxList
}}
153 \func{}{\destruct{wxList
}}{\void}
155 Destroys the list. Also destroys any remaining nodes, but does not destroy
156 client data held in the nodes.
158 \membersection{wxList::Append
}
160 \func{wxNode *
}{Append
}{\param{wxObject *
}{object
}}
162 \func{wxNode *
}{Append
}{\param{long
}{ key
},
\param{wxObject *
}{object
}}
164 \func{wxNode *
}{Append
}{\param{const wxString\&
}{key
},
\param{wxObject *
}{object
}}
166 Appends a new
{\bf wxNode
} to the end of the list and puts a pointer to the
167 \rtfsp{\it object
} in the node. The last two forms store a key with the object for
168 later retrieval using the key. The new node is returned in each case.
170 The key string is copied and stored by the list implementation.
172 \membersection{wxList::Clear
}
174 \func{void
}{Clear
}{\void}
176 Clears the list (but does not delete the client data stored with each node).
178 \membersection{wxList::DeleteContents
}
180 \func{void
}{DeleteContents
}{\param{bool
}{ destroy
}}
182 If
{\it destroy
} is TRUE, instructs the list to call
{\it delete
} on the client contents of
183 a node whenever the node is destroyed. The default is FALSE.
185 \membersection{wxList::DeleteNode
}
187 \func{bool
}{DeleteNode
}{\param{wxNode *
}{node
}}
189 Deletes the given node from the list, returning TRUE if successful.
191 \membersection{wxList::DeleteObject
}
193 \func{bool
}{DeleteObject
}{\param{wxObject *
}{object
}}
195 Finds the given client
{\it object
} and deletes the appropriate node from the list, returning
196 TRUE if successful. The application must delete the actual object separately.
198 \membersection{wxList::Find
}
200 \func{wxNode *
}{Find
}{\param{long
}{ key
}}
202 \func{wxNode *
}{Find
}{\param{const wxString\&
}{key
}}
204 Returns the node whose stored key matches
{\it key
}. Use on a keyed list only.
206 \membersection{wxList::First
}
208 \func{wxNode *
}{First
}{\void}
210 Returns the first node in the list (NULL if the list is empty).
212 \membersection{wxList::IndexOf
}
214 \func{int
}{IndexOf
}{\param{wxObject*
}{ obj
}}
216 Returns the index of
{\it obj
} within the list or NOT
\_FOUND if
{\it obj
}
217 is not found in the list.
219 \membersection{wxList::Insert
}
221 \func{wxNode *
}{Insert
}{\param{wxObject *
}{object
}}
223 Insert object at front of list.
225 \func{wxNode *
}{Insert
}{\param{wxNode *
}{position
},
\param{wxObject *
}{object
}}
227 Insert object before
{\it position
}.
230 \membersection{wxList::Last
}
232 \func{wxNode *
}{Last
}{\void}
234 Returns the last node in the list (NULL if the list is empty).
236 \membersection{wxList::Member
}
238 \func{wxNode *
}{Member
}{\param{wxObject *
}{object
}}
240 Returns the node associated with
{\it object
} if it is in the list, NULL otherwise.
242 \membersection{wxList::Nth
}
244 \func{wxNode *
}{Nth
}{\param{int
}{ n
}}
246 Returns the
{\it nth
} node in the list, indexing from zero (NULL if the list is empty
247 or the nth node could not be found).
249 \membersection{wxList::Number
}
251 \func{int
}{Number
}{\void}
253 Returns the number of elements in the list.
255 \membersection{wxList::Sort
}
257 \func{void
}{Sort
}{\param{wxSortCompareFunction
}{ compfunc
}}
260 // Type of compare function for list sort operation (as in 'qsort')
261 typedef int
(*wxSortCompareFunction)(const void *elem1, const void *elem2);
264 Allows the sorting of arbitrary lists by giving
265 a function to compare two list elements. We use the system {\bf qsort} function
266 for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **),
267 so be careful to dereference appropriately.
272 int listcompare(const void *arg1, const void *arg2)
274 return(compare
(**(wxString **)arg1, // use the wxString 'compare'
275 **(wxString **)arg2)); // function
282 list.Append(new wxString("DEF"));
283 list.Append(new wxString("GHI"));
284 list.Append(new wxString("ABC"));
285 list.Sort(listcompare);