Version: 3.1.0
wxList< T > Class Template Reference

#include <wx/list.h>

Detailed Description

template<typename T>
class wxList< T >

The wxList<T> class provides linked list functionality.

This class has been rewritten to be type safe and to provide the full API of the STL std::list container and should be used like it. The exception is that wxList<T> actually stores pointers and therefore its iterators return pointers and not references to the actual objects in the list (see example below) and value_type is defined as T*. wxList<T> destroys an object after removing it only if wxList<T>::DeleteContents has been called.

wxList<T> is not a real template and it requires that you declare and define each wxList<T> class in your program. This is done with WX_DECLARE_LIST and WX_DEFINE_LIST macros (see example). We hope that we'll be able to provide a proper template class providing both the STL std::list and the old wxList API in the future.

Please refer to the STL std::list documentation (see http://www.cppreference.com/wiki/stl/list/start) for further information on how to use the class. Below we documented both the supported STL and the legacy API that originated from the old wxList class and which can still be used alternatively for the same class.

Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1) then wxList<T> will actually derive from std::list and just add a legacy compatibility layer for the old wxList class.

// this part might be in a header or source (.cpp) file
class MyListElement
{
... // whatever
};
// this macro declares and partly implements MyList class
WX_DECLARE_LIST(MyListElement, MyList);
...
// the only requirement 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);
MyList list;
MyListElement element;
list.Append(&element); // ok
list.Append(17); // error: incorrect type
// let's iterate over the list in STL syntax
MyList::iterator iter;
for (iter = list.begin(); iter != list.end(); ++iter)
{
MyListElement *current = *iter;
...process the current element...
}
// the same with the legacy API from the old wxList class
MyList::compatibility_iterator node = list.GetFirst();
while (node)
{
MyListElement *current = node->GetData();
...process the current element...
node = node->GetNext();
}

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. The use of the latter is especially discouraged as it is not only unsafe but is also much less efficient than wxArrayString class.

Template Parameters
TThe type stored in the wxList nodes.

Library:  wxBase
Category:  Containers
See Also
wxArray<T>, wxVector<T>, wxNode<T>

Public Member Functions

 wxList ()
 Default constructor.
 
 wxList (size_t count, T *elements[])
 Constructor which initialized the list with an array of count elements.
 
 ~wxList ()
 Destroys the list, but does not delete the objects stored in the list unless you called DeleteContents(true ).
 
wxList< T >::compatibility_iterator Append (T *object)
 Appends the pointer to object to the list.
 
void Clear ()
 Clears the list.
 
void DeleteContents (bool destroy)
 If destroy is true, instructs the list to call delete on objects stored in the list whenever they are removed.
 
bool DeleteNode (const compatibility_iterator &iter)
 Deletes the given element referred to by iter from the list if iter is a valid iterator.
 
bool DeleteObject (T *object)
 Finds the given object and removes it from the list, returning true if successful.
 
void Erase (const compatibility_iterator &iter)
 Removes element referred to be iter.
 
wxList< T >::compatibility_iterator Find (T *object) const
 Returns the iterator referring to object or NULL if none found.
 
size_t GetCount () const
 Returns the number of elements in the list.
 
wxList< T >::compatibility_iterator GetFirst () const
 Returns the first iterator in the list (NULL if the list is empty).
 
wxList< T >::compatibility_iterator GetLast () const
 Returns the last iterator in the list (NULL if the list is empty).
 
int IndexOf (T *obj) const
 Returns the index of obj within the list or wxNOT_FOUND if obj is not found in the list.
 
wxList< T >::compatibility_iterator Insert (T *object)
 Inserts object at the beginning of the list.
 
wxList< T >::compatibility_iterator Insert (size_t position, T *object)
 Inserts object at position.
 
wxList< T >::compatibility_iterator Insert (compatibility_iterator iter, T *object)
 Inserts object before the object referred to be iter.
 
bool IsEmpty () const
 Returns true if the list is empty, false otherwise.
 
wxList< T >::compatibility_iterator Item (size_t index) const
 Returns the iterator referring to the object at the given index in the list.
 
bool Member (T *object) const
 Check if the object is present in the list.
 
wxList< T >::compatibility_iterator Nth (int n) const
 
int Number () const
 
void Sort (wxSortCompareFunction compfunc)
 Allows the sorting of arbitrary lists by giving a function to compare two list elements.
 
