| Version: 3.3.1

Public Member Functions | List of all members
wxItemContainer Class Reference
Class List by Category » Controls

`#include <wx/ctrlsub.h>`

Inheritance diagram for wxItemContainer:
[legend]

## Detailed Description

This class is an abstract base class for some wxWidgets controls which contain several items such as wxListBox, wxCheckListBox, wxComboBox or wxChoice.

It defines an interface which is implemented by all controls which have string subitems each of which may be selected.

wxItemContainer extends wxItemContainerImmutable interface with methods for adding/removing items.

It defines the methods for accessing the controls items and although each of the derived classes implements them differently, they still all conform to the same interface.

The items in a wxItemContainer have (non-empty) string labels and, optionally, client data associated with them. Client data may be of two different kinds: either simple untyped (`void` *) pointers which are simply stored by the control but not used in any way by it, or typed pointers (wxClientData*) which are owned by the control meaning that the typed client data (and only it) will be deleted when an item is deleted using Delete() or the entire control is cleared using Clear(), which also happens when it is destroyed.

Finally note that in the same control all items must have client data of the same type (typed or untyped), if any. This type is determined by the first call to Append() (the version with client data pointer) or SetClientData().

Note that this is not a control, it's a mixin interface that classes have to derive from in addition to wxControl or wxWindow. Convenience class wxControlWithItems is provided for this purpose.

##

Library: wxCore
Category: Controls

See also
  wxControlWithItems, wxItemContainerImmutable

## Public Member Functions
void | Clear ()
| Removes all items from the control. More...
void | Delete (unsigned int n)
| Deletes an item from the control. More...
bool | IsSorted () const
| The control may maintain its items in a sorted order in which case items are automatically inserted at the right position when they are inserted or appended. More...
wxClientData * | DetachClientObject (unsigned int n)
| Returns the client object associated with the given item and transfers its ownership to the caller. More...
bool | HasClientData () const
| Returns true, if either untyped data (`void*`) or object data (wxClientData*) is associated with the items of the control. More...
bool | HasClientObjectData () const
| Returns true, if object data is associated with the items of the control. More...
bool | HasClientUntypedData () const
| Returns true, if untyped data (`void*`) is associated with the items of the control. More...
int | Append (const wxString &item)
| Appends item into the control. More...
int | Append (const wxString &item, void *clientData)
| Appends item into the control. More...
int | Append (const wxString &item, wxClientData *clientData)
| Appends item into the control. More...
int | Append (const wxArrayString &items)
| Appends several items at once into the control. More...
int | Append (const std::vector< wxString > &items)
| Appends several items at once into the control. More...
int | Append (const wxArrayString &items, void **clientData)
| Appends several items at once into the control. More...
int | Append (const wxArrayString &items, wxClientData **clientData)
| Appends several items at once into the control. More...
int | Append (unsigned int n, const wxString *items)
| Appends several items at once into the control. More...
int | Append (unsigned int n, const wxString *items, void **clientData)
| Appends several items at once into the control. More...
int | Append (unsigned int n, const wxString *items, wxClientData **clientData)
| Appends several items at once into the control. More...
void * | GetClientData (unsigned int n) const
| Returns a pointer to the client data associated with the given item (if any). More...
wxClientData * | GetClientObject (unsigned int n) const
| Returns a pointer to the client data associated with the given item (if any). More...
void | SetClientData (unsigned int n, void *data)
| Associates the given untyped client data pointer with the given item. More...
void | SetClientObject (unsigned int n, wxClientData *data)
| Associates the given typed client data pointer with the given item: the data object will be deleted when the item is deleted (either explicitly by using Delete() or implicitly when the control itself is destroyed). More...
int | Insert (const wxString &item, unsigned int pos)
| Inserts item into the control. More...
int | Insert (const wxString &item, unsigned int pos, void *clientData)
| Inserts item into the control. More...
int | Insert (const wxString &item, unsigned int pos, wxClientData *clientData)
| Inserts item into the control. More...
int | Insert (const wxArrayString &items, unsigned int pos)
| Inserts several items at once into the control. More...
int | Insert (const std::vector< wxString > &items)
| Inserts several items at once into the control. More...
int | Insert (const wxArrayString &items, unsigned int pos, void **clientData)
| Inserts several items at once into the control. More...
int | Insert (const wxArrayString &items, unsigned int pos, wxClientData **clientData)
| Inserts several items at once into the control. More...
int | Insert (unsigned int n, const wxString *items, unsigned int pos)
| Inserts several items at once into the control. More...
int | Insert (unsigned int n, const wxString *items, unsigned int pos, void **clientData)
| Inserts several items at once into the control. More...
int | Insert (unsigned int n, const wxString *items, unsigned int pos, wxClientData **clientData)
| Inserts several items at once into the control. More...
void | Set (const wxArrayString &items)
| Replaces the current control contents with the given items. More...
void | Set (const std::vector< wxString > &items)
| Replaces the current control contents with the given items. More...
void | Set (const wxArrayString &items, void **clientData)
| Replaces the current control contents with the given items. More...
void | Set (const wxArrayString &items, wxClientData **clientData)
| Replaces the current control contents with the given items. More...
void | Set (unsigned int n, const wxString *items)
| Replaces the current control contents with the given items. More...
void | Set (unsigned int n, const wxString *items, void **clientData)
| Replaces the current control contents with the given items. More...
void | Set (unsigned int n, const wxString *items, wxClientData **clientData)
| Replaces the current control contents with the given items. More...
Public Member Functions inherited from wxItemContainerImmutable
| wxItemContainerImmutable ()
| Constructor. More...
virtual unsigned int | GetCount () const =0
| Returns the number of items in the control. More...
bool | IsEmpty () const
| Returns true if the control is empty or false if it has some items. More...
virtual wxString | GetString (unsigned int n) const =0
| Returns the label of the item with the given index. More...
wxArrayString | GetStrings () const
| Returns the array of the labels of all items in the control. More...
virtual void | SetString (unsigned int n, const wxString &string)=0
| Sets the label for the given item. More...
virtual int | FindString (const wxString &string, bool caseSensitive=false) const
| Finds an item whose label matches the given string. More...
virtual void | SetSelection (int n)=0
| Sets the selection to the given item n or removes the selection entirely if n == `wxNOT_FOUND`. More...
virtual int | GetSelection () const =0
| Returns the index of the selected item or `wxNOT_FOUND` if no item is selected. More...
bool | SetStringSelection (const wxString &string)
| Selects the item with the specified string in the control. More...
virtual wxString | GetStringSelection () const
| Returns the label of the selected item or an empty string if no item is selected. More...
void | Select (int n)
| This is the same as SetSelection() and exists only because it is slightly more natural for controls which support multiple selection. More...

