From: Václav Slavík Date: Fri, 11 Apr 2008 22:12:31 +0000 (+0000) Subject: Added documentation for wxItemContainer class; moved methods docs X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/bf84f3e207e19a6b921d01f74cb082cc442251ab?ds=inline Added documentation for wxItemContainer class; moved methods docs 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 --- diff --git a/interface/combobox.h b/interface/combobox.h index 62860ed93e..73ef4ad6a9 100644 --- a/interface/combobox.h +++ b/interface/combobox.h @@ -59,7 +59,7 @@ @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent */ -class wxComboBox : public wxControlWithItems +class wxComboBox : public wxControl, public wxItemContainer { public: //@{ diff --git a/interface/ctrlsub.h b/interface/ctrlsub.h index 3ac1b3a452..efe7d939c8 100644 --- a/interface/ctrlsub.h +++ b/interface/ctrlsub.h @@ -6,95 +6,75 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + /** - @class wxControlWithItems @wxheader{ctrlsub.h} - This class is an abstract base class for some wxWidgets controls which contain - several items such as wxListBox, wxCheckListBox, wxChoice and wxComboBox derive - from it. - + wxItemContainer defines an interface which is implemented by all controls + which have string subitems each of which may be selected. - 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. + It is decomposed in wxItemContainerImmutable which omits all methods + adding/removing items and is used by wxRadioBox and wxItemContainer itself. - 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 (@c void *) pointers which are simply - stored by the control but not used in any way by it, or typed pointers - (@c 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 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. + Note that this is not a control, it's a mixin interface that classes + have to derive from in addition to wxControl or wxWindow. + + Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which + implements an extended interface deriving from this one) @library{wxcore} - @category{controls} + @category{ctrl} - @see wxControlWithItems::Clear + @see wxControlWithItems, wxItemContainer */ -class wxControlWithItems : public wxControl +class wxItemContainerImmutable { 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. + Returns the number of items in the control. + + @see IsEmpty() + */ + 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 item - String to add. - @param stringsArray - Contains items to append to the control. - @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. + The zero-based index. - @returns 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). + @returns The label of the item or an empty string if the position was + invalid. */ - int Append(const wxString& item); - 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); - //@} + virtual wxString GetString(unsigned int n) const; /** - Removes all items from the control. - @e Clear() also deletes the client data of the existing items if it is owned - by the control. + Returns the array of the labels of all items in the control. */ - void Clear(); + wxArrayString GetStrings() const; /** - 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. + Sets the label for the given item. @param n The zero-based item index. - - @see Clear() + @param string + 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. @@ -107,41 +87,28 @@ public: @returns The zero-based position of the item, or wxNOT_FOUND if the string was not found. */ - int FindString(const wxString& string, - bool caseSensitive = false); - - /** - 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). + virtual int FindString(const wxString& s, bool bCase = false) const; - @param n - The zero-based position of the item. + //@} - @returns A pointer to the client data, or @NULL if not present. - */ - void* GetClientData(unsigned int n) const; + // selection + // --------- + //@{ /** - 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). + Sets the selection to the given item @a n or removes the selection + entirely if @a n == @c wxNOT_FOUND. - @param n - The zero-based position of the item. - - @returns A pointer to the client data, or @NULL if not present. - */ - wxClientData* GetClientObject(unsigned int n) const; + 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. - /** - Returns the number of items in the control. + @param n + The string position to select, starting from zero. - @see IsEmpty() + @see SetString(), SetStringSelection() */ - unsigned int GetCount() const; + virtual void SetSelection(int n); /** Returns the index of the selected item or @c wxNOT_FOUND if no item is @@ -150,23 +117,24 @@ public: @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 + you should use wxListBox::GetSelections() for the list boxes with wxLB_MULTIPLE style. @see SetSelection(), GetStringSelection() */ - int GetSelection() const; + virtual int GetSelection() const; /** - Returns the label of the item with the given index. + Selects the item with the specified string in the control. This doesn't + cause any command events to be emitted. - @param n - The zero-based index. + @param string + The string to select. - @returns The label of the item or an empty string if the position was - invalid. + @returns @true if the specified string has been selected, @false if it + wasn't found in the control. */ - wxString GetString(unsigned int n) const; + bool SetStringSelection(const wxString& string); /** Returns the label of the selected item or an empty string if no item is @@ -174,108 +142,247 @@ public: @see GetSelection() */ - wxString GetStringSelection() const; + virtual wxString GetStringSelection() const; /** - Returns the array of the labels of all items in the control. + This is the same as SetSelection() and exists only because it is + slightly more natural for controls which support multiple selection. */ - wxArrayString GetStrings() const; + 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: //@{ + /** - 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. + 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 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. + 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. + @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 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, + 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); - void Insert(unsigned int n, const wxString* strings, - unsigned int pos, + + /** + 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); //@} /** - Returns @true if the control is empty or @false if it has some items. - - @see GetCount() + Removes all items from the control. + Clear() also deletes the client data of the existing items if it is + owned by the control. */ - bool IsEmpty() const; + void Clear(); /** - This is the same as SetSelection() and - exists only because it is slightly more natural for controls which support - multiple selection. + 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 Select(int n); + void Delete(unsigned 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. + 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 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). + The zero-based position of the item. + + @returns A pointer to the client data, or @NULL if not present. */ - 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); - //@} + 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 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). + + @param n + The zero-based position of the item. + + @returns A pointer to the client data, or @NULL if not present. + */ + wxClientData* GetClientObject(unsigned int n) const; /** - 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. + 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 The zero-based item index. @@ -286,11 +393,11 @@ public: /** 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 - by using @ref delete() 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. + @a 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. @param n The zero-based item index. @@ -299,39 +406,260 @@ public: */ void SetClientObject(unsigned int n, wxClientData* data); + //@} + + //@{ + + /** + Inserts item into the control. + + @param item + 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); + /** - Sets the selection to the given item @a n or removes the selection entirely - if @a n == @c 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. + 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 - The string position to select, starting from zero. + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param pos + Position to insert the items before, zero based. + */ + void Insert(unsigned int n, const wxString* items, + unsigned int pos); - @see SetString(), SetStringSelection() + /** + 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 + 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. */ - void SetSelection(int n); + void Insert(unsigned int n, const wxString* items, + unsigned int pos, + void** clientData); /** - 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 - The zero-based item index. - @param string - The label to set. + 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. */ - void SetString(unsigned int n, const wxString& string); + void Insert(unsigned int n, const wxString* items, + unsigned int pos, + wxClientData** clientData); + //@} + //@{ /** - Selects the item with the specified string in the control. This doesn't cause - any command events to be emitted. + Replaces the current control contents with the given items. - @param string - The string to select. + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. - @returns @true if the specified string has been selected, @false if it - wasn't found in the control. + @param items + Array of strings to insert. */ - bool SetStringSelection(const wxString& string); + 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 +{ }; diff --git a/interface/radiobox.h b/interface/radiobox.h index d6173e4327..7085f562e5 100644 --- a/interface/radiobox.h +++ b/interface/radiobox.h @@ -37,7 +37,7 @@ @see @ref overview_eventhandling, wxRadioButton, wxCheckBox */ -class wxRadioBox : public wxControlWithItems +class wxRadioBox : public wxControl, wxItemContainerImmutable { public: //@{