void assign (const_iterator first, const const_iterator &last)
 Clears the list and item from first to last from another list to it.
 
void assign (size_type n, const_reference v=value_type())
 Clears the list and adds n items with value v to it.
 
reference back ()
 Returns the last item of the list.
 
const_reference back () const
 Returns the last item of the list as a const reference.
 
iterator begin ()
 Returns an iterator pointing to the beginning of the list.
 
const_iterator begin () const
 Returns a const iterator pointing to the beginning of the list.
 
void clear ()
 Removes all items from the list.
 
bool empty () const
 Returns true if the list is empty.
 
const_iterator end () const
 Returns a const iterator pointing at the end of the list.
 
iterator end () const
 Returns a iterator pointing at the end of the list.
 
iterator erase (const iterator &it)
 Erases the given item.
 
iterator erase (const iterator &first, const iterator &last)
 Erases the items from first to last.
 
reference front () const
 Returns the first item in the list.
 
const_reference front () const
 Returns the first item in the list as a const reference.
 
iterator insert (const iterator &it)
 Inserts an item at the head of the list.
 
void insert (const iterator &it, size_type n)
 Inserts an item at the given position.
 
void insert (const iterator &it, const_iterator first, const const_iterator &last)
 Inserts several items at the given position.
 
size_type max_size () const
 Returns the largest possible size of the list.
 
void pop_back ()
 Removes the last item from the list.
 
void pop_front ()
 Removes the first item from the list.
 
void push_back (const_reference v=value_type())
 Adds an item to end of the list.
 
void push_front (const_reference v=value_type())
 Adds an item to the front of the list.
 
reverse_iterator rbegin ()
 Returns a reverse iterator pointing to the beginning of the reversed list.
 
const_reverse_iterator rbegin () const
 Returns a const reverse iterator pointing to the beginning of the reversed list.
 
void remove (const_reference v)
 Removes an item from the list.
 
reverse_iterator rend ()
 Returns a reverse iterator pointing to the end of the reversed list.
 
const_reverse_iterator rend () const
 Returns a const reverse iterator pointing to the end of the reversed list.
 
void resize (size_type n, value_type v=value_type())
 Resizes the list.
 
void reverse ()
 Reverses the list.
 
size_type size () const
 Returns the size of the list.
 
wxVector< T > AsVector () const
 Returns a wxVector holding the list elements.
 

Constructor & Destructor Documentation

template<typename T >
wxList< T >::wxList ( )

Default constructor.

template<typename T >
wxList< T >::wxList ( size_t  count,
T *  elements[] 
)

Constructor which initialized the list with an array of count elements.

template<typename T >
wxList< T >::~wxList ( )

Destroys the list, but does not delete the objects stored in the list unless you called DeleteContents(true ).

Member Function Documentation

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Append ( T *  object)

Appends the pointer to object to the list.

template<typename T >
void wxList< T >::assign ( const_iterator  first,
const const_iterator &  last 
)

Clears the list and item from first to last from another list to it.

template<typename T >
void wxList< T >::assign ( size_type  n,
const_reference  v = value_type() 
)

Clears the list and adds n items with value v to it.

template<typename T >
wxVector<T> wxList< T >::AsVector ( ) const

Returns a wxVector holding the list elements.

Since
2.9.5
template<typename T >
reference wxList< T >::back ( )

Returns the last item of the list.

template<typename T >
const_reference wxList< T >::back ( ) const

Returns the last item of the list as a const reference.

template<typename T >
iterator wxList< T >::begin ( )

Returns an iterator pointing to the beginning of the list.

template<typename T >
const_iterator wxList< T >::begin ( ) const

Returns a const iterator pointing to the beginning of the list.

template<typename T >
void wxList< T >::Clear ( )

Clears the list.

Deletes the actual objects if DeleteContents( true ) was called previously.

template<typename T >
void wxList< T >::clear ( )

Removes all items from the list.

template<typename T >
void wxList< T >::DeleteContents ( bool  destroy)

If destroy is true, instructs the list to call delete on objects stored in the list whenever they are removed.

The default is false.

template<typename T >
bool wxList< T >::DeleteNode ( const compatibility_iterator &  iter)

Deletes the given element referred to by iter from the list if iter is a valid iterator.

Returns true if successful.

Deletes the actual object if DeleteContents( true ) was called previously.

template<typename T >
bool wxList< T >::DeleteObject ( T *  object)