## Member Function Documentation

## ◆ Append() [1/10]

int wxItemContainer::Append | ( | const std::vector< wxString > & | items | ) |

Appends several items at once into the control.

This is the same as the overload taking wxArrayString, except that it works with the standard vector container.

Since
  3.1.0

## ◆ Append() [2/10]

int wxItemContainer::Append | ( | const wxArrayString & | items | ) |

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  items | Array of strings to insert.

## ◆ Append() [3/10]

int wxItemContainer::Append | ( | const wxArrayString & | items,
|  | void ** | clientData
| ) |  |

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  items | Array of strings to insert.
  clientData | Array of client data pointers of the same size as items to associate with the new items.

## ◆ Append() [4/10]

int wxItemContainer::Append | ( | const wxArrayString & | items,
|  | wxClientData ** | clientData
| ) |  |

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  items | Array of strings to insert.
  clientData | Array of client data pointers of the same size as items to associate with the new items.

## ◆ Append() [5/10]

int wxItemContainer::Append | ( | const wxString & | item | ) |

Appends item into the control.

Parameters

  item | String to add.

Returns
  The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has `wxLB_SORT` or `wxCB_SORT` style).

## ◆ Append() [6/10]

int wxItemContainer::Append | ( | const wxString & | item,
|  | void * | clientData
| ) |  |

Appends item into the control.

Parameters

  item | String to add.
  clientData | Pointer to client data to associate with the new item.

Returns
  The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has `wxLB_SORT` or `wxCB_SORT` style).

## ◆ Append() [7/10]

int wxItemContainer::Append | ( | const wxString & | item,
|  | wxClientData * | clientData
| ) |  |

Appends item into the control.

Parameters

  item | String to add.
  clientData | Pointer to client data to associate with the new item.

Returns
  The return value is the index of the newly inserted item. Note that this may be different from the last one if the control is sorted (e.g. has `wxLB_SORT` or `wxCB_SORT` style).

## ◆ Append() [8/10]

int wxItemContainer::Append | ( | unsigned int | n,
|  | const wxString * | items
| ) |  |

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.

## ◆ Append() [9/10]

int wxItemContainer::Append | ( | unsigned int | n,
|  | const wxString * | items,
|  | void ** | clientData
| ) |  |

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  clientData | Array of client data pointers of size n to associate with the new items.

