X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..de536319f16406adf967003637b2655c61f6cb09:/interface/ctrlsub.h diff --git a/interface/ctrlsub.h b/interface/ctrlsub.h index f0211eef44..f540761470 100644 --- a/interface/ctrlsub.h +++ b/interface/ctrlsub.h @@ -1,355 +1,665 @@ ///////////////////////////////////////////////////////////////////////////// // Name: ctrlsub.h -// Purpose: documentation for wxControlWithItems class +// Purpose: interface of wxControlWithItems // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + /** - @class wxControlWithItems + @class wxItemContainerImmutable @wxheader{ctrlsub.h} - 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. + 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 - @ref wxControlWithItems::delete deleted or the entire control is - @ref wxControlWithItems::clear 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 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{FIXME} + @category{ctrl} - @seealso - 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. - - @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. - - @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 number of items in the control. + + @see IsEmpty() */ - 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 unsigned int GetCount() 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 @true if the control is empty or @false if it has some items. + + @see GetCount() */ - void Clear(); + bool IsEmpty() 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. - + Returns the label of the item with the given index. + @param n - The zero-based item index. - - @sa Clear() + The zero-based index. + + @return The label of the item or an empty string if the position was + invalid. */ - void Delete(unsigned int n); + virtual wxString GetString(unsigned int n) const; /** - Finds an item whose label matches the given string. - - @param string - String to find. - - @param caseSensitive - Whether search is case sensitive (default is not). - - @returns The zero-based position of the item, or wxNOT_FOUND if the - string was not found. + Returns the array of the labels of all items in the control. */ - int FindString(const wxString& string, - bool caseSensitive = @false); + wxArrayString GetStrings() 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). - + Sets the label for the given item. + @param n - The zero-based position of the item. - - @returns A pointer to the client data, or @NULL if not present. + The zero-based item index. + @param string + The label to set. */ - void * GetClientData(unsigned int n); + virtual void SetString(unsigned int n, const wxString& s); /** - 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. + Finds an item whose label matches the given string. + + @param string + String to find. + @param caseSensitive + Whether search is case sensitive (default is not). + + @return The zero-based position of the item, or wxNOT_FOUND if the + string was not found. */ - wxClientData * GetClientObject(unsigned int n); + virtual int FindString(const wxString& s, bool bCase = false) const; + + //@} + + /// @name Selection + //@{ /** - Returns the number of items in the control. - - @sa IsEmpty() + 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. + + @param n + The string position to select, starting from zero. + + @see SetString(), SetStringSelection() */ - unsigned int GetCount(); + 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. - + + @return 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. - - @sa SetSelection(), GetStringSelection() + you should use wxListBox::GetSelections() for the list + boxes with wxLB_MULTIPLE style. + + @see SetSelection(), GetStringSelection() */ - int GetSelection(); + virtual 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. + 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. + + @return @true if the specified string has been selected, @false if it + wasn't found in the control. */ - wxString GetString(unsigned int n); + bool SetStringSelection(const wxString& string); /** Returns the label of the selected item or an empty string if no item is selected. - - @sa GetSelection() + + @see GetSelection() */ - wxString GetStringSelection(); + 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(); + void Select(int n); + + //@} +}; + + +/** + @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 + 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 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{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. - - @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. - + String to add. + + @return 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. + + @return 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. + + @return 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 strings array. - + 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 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. + Array of client data pointers of size @a n to associate with the + new items. */ - 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); + 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); //@} /** - Returns @true if the control is empty or @false if it has some items. - - @sa 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(); + 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. - - @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'. - + 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 - 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); - //@} + The zero-based position of the item. + + @return A pointer to the client data, or @NULL if not present. + */ + void* GetClientData(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. - + 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 item index. - + The zero-based position of the item. + + @return 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. + + @param n + The zero-based item index. @param data - The client data to associate with the item. + The client data to associate with the item. */ - void SetClientData(unsigned int n, void * data); + void SetClientData(unsigned int n, void* data); /** Associates the given typed client data pointer with the given item: the - @e 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. - + The zero-based item index. @param data - The client data to associate with the item. + The client data to associate with the item. + */ + 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. + + @return 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. + + @return 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. + + @return 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 + 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 SetClientObject(unsigned int n, wxClientData * data); + void Insert(unsigned int n, const wxString* items, + unsigned int pos); /** - Sets the selection to the given item @e n or removes the selection entirely - if @e 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 n - The string position to select, starting from zero. - - @sa SetString(), SetStringSelection() + 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. - - @param string - The string to select. - - @returns @true if the specified string has been selected, @false if it - wasn't found in the control. + 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. */ - 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 +{ +}; +