Finds the given object and removes it from the list, returning true if successful.

Deletes object if DeleteContents( true ) was called previously.

template<typename T >
bool wxList< T >::empty ( ) const

Returns true if the list is empty.

template<typename T >
const_iterator wxList< T >::end ( ) const

Returns a const iterator pointing at the end of the list.

template<typename T >
iterator wxList< T >::end ( ) const

Returns a iterator pointing at the end of the list.

template<typename T >
void wxList< T >::Erase ( const compatibility_iterator &  iter)

Removes element referred to be iter.

Deletes the actual object if DeleteContents( true ) was called previously.

template<typename T >
iterator wxList< T >::erase ( const iterator &  it)

Erases the given item.

template<typename T >
iterator wxList< T >::erase ( const iterator &  first,
const iterator &  last 
)

Erases the items from first to last.

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Find ( T *  object) const

Returns the iterator referring to object or NULL if none found.

template<typename T >
reference wxList< T >::front ( ) const

Returns the first item in the list.

template<typename T >
const_reference wxList< T >::front ( ) const

Returns the first item in the list as a const reference.

template<typename T >
size_t wxList< T >::GetCount ( ) const

Returns the number of elements in the list.

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::GetFirst ( ) const

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

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::GetLast ( ) const

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

template<typename T >
int wxList< T >::IndexOf ( T *  obj) const

Returns the index of obj within the list or wxNOT_FOUND if obj is not found in the list.

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Insert ( T *  object)

Inserts object at the beginning of the list.

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Insert ( size_t  position,
T *  object 
)

Inserts object at position.

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Insert ( compatibility_iterator  iter,
T *  object 
)

Inserts object before the object referred to be iter.

template<typename T >
iterator wxList< T >::insert ( const iterator &  it)

Inserts an item at the head of the list.

template<typename T >
void wxList< T >::insert ( const iterator &  it,
size_type  n 
)

Inserts an item at the given position.

template<typename T >
void wxList< T >::insert ( const iterator &  it,
const_iterator  first,
const const_iterator &  last 
)

Inserts several items at the given position.

template<typename T >
bool wxList< T >::IsEmpty ( ) const

Returns true if the list is empty, false otherwise.

template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Item ( size_t  index) const

Returns the iterator referring to the object at the given index in the list.

template<typename T >
size_type wxList< T >::max_size ( ) const

Returns the largest possible size of the list.

template<typename T >
bool wxList< T >::Member ( T *  object) const

Check if the object is present in the list.

See Also
Find()
template<typename T >
wxList<T>::compatibility_iterator wxList< T >::Nth ( int  n) const
Deprecated:
This function is deprecated, use Item() instead.
template<typename T >
int wxList< T >::Number ( ) const
Deprecated:
This function is deprecated, use wxList::GetCount instead. Returns the number of elements in the list.
template<typename T >
void wxList< T >::pop_back ( )

Removes the last item from the list.

template<typename T >
void wxList< T >::pop_front ( )

Removes the first item from the list.

template<typename T >
void wxList< T >::push_back ( const_reference  v = value_type())

Adds an item to end of the list.

template<typename T >
void wxList< T >::push_front ( const_reference  v = value_type())

Adds an item to the front of the list.

template<typename T >
reverse_iterator wxList< T >::rbegin ( )

Returns a reverse iterator pointing to the beginning of the reversed list.

template<typename T >
const_reverse_iterator wxList< T >::rbegin ( ) const

Returns a const reverse iterator pointing to the beginning of the reversed list.

template<typename T >
void wxList< T >::remove ( const_reference  v)

Removes an item from the list.

template<typename T >
reverse_iterator wxList< T >::rend ( )

Returns a reverse iterator pointing to the end of the reversed list.

template<typename T >
const_reverse_iterator wxList< T >::rend ( ) const

Returns a const reverse iterator pointing to the end of the reversed list.

template<typename T >
void wxList< T >::resize ( size_type  n,
value_type  v = value_type() 
)

Resizes the list.

If the list is longer than n, then items are removed until the list becomes long n. If the list is shorter than n items with the value v are appended to the list until the list becomes long n.

template<typename T >
void wxList< T >::reverse ( )

Reverses the list.

template<typename T >
size_type wxList< T >::size ( ) const

Returns the size of the list.

template<typename T >
void wxList< T >::Sort ( wxSortCompareFunction  compfunc)

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.