## ◆ Append() [10/10]

int wxItemContainer::Append | ( | unsigned int | n,
|  | const wxString * | items,
|  | wxClientData ** | clientData
| ) |  |

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  clientData | Array of client data pointers of size n to associate with the new items.

## ◆ Clear()

void wxItemContainer::Clear | ( |  | ) |

Removes all items from the control.

Clear() also deletes the client data of the existing items if it is owned by the control.

## ◆ Delete()

void wxItemContainer::Delete | ( | unsigned int | n | ) |

Deletes an item from the control.

The client data associated with the item will be also deleted if it is owned by the control. Note that it is an error (signalled by an assert failure in debug builds) to remove an item with the index negative or greater or equal than the number of items in the control.

If there is a currently selected item below the item being deleted, i.e. if GetSelection() returns a valid index greater than or equal to n, the selection is invalidated when this function is called. However if the selected item appears before the item being deleted, the selection is preserved unchanged.

Parameters

  n | The zero-based item index.

See also
  Clear()

## ◆ DetachClientObject()

wxClientData* wxItemContainer::DetachClientObject | ( | unsigned int | n | ) |

Returns the client object associated with the given item and transfers its ownership to the caller.

This method, unlike GetClientObject(), expects the caller to delete the returned pointer. It also replaces the internally stored pointer with nullptr, i.e. completely detaches the client object pointer from the control.

It's an error to call this method unless HasClientObjectData() returns true.

Parameters

  n | The zero-based item index.

Returns
  The associated client object pointer to be deleted by caller or nullptr.

Since
  2.9.2

## ◆ GetClientData()

void* wxItemContainer::GetClientData | ( | unsigned int | n | ) | const

Returns a pointer to the client data associated with the given item (if any).

It is an error to call this function for a control which doesn't have untyped client data at all although it is OK to call it even if the given item doesn't have any client data associated with it (but other items do).

Parameters

  n | The zero-based position of the item.

Returns
  A pointer to the client data, or nullptr if not present.

## ◆ GetClientObject()

wxClientData* wxItemContainer::GetClientObject | ( | unsigned int | n | ) | const

Returns a pointer to the client data associated with the given item (if any).

It is an error to call this function for a control which doesn't have typed client data at all although it is OK to call it even if the given item doesn't have any client data associated with it (but other items do).

Notice that the returned pointer is still owned by the control and will be deleted by it, use DetachClientObject() if you want to remove the pointer from the control.

Parameters

  n | The zero-based position of the item.

Returns
  A pointer to the client data, or nullptr if not present.

## ◆ HasClientData()

bool wxItemContainer::HasClientData | ( |  | ) | const

Returns true, if either untyped data (`void*`) or object data (wxClientData*) is associated with the items of the control.

## ◆ HasClientObjectData()

bool wxItemContainer::HasClientObjectData | ( |  | ) | const

Returns true, if object data is associated with the items of the control.

Object data pointers have the type `wxClientData*` instead of `void*` and, importantly, are owned by the control, i.e. will be deleted by it, unlike their untyped counterparts.

## ◆ HasClientUntypedData()

bool wxItemContainer::HasClientUntypedData | ( |  | ) | const

Returns true, if untyped data (`void*`) is associated with the items of the control.

## ◆ Insert() [1/10]

int wxItemContainer::Insert | ( | const std::vector< wxString > & | items | ) |

Inserts several items at once into the control.

This is the same as the overload taking wxArrayString, except that it works with the standard vector container.

Since
  3.1.0

## ◆ Insert() [2/10]

int wxItemContainer::Insert | ( | const wxArrayString & | items,
|  | unsigned int | pos
| ) |  |

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.

Parameters

  items | Array of strings to insert.
  pos | Position to insert the items before, zero based.

Returns
  The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [3/10]

int wxItemContainer::Insert | ( | const wxArrayString & | items,
|  | unsigned int | pos,
|  | void ** | clientData
| ) |  |

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.

Parameters

  items | Array of strings to insert.
  pos | Position to insert the items before, zero based.
  clientData | Array of client data pointers of the same size as items to associate with the new items.

Returns
  The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [4/10]

int wxItemContainer::Insert | ( | const wxArrayString & | items,
|  | unsigned int | pos,
|  | wxClientData ** | clientData
| ) |  |

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.

Parameters

  items | Array of strings to insert.
  pos | Position to insert the items before, zero based.
  clientData | Array of client data pointers of the same size as items to associate with the new items.

