wxWidgets: wxList< T > Class Template Reference

| Version: 3.2.7

Public Member Functions | List of all members
wxList< T > Class Template Reference
Class List by Category » Containers

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

## Constructor & Destructor Documentation

## ◆ wxList() [1/2]

template<typename T >

wxList< T >::wxList | ( |  | ) |

Default constructor.

## ◆ wxList() [2/2]

template<typename T >

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

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

## ◆ ~wxList()

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

## ◆ Append()

template<typename T >

wxList<T>::compatibility_iterator wxList< T >::Append | ( | T * | object | ) |

Appends the pointer to object to the list.

## ◆ assign() [1/2]

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.

## ◆ assign() [2/2]

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.

## ◆ AsVector()

template<typename T >

wxVector<T> wxList< T >::AsVector | ( |  | ) | const

Returns a wxVector holding the list elements.

Since
  2.9.5

## ◆ back() [1/2]

template<typename T >

reference wxList< T >::back | ( |  | ) |

Returns the last item of the list.

## ◆ back() [2/2]

template<typename T >

const_reference wxList< T >::back | ( |  | ) | const

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

## ◆ begin() [1/2]

template<typename T >

iterator wxList< T >::begin | ( |  | ) |

Returns an iterator pointing to the beginning of the list.

## ◆ begin() [2/2]

template<typename T >

const_iterator wxList< T >::begin | ( |  | ) | const

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

## ◆ Clear()

template<typename T >

void wxList< T >::Clear | ( |  | ) |

Clears the list.

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

## ◆ clear()

template<typename T >

void wxList< T >::clear | ( |  | ) |

Removes all items from the list.

## ◆ DeleteContents()

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.

## ◆ DeleteNode()

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.

## ◆ DeleteObject()

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.

## ◆ empty()

template<typename T >

bool wxList< T >::empty | ( |  | ) | const

Returns true if the list is empty.

## ◆ end() [1/2]

template<typename T >

const_iterator wxList< T >::end | ( |  | ) | const

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

## ◆ end() [2/2]

template<typename T >

iterator wxList< T >::end | ( |  | ) | const

Returns an iterator pointing at the end of the list.

## ◆ Erase()

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.

## ◆ erase() [1/2]

template<typename T >

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

Erases the items from first to last.

## ◆ erase() [2/2]

template<typename T >

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

Erases the given item.

## ◆ Find()

template<typename T >

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

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

## ◆ front() [1/2]

template<typename T >

reference wxList< T >::front | ( |  | ) | const

Returns the first item in the list.

## ◆ front() [2/2]

template<typename T >

const_reference wxList< T >::front | ( |  | ) | const

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

## ◆ GetCount()

template<typename T >

size_t wxList< T >::GetCount | ( |  | ) | const

Returns the number of elements in the list.

## ◆ GetFirst()

template<typename T >

wxList<T>::compatibility_iterator wxList< T >::GetFirst | ( |  | ) | const

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

## ◆ GetLast()

template<typename T >

wxList<T>::compatibility_iterator wxList< T >::GetLast | ( |  | ) | const

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

## ◆ IndexOf()

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.

## ◆ Insert() [1/3]

template<typename T >

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

Inserts object before the object referred to be iter.

## ◆ insert() [1/3]

template<typename T >

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

Inserts an item at the head of the list.

## ◆ insert() [2/3]

template<typename T >

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

Inserts several items at the given position.

## ◆ insert() [3/3]

template<typename T >

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

Inserts an item at the given position.

## ◆ Insert() [2/3]

template<typename T >

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

Inserts object at position.

## ◆ Insert() [3/3]

template<typename T >

wxList<T>::compatibility_iterator wxList< T >::Insert | ( | T * | object | ) |

Inserts object at the beginning of the list.

## ◆ IsEmpty()

template<typename T >

bool wxList< T >::IsEmpty | ( |  | ) | const

Returns true if the list is empty, false otherwise.

## ◆ Item()

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.

## ◆ max_size()

template<typename T >

size_type wxList< T >::max_size | ( |  | ) | const

Returns the largest possible size of the list.

## ◆ Member()

template<typename T >

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

Check if the object is present in the list.

See also
  Find()

## ◆ Nth()

template<typename T >

wxList<T>::compatibility_iterator wxList< T >::Nth | ( | int | n | ) | const

Deprecated:
  This function is deprecated, use Item() instead.

## ◆ Number()

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.

## ◆ pop_back()

template<typename T >

void wxList< T >::pop_back | ( |  | ) |

Removes the last item from the list.

## ◆ pop_front()

template<typename T >

void wxList< T >::pop_front | ( |  | ) |

Removes the first item from the list.

## ◆ push_back()

template<typename T >

void wxList< T >::push_back | ( | const_reference | v = `value_type()` | ) |

Adds an item to end of the list.

## ◆ push_front()

template<typename T >

void wxList< T >::push_front | ( | const_reference | v = `value_type()` | ) |

Adds an item to the front of the list.

## ◆ rbegin() [1/2]

template<typename T >

reverse_iterator wxList< T >::rbegin | ( |  | ) |

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

## ◆ rbegin() [2/2]

template<typename T >

const_reverse_iterator wxList< T >::rbegin | ( |  | ) | const

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

## ◆ remove()

template<typename T >

void wxList< T >::remove | ( | const_reference | v | ) |

Removes an item from the list.

## ◆ rend() [1/2]

template<typename T >

reverse_iterator wxList< T >::rend | ( |  | ) |

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

## ◆ rend() [2/2]

template<typename T >

const_reverse_iterator wxList< T >::rend | ( |  | ) | const

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

## ◆ resize()

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.

## ◆ reverse()

template<typename T >

void wxList< T >::reverse | ( |  | ) |

Reverses the list.

## ◆ size()

template<typename T >

size_type wxList< T >::size | ( |  | ) | const

Returns the size of the list.

## ◆ Sort()

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.