Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added documentation for wxItemContainer class; moved methods docs

Browse Source 
from wxControlWithItems there and fixed errors in them.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53131 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Václav Slavík
2008-04-11 22:12:31 +00:00
parent f801d19a74
commit bf84f3e207
3 changed files with 568 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
interface/combobox.h
View File

@@ -59,7 +59,7 @@
@see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
*/ */
class wxComboBox : public wxControlWithItems class wxComboBox : public wxControl, public wxItemContainer
{ {
public: public:
//@{ //@{

804
interface/ctrlsub.h
View File

@@ -6,95 +6,75 @@
// Licence: wxWindows license // Licence: wxWindows license
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
/** /**
@class wxControlWithItems
@wxheader{ctrlsub.h} @wxheader{ctrlsub.h}
This class is an abstract base class for some wxWidgets controls which contain wxItemContainer defines an interface which is implemented by all controls
several items such as wxListBox, wxCheckListBox, wxChoice and wxComboBox derive which have string subitems each of which may be selected.
from it.
It defines the methods for accessing the controls items and although each of It is decomposed in wxItemContainerImmutable which omits all methods
the derived classes implements them differently, they still all conform to the adding/removing items and is used by wxRadioBox and wxItemContainer itself.
same interface.
The items in a wxControlWithItems have (non-empty) string labels and, Note that this is not a control, it's a mixin interface that classes
optionally, client data associated with them. Client data may be of two have to derive from in addition to wxControl or wxWindow.
different kinds: either simple untyped (@c void *) pointers which are simply
stored by the control but not used in any way by it, or typed pointers Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which
(@c wxClientData *) which are owned by the control meaning that the typed implements an extended interface deriving from this one)
client data (and only it) will be deleted when an item is deleted
(using wxControlWithItems::Delete) or the entire control is cleared
(using wxControlWithItems::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 wxControlWithItems::Append (the version with
client data pointer) or wxControlWithItems::SetClientData.
@library{wxcore} @library{wxcore}
@category{controls} @category{ctrl}
@see wxControlWithItems::Clear @see wxControlWithItems, wxItemContainer
*/ */
class wxControlWithItems : public wxControl class wxItemContainerImmutable
{ {
public: public:
/// Constructor
wxItemContainerImmutable();
//@{ //@{
/**
Appends several items at once to 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.
@param item /**
String to add. Returns the number of items in the control.
@param stringsArray
Contains items to append to the control. @see IsEmpty()
@param strings */
Array of strings of size n. virtual unsigned int GetCount() const;
/**
Returns @true if the control is empty or @false if it has some items.
@see GetCount()
*/
bool IsEmpty() const;
/**
Returns the label of the item with the given index.
@param n @param n
Number of items in the strings array. The zero-based index.
@param clientData
Array of client data pointers of size n to associate with the new items.
@returns When appending a single item, the return value is the index of @returns The label of the item or an empty string if the position was
the newly added item which may be different from the invalid.
last one if the control is sorted (e.g. has wxLB_SORT
or wxCB_SORT style).
*/ */
int Append(const wxString& item); virtual wxString GetString(unsigned int n) const;
int Append(const wxString& item, void* clientData);
int Append(const wxString& item, wxClientData* clientData);
void Append(const wxArrayString& strings);
void Append(unsigned int n, const wxString* strings);
void Append(unsigned int n, const wxString* strings,
void** clientData);
void Append(unsigned int n, const wxString* strings,
wxClientData** clientData);
//@}
/** /**
Removes all items from the control. Returns the array of the labels of all items in the control.
@e Clear() also deletes the client data of the existing items if it is owned
by the control.
*/ */
void Clear(); wxArrayString GetStrings() const;
/** /**
Deletes an item from the control. The client data associated with the item Sets the label for the given 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.
@param n @param n
The zero-based item index. The zero-based item index.
@param string
@see Clear() The label to set.
*/ */
void Delete(unsigned int n); virtual void SetString(unsigned int n, const wxString& s);
/** /**
Finds an item whose label matches the given string. Finds an item whose label matches the given string.
@@ -107,14 +87,276 @@ public:
@returns The zero-based position of the item, or wxNOT_FOUND if the @returns The zero-based position of the item, or wxNOT_FOUND if the
string was not found. string was not found.
*/ */
int FindString(const wxString& string, virtual int FindString(const wxString& s, bool bCase = false) const;
bool caseSensitive = false);
//@}
// selection
// ---------
//@{
/** /**
Returns a pointer to the client data associated with the given item (if any). Sets the selection to the given item @a n or removes the selection
It is an error to call this function for a control which doesn't have untyped entirely if @a n == @c wxNOT_FOUND.
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). 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.
@param n
The string position to select, starting from zero.
@see SetString(), SetStringSelection()
*/
virtual void SetSelection(int n);
/**
Returns the index of the selected item or @c wxNOT_FOUND if no item is
selected.
@returns 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 SetSelection(), GetStringSelection()
*/
virtual int GetSelection() const;
/**
Selects the item with the specified string in the control. This doesn't
cause any command events to be emitted.
@param string
The string to select.
@returns @true if the specified string has been selected, @false if it
wasn't found in the control.
*/
bool SetStringSelection(const wxString& string);
/**
Returns the label of the selected item or an empty string if no item is
selected.
@see GetSelection()
*/
virtual wxString GetStringSelection() const;
/**
This is the same as SetSelection() and exists only because it is
slightly more natural for controls which support multiple selection.
*/
void Select(int n);
//@}
};
/**
@wxheader{ctrlsub.h}
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 (@c 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 wxItemContainer::Delete() or the entire control is cleared using
wxItemContainer::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 wxItemContainer::Append() (the version with client data
pointer) or wxItemContainer::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{ctrl}
@see wxControlWithItems, wxItemContainerImmutable
*/
class wxItemContainer : public wxItemContainerImmutable
{
public:
//@{
/**
Appends item into the control.
@param 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 @c wxLB_SORT or @c wxCB_SORT
style).
*/
int Append(const wxString& item);
/**
Appends item into the control.
@param item
String to add.
@param 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 @c wxLB_SORT or @c wxCB_SORT
style).
*/
int Append(const wxString& item, void* clientData);
/**
Appends item into the control.
@param item
String to add.
@param 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 @c wxLB_SORT or @c wxCB_SORT
style).
*/
int Append(const wxString& item, 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.
@param items
Array of strings to insert.
*/
void 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.
@param items
Array of strings to insert.
@param clientData
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);
/**
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.
@param items
Array of strings to insert.
@param clientData
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);
/**
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.
@param n
Number of items in the @a items array.
@param items
Array of strings of size @a n.
*/
void 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.
@param n
Number of items in the @a items array.
@param items
Array of strings of size @a n.
@param clientData
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);
/**
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.
@param n
Number of items in the @a items array.
@param items
Array of strings of size @a n.
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
*/
void Append(unsigned int n, const wxString* items,
wxClientData** clientData);
//@}
/**
Removes all items from the control.
Clear() also deletes the client data of the existing items if it is
owned by the control.
*/
void Clear();
/**
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.
@param n
The zero-based item index.
@see Clear()
*/
void Delete(unsigned int n);
//@{
/**
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).
@param n @param n
The zero-based position of the item. The zero-based position of the item.
@@ -124,10 +366,11 @@ public:
void* GetClientData(unsigned int n) const; void* GetClientData(unsigned int n) const;
/** /**
Returns a pointer to the client data associated with the given item (if any). Returns a pointer to the client data associated with the given item (if
It is an error to call this function for a control which doesn't have typed any). It is an error to call this function for a control which doesn't
client data at all although it is ok to call it even if the given item doesn't have typed client data at all although it is OK to call it even if the
have any client data associated with it (but other items do). given item doesn't have any client data associated with it (but other
items do).
@param n @param n
The zero-based position of the item. The zero-based position of the item.
@@ -137,145 +380,9 @@ public:
wxClientData* GetClientObject(unsigned int n) const; wxClientData* GetClientObject(unsigned int n) const;
/** /**
Returns the number of items in the control. 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
@see IsEmpty() pointers had been associated with the control items before.
*/
unsigned int GetCount() const;
/**
Returns the index of the selected item or @c wxNOT_FOUND if no item is
selected.
@returns 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 SetSelection(), GetStringSelection()
*/
int GetSelection() const;
/**
Returns the label of the item with the given index.
@param n
The zero-based index.
@returns The label of the item or an empty string if the position was
invalid.
*/
wxString GetString(unsigned int n) const;
/**
Returns the label of the selected item or an empty string if no item is
selected.
@see GetSelection()
*/
wxString GetStringSelection() const;
/**
Returns the array of the labels of all items in the control.
*/
wxArrayString GetStrings() const;
//@{
/**
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.
@param item
String to add.
@param pos
Position to insert item before, zero based.
@param stringsArray
Contains items to insert into the control content
@param strings
Array of strings of size n.
@param n
Number of items in the strings array.
@param clientData
Array of client data pointers of size n to associate with the new items.
@returns The return value is the index of the newly inserted item. If the
insertion failed for some reason, -1 is returned.
*/
int Insert(const wxString& item, unsigned int pos);
int Insert(const wxString& item, unsigned int pos,
void* clientData);
int Insert(const wxString& item, unsigned int pos,
wxClientData* clientData);
void Insert(const wxArrayString& strings, unsigned int pos);
void Insert(const wxArrayString& strings, unsigned int pos);
void Insert(unsigned int n, const wxString* strings,
unsigned int pos);
void Insert(unsigned int n, const wxString* strings,
unsigned int pos,
void** clientData);
void Insert(unsigned int n, const wxString* strings,
unsigned int pos,
wxClientData** clientData);
//@}
/**
Returns @true if the control is empty or @false if it has some items.
@see GetCount()
*/
bool IsEmpty() const;
/**
This is the same as SetSelection() and
exists only because it is slightly more natural for controls which support
multiple selection.
*/
void Select(int n);
//@{
/**
Replaces the current control contents with the given items. Notice that calling
this method is much faster than appending the items one by one if you need to
append a lot of them.
@param item
The single item to insert into the control.
@param stringsArray
Contains items to set as control content.
@param strings
Raw C++ array of strings. Only used in conjunction with 'n'.
@param n
Number of items passed in 'strings'. Only used in conjunction with
'strings'.
@param clientData
Client data to associate with the item(s).
@returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT
style) the return value could be different from
(GetCount() - 1). When setting a single item to the
container, 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).
*/
int Set(const wxString& item);
int Set(const wxString& item, void* clientData);
int Set(const wxString& item, wxClientData* clientData);
void Set(const wxArrayString& stringsArray);
void Set(unsigned int n, const wxString* strings);
void Set(unsigned int n, const wxString* strings,
void** clientData);
void Set(unsigned int n, const wxString* strings,
wxClientData** clientData);
//@}
/**
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.
@param n @param n
The zero-based item index. The zero-based item index.
@@ -286,11 +393,11 @@ public:
/** /**
Associates the given typed client data pointer with the given item: the Associates the given typed client data pointer with the given item: the
@a data object will be deleted when the item is deleted (either explicitly @a data object will be deleted when the item is deleted (either
by using @ref delete() Deletes or implicitly when the explicitly by using Delete() or implicitly when the control itself is
control itself is destroyed). destroyed). Note that it is an error to call this function if any
Note that it is an error to call this function if any untyped client data untyped client data pointers had been associated with the control items
pointers had been associated with the control items before. before.
@param n @param n
The zero-based item index. The zero-based item index.
@@ -299,39 +406,260 @@ public:
*/ */
void SetClientObject(unsigned int n, wxClientData* data); void SetClientObject(unsigned int n, wxClientData* data);
//@}
//@{
/** /**
Sets the selection to the given item @a n or removes the selection entirely Inserts item into the control.
if @a n == @c wxNOT_FOUND.
Note that this does not cause any command events to be emitted nor does it @param item
deselect any other items in the controls which support multiple selections. String to add.
@param 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.
*/
int Insert(const wxString& item, unsigned int pos);
/**
Inserts item into the control.
@param item
String to add.
@param pos
Position to insert item before, zero based.
@param 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 Insert(const wxString& item, unsigned int pos, void* clientData);
/**
Inserts item into the control.
@param item
String to add.
@param pos
Position to insert item before, zero based.
@param 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 Insert(const wxString& item, 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.
@param items
Array of strings to insert.
@param pos
Position to insert the items before, zero based.
*/
void 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.
@param items
Array of strings to insert.
@param pos
Position to insert the items before, zero based.
@param clientData
Array of client data pointers of the same size as @a items to
associate with the new items.
*/
void 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.
@param items
Array of strings to insert.
@param pos
Position to insert the items before, zero based.
@param clientData
Array of client data pointers of the same size as @a items to
associate with the new items.
*/
void 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.
@param n @param n
The string position to select, starting from zero. Number of items in the @a items array.
@param items
@see SetString(), SetStringSelection() Array of strings of size @a n.
@param pos
Position to insert the items before, zero based.
*/ */
void SetSelection(int n); void Insert(unsigned int n, const wxString* items,
unsigned int pos);
/** /**
Sets the label for the given item. 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.
@param n @param n
The zero-based item index. Number of items in the @a items array.
@param string @param items
The label to set. Array of strings of size @a n.
@param pos
Position to insert the new items before, zero based.
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
*/ */
void SetString(unsigned int n, const wxString& string); void Insert(unsigned int n, const wxString* items,
unsigned int pos,
void** clientData);
/** /**
Selects the item with the specified string in the control. This doesn't cause Inserts several items at once into the control.
any command events to be emitted.
@param string Notice that calling this method is usually much faster than inserting
The string to select. them one by one if you need to insert a lot of items.
@returns @true if the specified string has been selected, @false if it @param n
wasn't found in the control. Number of items in the @a items array.
@param items
Array of strings of size @a n.
@param pos
Position to insert the new items before, zero based.
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
*/ */
bool SetStringSelection(const wxString& string); void Insert(unsigned int n, const wxString* items,
unsigned int pos,
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.
@param items
Array of strings to insert.
*/
void 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.
@param items
Array of strings to insert.
@param clientData
Array of client data pointers of the same size as @a items to
associate with the new items.
*/
void 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.
@param items
Array of strings to insert.
@param clientData
Array of client data pointers of the same size as @a items to
associate with the new items.
*/
void 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.
@param n
Number of items in the @a items array.
@param items
Array of strings of size @a n.
*/
void 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.
@param n
Number of items in the @a items array.
@param items
Array of strings of size @a n.
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
*/
void 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.
@param n
Number of items in the @a items array.
@param items
Array of strings of size @a n.
@param clientData
Array of client data pointers of size @a n to associate with the
new items.
*/
void Set(unsigned int n, const wxString* items, 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
(wxChoice and wxListBox).
@library{wxcore}
@category{ctrl}
@see wxItemContainer, wxItemContainerImmutable
*/
class wxControlWithItems : public wxControl, public wxItemContainer
{
}; };

2
interface/radiobox.h
View File

@@ -37,7 +37,7 @@
@see @ref overview_eventhandling, wxRadioButton, wxCheckBox @see @ref overview_eventhandling, wxRadioButton, wxCheckBox
*/ */
class wxRadioBox : public wxControlWithItems class wxRadioBox : public wxControl, wxItemContainerImmutable
{ {
public: public:
//@{ //@{