// Name: ctrlsub.h
// Purpose: interface of wxControlWithItems
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxItemContainerImmutable
- @wxheader{ctrlsub.h}
wxItemContainer defines an interface which is implemented by all controls
which have string subitems each of which may be selected.
@see IsEmpty()
*/
- virtual unsigned int GetCount() const;
+ virtual unsigned int GetCount() const = 0;
/**
Returns @true if the control is empty or @false if it has some items.
@return The label of the item or an empty string if the position was
invalid.
*/
- virtual wxString GetString(unsigned int n) const;
+ virtual wxString GetString(unsigned int n) const = 0;
/**
Returns the array of the labels of all items in the control.
@param string
The label to set.
*/
- virtual void SetString(unsigned int n, const wxString& s);
+ virtual void SetString(unsigned int n, const wxString& string) = 0;
/**
Finds an item whose label matches the given string.
@return The zero-based position of the item, or wxNOT_FOUND if the
string was not found.
*/
- virtual int FindString(const wxString& s, bool bCase = false) const;
+ virtual int FindString(const wxString& string, bool caseSensitive = false) const;
//@}
@see SetString(), SetStringSelection()
*/
- virtual void SetSelection(int n);
+ virtual void SetSelection(int n) = 0;
/**
Returns the index of the selected item or @c wxNOT_FOUND if no item is
@see SetSelection(), GetStringSelection()
*/
- virtual int GetSelection() const;
+ virtual int GetSelection() const = 0;
/**
- Selects the item with the specified string in the control. This doesn't
- cause any command events to be emitted.
+ Selects the item with the specified string in the control.
+
+ This method doesn't cause any command events to be emitted.
+
+ Notice that this method is case-insensitive, i.e. the string is
+ compared with all the elements of the control case-insensitively and
+ the first matching entry is selected, even if it doesn't have exactly
+ the same case as this string and there is an exact match afterwards.
@param string
The string to select.
-
@return @true if the specified string has been selected, @false if it
wasn't found in the control.
*/
/**
@class wxItemContainer
- @wxheader{ctrlsub.h}
This class is an abstract base class for some wxWidgets controls which
contain several items such as wxListBox, wxCheckListBox, wxComboBox or
@param items
Array of strings to insert.
*/
- void Append(const wxArrayString& items);
+ int Append(const wxArrayString& items);
/**
Appends several items at once into the control.
Array of client data pointers of the same size as @a items to
associate with the new items.
*/
- void Append(const wxArrayString& items, void **clientData);
+ int Append(const wxArrayString& items, void **clientData);
/**
Appends several items at once into the control.
Array of client data pointers of the same size as @a items to
associate with the new items.
*/
- void Append(const wxArrayString& items, wxClientData **clientData);
+ int Append(const wxArrayString& items, wxClientData **clientData);
/**
Appends several items at once into the control.
@param items
Array of strings of size @a n.
*/
- void Append(unsigned int n, const wxString* items);
+ int Append(unsigned int n, const wxString* items);
/**
Appends several items at once into the control.
Array of client data pointers of size @a n to associate with the
new items.
*/
- void Append(unsigned int n, const wxString* items,
- void** clientData);
+ int Append(unsigned int n, const wxString* items,
+ void** clientData);
/**
Appends several items at once into the control.
Array of client data pointers of size @a n to associate with the
new items.
*/
- void Append(unsigned int n, const wxString* items,
+ int Append(unsigned int n, const wxString* items,
wxClientData** clientData);
//@}
*/
void Delete(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
+ @NULL, i.e. completely detaches the client object pointer from the
+ control.
+
+ It's an error to call this method unless HasClientObjectData() returns
+ @true.
+
+ @param n
+ The zero-based item index.
+ @return The associated client object pointer to be deleted by caller or
+ @NULL.
+
+ @since 2.9.2
+ */
+ wxClientData *DetachClientObject(unsigned int n);
+
+ /**
+ Returns true, if either untyped data (@c void*) or object data (wxClientData*)
+ is associated with the items of the control.
+ */
+ bool HasClientData() const;
+
+ /**
+ Returns true, if object data is associated with the items of the
+ control.
+
+ Object data pointers have the type @c wxClientData* instead of @c void*
+ and, importantly, are owned by the control, i.e. will be deleted by it,
+ unlike their untyped counterparts.
+ */
+ bool HasClientObjectData() const;
+
+ /**
+ Returns true, if untyped data (@c void*)
+ is associated with the items of the control.
+ */
+ bool HasClientUntypedData() const;
+
+
//@{
/**
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.
+
@param n
The zero-based position of the item.
Array of strings to insert.
@param pos
Position to insert the items before, zero based.
+ @return The return value is the index of the last inserted item.
+ If the insertion failed for some reason, -1 is returned.
*/
- void Insert(const wxArrayString& items, unsigned int pos);
+ int Insert(const wxArrayString& items, unsigned int pos);
/**
Inserts several items at once into the control.
@param clientData
Array of client data pointers of the same size as @a items to
associate with the new items.
+ @return The return value is the index of the last inserted item.
+ If the insertion failed for some reason, -1 is returned.
*/
- void Insert(const wxArrayString& items, unsigned int pos,
+ int Insert(const wxArrayString& items, unsigned int pos,
void **clientData);
/**
@param clientData
Array of client data pointers of the same size as @a items to
associate with the new items.
+ @return The return value is the index of the last inserted item.
+ If the insertion failed for some reason, -1 is returned.
*/
- void Insert(const wxArrayString& items, unsigned int pos,
+ int Insert(const wxArrayString& items, unsigned int pos,
wxClientData **clientData);
/**
Array of strings of size @a n.
@param pos
Position to insert the items before, zero based.
+ @return The return value is the index of the last inserted item.
+ If the insertion failed for some reason, -1 is returned.
*/
- void Insert(unsigned int n, const wxString* items,
+ int Insert(unsigned int n, const wxString* items,
unsigned int pos);
/**
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
+ @return The return value is the index of the last inserted item.
+ If the insertion failed for some reason, -1 is returned.
*/
- void Insert(unsigned int n, const wxString* items,
+ int Insert(unsigned int n, const wxString* items,
unsigned int pos,
void** clientData);
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
+ @return The return value is the index of the last inserted item.
+ If the insertion failed for some reason, -1 is returned.
*/
- void Insert(unsigned int n, const wxString* items,
+ int Insert(unsigned int n, const wxString* items,
unsigned int pos,
wxClientData** clientData);
//@}
/**
@class wxControlWithItems
- @wxheader{ctrlsub.h}
This is convenience class that derives from both wxControl and
wxItemContainer. It is used as basis for some wxWidgets controls
projects / wxWidgets.git / blobdiff