## wxControlWithItems

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

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 wxControlWithItems 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 or the entire control is cleared (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.

Derived from

wxControl
wxWindow
wxEvtHandler
wxObject

Include files

<wx/ctrlsub.h> but usually never included directly

Members

wxControlWithItems::Append
wxControlWithItems::Clear
wxControlWithItems::Delete
wxControlWithItems::FindString
wxControlWithItems::GetClientData
wxControlWithItems::GetClientObject
wxControlWithItems::GetCount
wxControlWithItems::GetSelection
wxControlWithItems::GetString
wxControlWithItems::GetStrings
wxControlWithItems::GetStringSelection
wxControlWithItems::Insert
wxControlWithItems::IsEmpty
wxControlWithItems::Number
wxControlWithItems::Select
wxControlWithItems::SetClientData
wxControlWithItems::SetClientObject
wxControlWithItems::SetSelection
wxControlWithItems::SetString
wxControlWithItems::SetStringSelection

### wxControlWithItems::Append

int Append(const wxString& item)

Adds the item to the end of the list box.

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

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

Adds the item to the end of the list box, associating the given, typed or untyped, client data pointer with the item.

void Append(const wxArrayString& strings)

Appends several items at once to the control. Notice that calling this method may be much faster than appending the items one by one if you need to add a lot of items.

Parameters

item

String to add.

clientData

Client data to associate with the item.

Return value

When appending a single item, the return value is the index of the newly added item which may be different from the last one if the control is sorted (e.g. has `wxLB_SORT` or `wxCB_SORT` style).

### wxControlWithItems::Clear

void Clear()

Removes all items from the control.

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

### wxControlWithItems::Delete

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

Parameters

n

The zero-based item index.

See also

Clear

### wxControlWithItems::FindString

int FindString(const wxString& string, bool caseSensitive = false)

Finds an item whose label matches the given string.

Parameters

string

String to find.

caseSensitive

Whether search is case sensitive (default is not).

Return value

The zero-based position of the item, or `wxNOT_FOUND` if the string was not found.

### wxControlWithItems::GetClientData

void * 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.

Return value

A pointer to the client data, or `NULL` if not present.

### wxControlWithItems::GetClientObject

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

Parameters

n

The zero-based position of the item.

Return value

A pointer to the client data, or `NULL` if not present.

### wxControlWithItems::GetCount

unsigned int GetCount() const

Returns the number of items in the control.

See also

IsEmpty

### wxControlWithItems::GetSelection

int GetSelection() const

Returns the index of the selected item or `wxNOT_FOUND` if no item is selected.

Return value

The position of the current selection.

Remarks

This method can be used with single selection list boxes only, you should use wxListBox::GetSelections for the list boxes with `wxLB_MULTIPLE` style.

See also

SetSelection, GetStringSelection

### wxControlWithItems::GetString

wxString GetString(unsigned int n) const

Returns the label of the item with the given index.

Parameters

n

The zero-based index.

Return value

The label of the item or an empty string if the position was invalid.

### wxControlWithItems::GetStrings

wxArrayString GetStrings() const

Returns the array of the labels of all items in the control.

### wxControlWithItems::GetStringSelection

wxString GetStringSelection() const

Returns the label of the selected item or an empty string if no item is selected.

See also

GetSelection

### wxControlWithItems::Insert

int Insert(const wxString& item, unsigned int pos)

Inserts the item into the list before pos. Not valid for `wxLB_SORT` or `wxCB_SORT` styles, use Append instead.

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

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

Inserts the item into the list before pos, associating the given, typed or untyped, client data pointer with the item. Not valid for `wxLB_SORT` or `wxCB_SORT` styles, use Append instead.

Parameters

item

String to add.

pos

Position to insert item before, zero based.

clientData

Client data to associate with the item.

Return value

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

### wxControlWithItems::IsEmpty

bool IsEmpty() const

Returns `true` if the control is empty or `false` if it has some items.

See also

GetCount

### wxControlWithItems::Number

int Number() const

Obsolescence note: This method is obsolete and was replaced with GetCount, please use the new method in the new code. This method is only available if wxWidgets was compiled with `WXWIN_COMPATIBILITY_2_2` defined and will disappear completely in future versions.

### wxControlWithItems::Select

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.

### wxControlWithItems::SetClientData

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

### wxControlWithItems::SetClientObject

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

### wxControlWithItems::SetSelection

void SetSelection(int n)

Sets the selection to the given item n or removes the selection entirely if n == `wxNOT_FOUND`.

Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections.

Parameters

n

The string position to select, starting from zero.

See also

SetString, SetStringSelection

### wxControlWithItems::SetString

void SetString(unsigned int n, const wxString& string)

Sets the label for the given item.

Parameters

n

The zero-based item index.

string

The label to set.

### wxControlWithItems::SetStringSelection

bool SetStringSelection(const wxString& string)

Selects the item with the specified string in the control. This doesn't cause any command events being emitted.

Parameters

string

The string to select.

Return value

`true` if the specified string has been selected, `false` if it wasn't found in the control.

See also

SetSelection