[wxWidgets.git] / interface / ctrlsub.h

/////////////////////////////////////////////////////////////////////////////
// Name:        ctrlsub.h
// Purpose:     documentation for wxControlWithItems class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// 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 and
    wxCheckListBox derived from it,
    wxChoice and wxComboBox.

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

    @library{wxcore}
    @category{FIXME}

    @seealso
    wxControlWithItems::Clear
*/
class wxControlWithItems : public wxControl
{
public:
    //@{
    /**
        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).
    */
    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);
    //@}

    /**
        Removes all items from the control.
        
        @e 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.
        
        @sa Clear()
    */
    void Delete(unsigned int n);

    /**
        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.
    */
    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).
        
        @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);

    /**
        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);

    /**
        Returns the number of items in the control.
        
        @sa IsEmpty()
    */
    unsigned int GetCount();

    /**
        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.
        
        @sa SetSelection(), GetStringSelection()
    */
    int GetSelection();

    /**
        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);

    /**
        Returns the label of the selected item or an empty string if no item is
        selected.
        
        @sa GetSelection()
    */
    wxString GetStringSelection();

    /**
        Returns the array of the labels of all items in the control.
    */
    wxArrayString GetStrings();

    //@{
    /**
        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.
        
        @sa GetCount()
    */
    bool IsEmpty();

    /**
        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
        The zero-based item index.
        
        @param data
        The client data to associate with the item.
    */
    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.
        
        @param n
        The zero-based item index.
        
        @param data
        The client data to associate with the item.
    */
    void SetClientObject(unsigned int n, wxClientData * data);

    /**
        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.
        
        @param n
        The string position to select, starting from zero.
        
        @sa SetString(), SetStringSelection()
    */
    void SetSelection(int n);

    /**
        Sets the label for the given item.
        
        @param n
        The zero-based item index.
        
        @param string
        The label to set.
    */
    void SetString(unsigned int n, const wxString& string);

    /**
        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);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: ctrlsub.h
	3	// Purpose: documentation for wxControlWithItems class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxControlWithItems
	11	@wxheader{ctrlsub.h}
7c913512	12
23324ae1 FM	13	This class is an abstract base class for some wxWidgets controls which contain
	14	several items, such as wxListBox and
	15	wxCheckListBox derived from it,
	16	wxChoice and wxComboBox.
7c913512	17
23324ae1 FM	18	It defines the methods for accessing the controls items and although each of
	19	the derived classes implements them differently, they still all conform to the
	20	same interface.
7c913512	21
23324ae1 FM	22	The items in a wxControlWithItems have (non-empty) string labels and,
	23	optionally, client data associated with them. Client data may be of two
	24	different kinds: either simple untyped (@c void *) pointers which are simply
	25	stored by the control but not used in any way by it, or typed pointers
	26	(@c wxClientData *) which are owned by the control meaning that the typed
	27	client data (and only it) will be deleted when an item is
	28	@ref wxControlWithItems::delete deleted or the entire control is
	29	@ref wxControlWithItems::clear cleared (which also happens when it is
	30	destroyed). Finally note that in the same control all items must have client
	31	data of the same type (typed or untyped), if any. This type is determined by
	32	the first call to wxControlWithItems::Append (the version with
	33	client data pointer) or wxControlWithItems::SetClientData.
7c913512	34
23324ae1 FM	35	@library{wxcore}
23324ae1 FM	36	@category{FIXME}
7c913512	37
23324ae1 FM	38	@seealso
	39	wxControlWithItems::Clear
	40	*/
	41	class wxControlWithItems : public wxControl
	42	{
	43	public:
	44	//@{
	45	/**
	46	Appends several items at once to the control. Notice that calling this method
	47	is usually much faster than appending them one by one if you need to add a lot
	48	of items.
	49
7c913512	50	@param item
23324ae1 FM	51	String to add.
23324ae1 FM	52
7c913512	53	@param stringsArray
23324ae1 FM	54	Contains items to append to the control.
23324ae1 FM	55
7c913512	56	@param strings
23324ae1 FM	57	Array of strings of size n.
23324ae1 FM	58
7c913512	59	@param n
23324ae1 FM	60	Number of items in the strings array.
23324ae1 FM	61
7c913512	62	@param clientData
23324ae1 FM	63	Array of client data pointers of size n to associate with the new items.
	64
	65	@returns When appending a single item, the return value is the index of
	66	the newly added item which may be different from the
	67	last one if the control is sorted (e.g. has wxLB_SORT
	68	or wxCB_SORT style).
	69	*/
	70	int Append(const wxString& item);
7c913512 FM	71	int Append(const wxString& item, void * clientData);
	72	int Append(const wxString& item, wxClientData * clientData);
	73	void Append(const wxArrayString& strings);
	74	void Append(unsigned int n, const wxString* strings);
	75	void Append(unsigned int n, const wxString* strings,
	76	void ** clientData);
	77	void Append(unsigned int n, const wxString* strings,
	78	wxClientData ** clientData);
23324ae1 FM	79	//@}
	80
	81	/**
	82	Removes all items from the control.
	83
	84	@e Clear() also deletes the client data of the existing items if it is owned
	85	by the control.
	86	*/
	87	void Clear();
	88
	89	/**
	90	Deletes an item from the control. The client data associated with the item
	91	will be also deleted if it is owned by the control.
	92
	93	Note that it is an error (signalled by an assert failure in debug builds) to
	94	remove an item with the index negative or greater or equal than the number of
	95	items in the control.
	96
7c913512	97	@param n
23324ae1 FM	98	The zero-based item index.
	99
	100	@sa Clear()
	101	*/
	102	void Delete(unsigned int n);
	103
	104	/**
	105	Finds an item whose label matches the given string.
	106
7c913512	107	@param string
23324ae1 FM	108	String to find.
23324ae1 FM	109
7c913512	110	@param caseSensitive
23324ae1 FM	111	Whether search is case sensitive (default is not).
	112
	113	@returns The zero-based position of the item, or wxNOT_FOUND if the
	114	string was not found.
	115	*/
	116	int FindString(const wxString& string,
	117	bool caseSensitive = @false);
	118
	119	/**
	120	Returns a pointer to the client data associated with the given item (if any).
	121	It is an error to call this function for a control which doesn't have untyped
	122	client data at all although it is ok to call it even if the given item doesn't
	123	have any client data associated with it (but other items do).
	124
7c913512	125	@param n
23324ae1 FM	126	The zero-based position of the item.
	127
	128	@returns A pointer to the client data, or @NULL if not present.
	129	*/
	130	void * GetClientData(unsigned int n);
	131
	132	/**
	133	Returns a pointer to the client data associated with the given item (if any).
	134	It is an error to call this function for a control which doesn't have typed
	135	client data at all although it is ok to call it even if the given item doesn't
	136	have any client data associated with it (but other items do).
	137
7c913512	138	@param n
23324ae1 FM	139	The zero-based position of the item.
	140
	141	@returns A pointer to the client data, or @NULL if not present.
	142	*/
	143	wxClientData * GetClientObject(unsigned int n);
	144
	145	/**
	146	Returns the number of items in the control.
	147
	148	@sa IsEmpty()
	149	*/
	150	unsigned int GetCount();
	151
	152	/**
	153	Returns the index of the selected item or @c wxNOT_FOUND if no item is
	154	selected.
	155
	156	@returns The position of the current selection.
	157
	158	@remarks This method can be used with single selection list boxes only,
	159	you should use wxListBox::GetSelections for the list
	160	boxes with wxLB_MULTIPLE style.
	161
	162	@sa SetSelection(), GetStringSelection()
	163	*/
	164	int GetSelection();
	165
	166	/**
	167	Returns the label of the item with the given index.
	168
7c913512	169	@param n
23324ae1 FM	170	The zero-based index.
	171
	172	@returns The label of the item or an empty string if the position was
	173	invalid.
	174	*/
	175	wxString GetString(unsigned int n);
	176
	177	/**
	178	Returns the label of the selected item or an empty string if no item is
	179	selected.
	180
	181	@sa GetSelection()
	182	*/
	183	wxString GetStringSelection();
	184
	185	/**
	186	Returns the array of the labels of all items in the control.
	187	*/
	188	wxArrayString GetStrings();
	189
	190	//@{
	191	/**
	192	Inserts several items at once into the control. Notice that calling this method
	193	is usually much faster than inserting them one by one if you need to insert a
	194	lot
	195	of items.
	196
7c913512	197	@param item
23324ae1 FM	198	String to add.
23324ae1 FM	199
7c913512	200	@param pos
23324ae1 FM	201	Position to insert item before, zero based.
23324ae1 FM	202
7c913512	203	@param stringsArray
23324ae1 FM	204	Contains items to insert into the control content
23324ae1 FM	205
7c913512	206	@param strings
23324ae1 FM	207	Array of strings of size n.
23324ae1 FM	208
7c913512	209	@param n
23324ae1 FM	210	Number of items in the strings array.
23324ae1 FM	211
7c913512	212	@param clientData
23324ae1 FM	213	Array of client data pointers of size n to associate with the new items.
	214
	215	@returns The return value is the index of the newly inserted item. If the
	216	insertion failed for some reason, -1 is returned.
	217	*/
	218	int Insert(const wxString& item, unsigned int pos);
7c913512 FM	219	int Insert(const wxString& item, unsigned int pos,
	220	void * clientData);
	221	int Insert(const wxString& item, unsigned int pos,
	222	wxClientData * clientData);
	223	void Insert(const wxArrayString& strings, unsigned int pos);
	224	void Insert(const wxArrayString& strings, unsigned int pos);
	225	void Insert(unsigned int n, const wxString* strings,
	226	unsigned int pos);
	227	void Insert(unsigned int n, const wxString* strings,
	228	unsigned int pos,
	229	void ** clientData);
	230	void Insert(unsigned int n, const wxString* strings,
	231	unsigned int pos,
	232	wxClientData ** clientData);
23324ae1 FM	233	//@}
	234
	235	/**
	236	Returns @true if the control is empty or @false if it has some items.
	237
	238	@sa GetCount()
	239	*/
	240	bool IsEmpty();
	241
	242	/**
	243	This is the same as SetSelection() and
	244	exists only because it is slightly more natural for controls which support
	245	multiple selection.
	246	*/
	247	void Select(int n);
	248
	249	//@{
	250	/**
	251	Replaces the current control contents with the given items. Notice that calling
	252	this method is much faster than appending the items one by one if you need to
	253	append a lot of them.
	254
7c913512	255	@param item
23324ae1 FM	256	The single item to insert into the control.
23324ae1 FM	257
7c913512	258	@param stringsArray
23324ae1 FM	259	Contains items to set as control content.
23324ae1 FM	260
7c913512	261	@param strings
23324ae1 FM	262	Raw C++ array of strings. Only used in conjunction with 'n'.
23324ae1 FM	263
7c913512	264	@param n
23324ae1 FM	265	Number of items passed in 'strings'. Only used in conjunction with 'strings'.
23324ae1 FM	266
7c913512	267	@param clientData
23324ae1 FM	268	Client data to associate with the item(s).
	269
	270	@returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT
	271	style) the return value could be different from
	272	(GetCount() - 1). When setting a single item to the
	273	container, the return value is the index of the newly
	274	added item which may be different from the last one
	275	if the control is sorted (e.g. has wxLB_SORT or
	276	wxCB_SORT style).
	277	*/
	278	int Set(const wxString& item);
7c913512 FM	279	int Set(const wxString& item, void * clientData);
	280	int Set(const wxString& item, wxClientData * clientData);
	281	void Set(const wxArrayString& stringsArray);
	282	void Set(unsigned int n, const wxString* strings);
	283	void Set(unsigned int n, const wxString* strings,
	284	void ** clientData);
	285	void Set(unsigned int n, const wxString* strings,
	286	wxClientData ** clientData);
23324ae1 FM	287	//@}
	288
	289	/**
	290	Associates the given untyped client data pointer with the given item. Note that
	291	it is an error to call this function if any typed client data pointers had been
	292	associated with the control items before.
	293
7c913512	294	@param n
23324ae1 FM	295	The zero-based item index.
23324ae1 FM	296
7c913512	297	@param data
23324ae1 FM	298	The client data to associate with the item.
	299	*/
	300	void SetClientData(unsigned int n, void * data);
	301
	302	/**
	303	Associates the given typed client data pointer with the given item: the
	304	@e data object will be deleted when the item is deleted (either explicitly
	305	by using @ref delete() Deletes or implicitly when the
	306	control itself is destroyed).
	307
	308	Note that it is an error to call this function if any untyped client data
	309	pointers had been associated with the control items before.
	310
7c913512	311	@param n
23324ae1 FM	312	The zero-based item index.
23324ae1 FM	313
7c913512	314	@param data
23324ae1 FM	315	The client data to associate with the item.
	316	*/
	317	void SetClientObject(unsigned int n, wxClientData * data);
	318
	319	/**
	320	Sets the selection to the given item @e n or removes the selection entirely
	321	if @e n == @c wxNOT_FOUND.
	322
	323	Note that this does not cause any command events to be emitted nor does it
	324	deselect any other items in the controls which support multiple selections.
	325
7c913512	326	@param n
23324ae1 FM	327	The string position to select, starting from zero.
	328
	329	@sa SetString(), SetStringSelection()
	330	*/
	331	void SetSelection(int n);
	332
	333	/**
	334	Sets the label for the given item.
	335
7c913512	336	@param n
23324ae1 FM	337	The zero-based item index.
23324ae1 FM	338
7c913512	339	@param string
23324ae1 FM	340	The label to set.
	341	*/
	342	void SetString(unsigned int n, const wxString& string);
	343
	344	/**
	345	Selects the item with the specified string in the control. This doesn't cause
	346	any command events to be emitted.
	347
7c913512	348	@param string
23324ae1 FM	349	The string to select.
	350
	351	@returns @true if the specified string has been selected, @false if it
	352	wasn't found in the control.
	353	*/
	354	bool SetStringSelection(const wxString& string);
	355	};