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

T	The 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.