Returns
  The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [5/10]

int wxItemContainer::Insert | ( | const wxString & | item,
|  | unsigned int | pos
| ) |  |

Inserts item into the control.

Parameters

  item | String to add.
  pos | Position to insert item before, zero based.

Returns
  The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [6/10]

int wxItemContainer::Insert | ( | const wxString & | item,
|  | unsigned int | pos,
|  | void * | clientData
| ) |  |

Inserts item into the control.

Parameters

  item | String to add.
  pos | Position to insert item before, zero based.
  clientData | Pointer to client data to associate with the new item.

Returns
  The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [7/10]

int wxItemContainer::Insert | ( | const wxString & | item,
|  | unsigned int | pos,
|  | wxClientData * | clientData
| ) |  |

Inserts item into the control.

Parameters

  item | String to add.
  pos | Position to insert item before, zero based.
  clientData | Pointer to client data to associate with the new item.

Returns
  The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [8/10]

int wxItemContainer::Insert | ( | unsigned int | n,
|  | const wxString * | items,
|  | unsigned int | pos
| ) |  |

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  pos | Position to insert the items before, zero based.

Returns
  The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [9/10]

int wxItemContainer::Insert | ( | unsigned int | n,
|  | const wxString * | items,
|  | unsigned int | pos,
|  | void ** | clientData
| ) |  |

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  pos | Position to insert the new items before, zero based.
  clientData | Array of client data pointers of size n to associate with the new items.

Returns
  The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ Insert() [10/10]

int wxItemContainer::Insert | ( | unsigned int | n,
|  | const wxString * | items,
|  | unsigned int | pos,
|  | wxClientData ** | clientData
| ) |  |

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  pos | Position to insert the new items before, zero based.
  clientData | Array of client data pointers of size n to associate with the new items.

Returns
  The return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

## ◆ IsSorted()

bool wxItemContainer::IsSorted | ( |  | ) | const

The control may maintain its items in a sorted order in which case items are automatically inserted at the right position when they are inserted or appended.

Returns true if the control maintains its items in a sorted order.

## ◆ Set() [1/7]

void wxItemContainer::Set | ( | const std::vector< wxString > & | items | ) |

Replaces the current control contents with the given items.

This is the same as the overload taking wxArrayString, except that it works with the standard vector container.

Since
  3.1.0

## ◆ Set() [2/7]

void wxItemContainer::Set | ( | const wxArrayString & | items | ) |

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  items | Array of strings to insert.

## ◆ Set() [3/7]

void wxItemContainer::Set | ( | const wxArrayString & | items,
|  | void ** | clientData
| ) |  |

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  items | Array of strings to insert.
  clientData | Array of client data pointers of the same size as items to associate with the new items.

## ◆ Set() [4/7]

void wxItemContainer::Set | ( | const wxArrayString & | items,
|  | wxClientData ** | clientData
| ) |  |

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  items | Array of strings to insert.
  clientData | Array of client data pointers of the same size as items to associate with the new items.

## ◆ Set() [5/7]

void wxItemContainer::Set | ( | unsigned int | n,
|  | const wxString * | items
| ) |  |

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.

## ◆ Set() [6/7]

void wxItemContainer::Set | ( | unsigned int | n,
|  | const wxString * | items,
|  | void ** | clientData
| ) |  |

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  clientData | Array of client data pointers of size n to associate with the new items.

## ◆ Set() [7/7]

void wxItemContainer::Set | ( | unsigned int | n,
|  | const wxString * | items,
|  | wxClientData ** | clientData
| ) |  |

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items.

Parameters

  n | Number of items in the items array.
  items | Array of strings of size n.
  clientData | Array of client data pointers of size n to associate with the new items.

## ◆ SetClientData()

void wxItemContainer::SetClientData | ( | unsigned int | n,
|  | void * | data
| ) |  |

Associates the given untyped client data pointer with the given item.

Note that it is an error to call this function if any typed client data pointers had been associated with the control items before.

Parameters

  n | The zero-based item index.
  data | The client data to associate with the item.

## ◆ SetClientObject()

void wxItemContainer::SetClientObject | ( | unsigned int | n,
|  | wxClientData * | data
| ) |  |

Associates the given typed client data pointer with the given item: the data object will be deleted when the item is deleted (either explicitly by using Delete() or implicitly when the control itself is destroyed).

Note that it is an error to call this function if any untyped client data pointers had been associated with the control items before.

Parameters

  n | The zero-based item index.
  data | The client data to associate with the item.