wxItemContainer Class Reference
[Controls]

#include <wx/ctrlsub.h>

Inheritance diagram for wxItemContainer:
Inheritance graph
[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.
void Delete (unsigned int n)
 Deletes an item from the control.

int Append (const wxString &item)
 Appends item into the control.
int Append (const wxString &item, void *clientData)
 Appends item into the control.
int Append (const wxString &item, wxClientData *clientData)
 Appends item into the control.
int Append (const wxArrayString &items)
 Appends several items at once into the control.
int Append (const wxArrayString &items, void **clientData)
 Appends several items at once into the control.
int Append (const wxArrayString &items, wxClientData **clientData)
 Appends several items at once into the control.
int Append (unsigned int n, const wxString *items)
 Appends several items at once into the control.
int Append (unsigned int n, const wxString *items, void **clientData)
 Appends several items at once into the control.
int Append (unsigned int n, const wxString *items, wxClientData **clientData)
 Appends several items at once into the control.

void * GetClientData (unsigned int n) const
 Returns a pointer to the client data associated with the given item (if any).
wxClientDataGetClientObject (unsigned int n) const
 Returns a pointer to the client data associated with the given item (if any).
void SetClientData (unsigned int n, void *data)
 Associates the given untyped client data pointer with the given item.
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).

int Insert (const wxString &item, unsigned int pos)
 Inserts item into the control.
int Insert (const wxString &item, unsigned int pos, void *clientData)
 Inserts item into the control.
int Insert (const wxString &item, unsigned int pos, wxClientData *clientData)
 Inserts item into the control.
int Insert (const wxArrayString &items, unsigned int pos)
 Inserts several items at once into the control.
int Insert (const wxArrayString &items, unsigned int pos, void **clientData)
 Inserts several items at once into the control.
int Insert (const wxArrayString &items, unsigned int pos, wxClientData **clientData)
 Inserts several items at once into the control.
int Insert (unsigned int n, const wxString *items, unsigned int pos)
 Inserts several items at once into the control.
int Insert (unsigned int n, const wxString *items, unsigned int pos, void **clientData)
 Inserts several items at once into the control.
int Insert (unsigned int n, const wxString *items, unsigned int pos, wxClientData **clientData)
 Inserts several items at once into the control.

void Set (const wxArrayString &items)
 Replaces the current control contents with the given items.
void Set (const wxArrayString &items, void **clientData)
 Replaces the current control contents with the given items.
void Set (const wxArrayString &items, wxClientData **clientData)
 Replaces the current control contents with the given items.
void Set (unsigned int n, const wxString *items)
 Replaces the current control contents with the given items.
void Set (unsigned int n, const wxString *items, void **clientData)
 Replaces the current control contents with the given items.
void Set (unsigned int n, const wxString *items, wxClientData **clientData)
 Replaces the current control contents with the given items.

List of all members.


Member Function Documentation

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

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.

Parameters:
n The zero-based item index.
See also:
Clear()
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 NULL if not present.
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).

Parameters:
n The zero-based position of the item.
Returns:
A pointer to the client data, or NULL if not present.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines



wxWidgets logo

[ top ]