git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: control.h
	3	// Purpose: interface of wxControl
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	The different ellipsization modes supported by the
	11	wxControl::Ellipsize function.
	12	*/
	13	enum wxEllipsizeMode
	14	{
	15	wxELLIPSIZE_START,
	16	wxELLIPSIZE_MIDDLE,
	17	wxELLIPSIZE_END
	18	};
	19
	20	/**
	21	@class wxControl
	22
	23	This is the base class for a control or "widget".
	24
	25	A control is generally a small window which processes user input and/or
	26	displays one or more item of data.
	27
	28	@library{wxcore}
	29	@category{ctrl}
	30
	31	@see wxValidator
	32	*/
	33	class wxControl : public wxWindow
	34	{
	35	public:
	36	/**
	37	Simulates the effect of the user issuing a command to the item.
	38
	39	@see wxCommandEvent
	40	*/
	41	virtual void Command(wxCommandEvent& event);
	42
	43	/**
	44	Replaces parts of the @a label string with ellipsis, if needed, so
	45	that it doesn't exceed @a maxWidth.
	46
	47	@param label
	48	The string to ellipsize
	49	@param dc
	50	The DC used to retrieve the character widths through the
	51	wxDC::GetPartialTextExtents() function.
	52	@param mode
	53	The ellipsization modes. See ::wxEllipsizeMode.
	54	@param maxWidth
	55	The maximum width of the returned string in pixels.
	56	*/
	57	static wxString Ellipsize(const wxString& label, const wxDC& dc,
	58	wxEllipsizeMode mode, int maxWidth);
	59
	60	/**
	61	Returns the control's text.
	62
	63	@note The returned string contains mnemonics ("&" characters) if it has
	64	any, use GetLabelText() if they are undesired.
	65	*/
	66	wxString GetLabel() const;
	67
	68	/**
	69	Returns the control's label without mnemonics.
	70	*/
	71	wxString GetLabelText() const;
	72
	73	/**
	74	Returns the given @a label string without mnemonics ("&" characters).
	75	*/
	76	static wxString GetLabelText(const wxString& label);
	77
	78	/**
	79	Removes the mnemonics ("&" characters) from the given string.
	80	*/
	81	static wxString RemoveMnemonics(const wxString& str);
	82
	83	/**
	84	Escape the special mnemonics characters ("&") in the given string.
	85
	86	This function can be helpful if you need to set the controls label to a
	87	user-provided string. If the string contains ampersands, they wouldn't
	88	appear on the display but be used instead to indicate that the
	89	character following the first of them can be used as a control mnemonic.
	90	While this can sometimes be desirable (e.g. to allow the user to
	91	configure mnemonics of the controls), more often you will want to use
	92	this function before passing a user-defined string to SetLabel().
	93	Alternatively, if the label is entirely user-defined, you can just call
	94	SetLabelText() directly -- but this function must be used if the label
	95	is a combination of a part defined by program containing the control
	96	mnemonics and a user-defined part.
	97
	98	@param text
	99	The string such as it should appear on the display.
	100	@return
	101	The same string with the ampersands in it doubled.
	102	*/
	103	static wxString EscapeMnemonics(const wxString& text);
	104
	105	/**
	106	Sets the item's text.
	107
	108	Any "&" characters in the @a label are special and indicate that the
	109	following character is a @e mnemonic for this control and can be used to
	110	activate it from the keyboard (typically by using @e Alt key in
	111	combination with it). To insert a literal ampersand character, you need
	112	to double it, i.e. use use "&&". If this behaviour is undesirable, use
	113	SetLabelText() instead.
	114	*/
	115	void SetLabel(const wxString& label);
	116
	117	/**
	118	Sets the item's text to exactly the given string.
	119
	120	Unlike SetLabel(), this function shows exactly the @a text passed to it
	121	in the control, without interpreting ampersands in it in any way.
	122	Notice that it means that the control can't have any mnemonic defined
	123	for it using this function.
	124
	125	@see EscapeMnemonics()
	126	*/
	127	void SetLabelText(const wxString& text);
	128	};
	129