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 wxHashTable for a faster method of storage when random access is required.
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).
The general idea is to have the base class wxListBase working with void * 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 WX_DECLARE_LIST and WX_IMPLEMENT_LIST macros like this (notice the similarity with WX_DECLARE_OBJARRAY and WX_IMPLEMENT_OBJARRAY macros):
Example
// 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...
}
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.
Derived from
Include files
<wx/list.h>
Example
It is very common to iterate on a list as follows:
... 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(); }To delete nodes in a list as the list is being traversed, replace
... node = node->Next(); ...with
... delete win; delete node; node = SomeList.GetFirst(); ...See wxNode for members that retrieve the data associated with a node, and members for getting to the next or previous node.
Note that a cast is required when retrieving the data from a node. Although a node is defined to store objects of type wxObject and derived types, other types (such as char*) may be used with appropriate casting.
See also
Members
wxList::wxList
wxList::~wxList
wxList::Append
wxList::Clear
wxList::DeleteContents
wxList::DeleteNode
wxList::DeleteObject
wxList::Find
wxList::GetFirst
wxList::IndexOf
wxList::Insert
wxList::GetLast
wxList::Member
wxList::Nth
wxList::Number
wxList::Sort
wxList()
wxList(unsigned int key_type)
wxList(int n, wxObject *objects[])
wxList(wxObject *object, ...)
Constructors. key_type is one of wxKEY_NONE, wxKEY_INTEGER, or wxKEY_STRING, and indicates what sort of keying is required (if any).
objects is an array of n objects with which to initialize the list.
The variable-length argument list constructor must be supplied with a terminating NULL.
~wxList()
Destroys the list. Also destroys any remaining nodes, but does not destroy client data held in the nodes.
wxNode * Append(wxObject *object)
wxNode * Append(long key, wxObject *object)
wxNode * Append(const wxString& key, wxObject *object)
Appends a new wxNode to the end of the list and puts a pointer to the object 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.
The key string is copied and stored by the list implementation.
void Clear()
Clears the list (but does not delete the client data stored with each node).
void DeleteContents(bool destroy)
If destroy is TRUE, instructs the list to call delete on the client contents of a node whenever the node is destroyed. The default is FALSE.
bool DeleteNode(wxNode *node)
Deletes the given node from the list, returning TRUE if successful.
bool DeleteObject(wxObject *object)
Finds the given client object and deletes the appropriate node from the list, returning TRUE if successful. The application must delete the actual object separately.
wxNode * Find(long key)
wxNode * Find(const wxString& key)
Returns the node whose stored key matches key. Use on a keyed list only.
wxNode * GetFirst()
Returns the first node in the list (NULL if the list is empty).
int IndexOf(wxObject* obj )
Returns the index of obj within the list or NOT_FOUND if obj is not found in the list.
wxNode * Insert(wxObject *object)
Insert object at front of list.
wxNode * Insert(wxNode *position, wxObject *object)
Insert object before position.
wxNode * GetLast()
Returns the last node in the list (NULL if the list is empty).
wxNode * Member(wxObject *object)
Returns the node associated with object if it is in the list, NULL otherwise.
wxNode * Nth(int n)
Returns the nth node in the list, indexing from zero (NULL if the list is empty or the nth node could not be found).
int Number()
Returns the number of elements in the list.
void Sort(wxSortCompareFunction compfunc)
// Type of compare function for list sort operation (as in 'qsort') typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);Allows the sorting of arbitrary lists by giving a function to compare two list elements. We use the system qsort function for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **), so be careful to dereference appropriately.
Example:
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); }