Contents Up Previous Next

wxList: wxObject

This class provides 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.

It is very common to iterate on a list as follows:

  ...
  wxPoint *point1 = new wxPoint(100, 100);
  wxPoint *point2 = new wxPoint(200, 200);

  wxList SomeList;
  SomeList.Append(point1);
  SomeList.Append(point2);

  ...

  wxNode *node = SomeList.First();
  while (node)
  {
    wxPoint *point = (wxPoint *)node->Data();
    ...
    node = node->Next();
  }
To delete nodes in a list as the list is being traversed, replace

    ...
    node = node->Next();
    ...
with

    ...
    delete point;
    delete node;
    node = SomeList.First();
    ...
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.

wxList::wxList
wxList::~wxList
wxList::Append
wxList::Clear
wxList::DeleteContents
wxList::DeleteNode
wxList::DeleteObject
wxList::Find
wxList::First
wxList::Insert
wxList::Last
wxList::Member
wxList::Nth
wxList::Number
wxList::Sort


wxList::wxList

void wxList(void)

void wxList(unsigned int key_type)

void wxList(int n, wxObject *objects[])

void 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::~wxList

void ~wxList(void)

Destroys list. Also destroys any remaining nodes, but does not destroy client data held in the nodes.


wxList::Append

wxNode * Append(wxObject *object)

wxNode * Append(long key, wxObject *object)

wxNode * Append(char *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.


wxList::Clear

void Clear(void)

Clears the list (but does not delete the client data stored with each node).


wxList::DeleteContents

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.


wxList::DeleteNode

Bool DeleteNode(wxNode *node)

Deletes the given node from the list, returning TRUE if successful.


wxList::DeleteObject

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.


wxList::Find

wxNode * Find(long key)

wxNode * Find(char *key)

Returns the node whose stored key matches key. Use on a keyed list only.


wxList::First

wxNode * First(void)

Returns the first node in the list (NULL if the list is empty).


wxList::Insert

wxNode * Insert(wxObject *object)

Insert object at front of list.

wxNode * Insert(wxNode *position, wxObject *object)

Insert object before position.


wxList::Last

wxNode * Last(void)

Returns the last node in the list (NULL if the list is empty).


wxList::Member

wxNode * Member(wxObject *object)

Returns the node associated with object if it is in the list, NULL otherwise.


wxList::Nth

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).


wxList::Number

int Number(void)

Returns the number of elements in the list.


wxList::Sort

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);
  }