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	Flags used by wxControl::Ellipsize function.
	11	*/
	12	enum wxEllipsizeFlags
	13	{
	14	/// With this flag when calculating the size of the passed string, mnemonics
	15	/// characters (see wxControl::SetLabel) will be automatically reduced to a
	16	/// single character.
	17	/// This leads to correct calculations only if the string passed to Ellipsize()
	18	/// will be used with wxControl::SetLabel. If you don't want ampersand to
	19	/// be interpreted as mnemonics (e.g. because you use wxControl::SetLabelText)
	20	/// then don't use this flag.
	21	wxELLIPSIZE_PROCESS_MNEMONICS = 1,
	22
	23	/// This flag tells wxControl::Ellipsize to calculate the width of tab
	24	/// characters @c '\\t' as 6 spaces.
	25	wxELLIPSIZE_EXPAND_TAB = 2,
	26
	27	/// The default flags for wxControl::Ellipsize.
	28	wxELLIPSIZE_DEFAULT_FLAGS = wxELLIPSIZE_PROCESS_MNEMONICS\|wxELLIPSIZE_EXPAND_TAB
	29	};
	30
	31
	32	/**
	33	The different ellipsization modes supported by the
	34	wxControl::Ellipsize function.
	35	*/
	36	enum wxEllipsizeMode
	37	{
	38	/// Put the ellipsis at the start of the string, if the string needs ellipsization.
	39	wxELLIPSIZE_START,
	40
	41	/// Put the ellipsis in the middle of the string, if the string needs ellipsization.
	42	wxELLIPSIZE_MIDDLE,
	43
	44	/// Put the ellipsis at the end of the string, if the string needs ellipsization.
	45	wxELLIPSIZE_END
	46	};
	47
	48	/**
	49	@class wxControl
	50
	51	This is the base class for a control or "widget".
	52
	53	A control is generally a small window which processes user input and/or
	54	displays one or more item of data.
	55
	56	@beginEventEmissionTable{wxClipboardTextEvent}
	57	@event{EVT_TEXT_COPY(id, func)}
	58	Some or all of the controls content was copied to the clipboard.
	59	@event{EVT_TEXT_CUT(id, func)}
	60	Some or all of the controls content was cut (i.e. copied and
	61	deleted).
	62	@event{EVT_TEXT_PASTE(id, func)}
	63	Clipboard content was pasted into the control.
	64	@endEventTable
	65
	66	@library{wxcore}
	67	@category{ctrl}
	68
	69	@see wxValidator
	70	*/
	71	class wxControl : public wxWindow
	72	{
	73	public:
	74	/**
	75	Simulates the effect of the user issuing a command to the item.
	76
	77	@see wxCommandEvent
	78	*/
	79	virtual void Command(wxCommandEvent& event);
	80
	81	/**
	82	Replaces parts of the @a label string with ellipsis, if needed, so
	83	that it doesn't exceed @a maxWidth.
	84
	85	@param label
	86	The string to ellipsize
	87	@param dc
	88	The DC used to retrieve the character widths through the
	89	wxDC::GetPartialTextExtents() function.
	90	@param mode
	91	The ellipsization modes. See ::wxEllipsizeMode.
	92	@param maxWidth
	93	The maximum width of the returned string in pixels.
	94	@param flags
	95	One or more of the ::wxEllipsize
	96	*/
	97	static wxString Ellipsize(const wxString& label, const wxDC& dc,
	98	wxEllipsizeMode mode, int maxWidth,
	99	int flags = wxELLIPSIZE_DEFAULT_FLAGS);
	100
	101	/**
	102	Returns the control's text.
	103
	104	@note The returned string contains mnemonics ("&" characters) if it has
	105	any, use GetLabelText() if they are undesired.
	106	*/
	107	wxString GetLabel() const;
	108
	109	/**
	110	Returns the control's label without mnemonics.
	111	*/
	112	wxString GetLabelText() const;
	113
	114	/**
	115	Returns the given @a label string without mnemonics ("&" characters).
	116	*/
	117	static wxString GetLabelText(const wxString& label);
	118
	119	/**
	120	Removes the mnemonics ("&" characters) from the given string.
	121	*/
	122	static wxString RemoveMnemonics(const wxString& str);
	123
	124	/**
	125	Escape the special mnemonics characters ("&") in the given string.
	126
	127	This function can be helpful if you need to set the controls label to a
	128	user-provided string. If the string contains ampersands, they wouldn't
	129	appear on the display but be used instead to indicate that the
	130	character following the first of them can be used as a control mnemonic.
	131	While this can sometimes be desirable (e.g. to allow the user to
	132	configure mnemonics of the controls), more often you will want to use
	133	this function before passing a user-defined string to SetLabel().
	134	Alternatively, if the label is entirely user-defined, you can just call
	135	SetLabelText() directly -- but this function must be used if the label
	136	is a combination of a part defined by program containing the control
	137	mnemonics and a user-defined part.
	138
	139	@param text
	140	The string such as it should appear on the display.
	141	@return
	142	The same string with the ampersands in it doubled.
	143	*/
	144	static wxString EscapeMnemonics(const wxString& text);
	145
	146	/**
	147	Sets the item's text.
	148
	149	Any "&" characters in the @a label are special and indicate that the
	150	following character is a @e mnemonic for this control and can be used to
	151	activate it from the keyboard (typically by using @e Alt key in
	152	combination with it). To insert a literal ampersand character, you need
	153	to double it, i.e. use use "&&". If this behaviour is undesirable, use
	154	SetLabelText() instead.
	155	*/
	156	void SetLabel(const wxString& label);
	157
	158	/**
	159	Sets the item's text to exactly the given string.
	160
	161	Unlike SetLabel(), this function shows exactly the @a text passed to it
	162	in the control, without interpreting ampersands in it in any way.
	163	Notice that it means that the control can't have any mnemonic defined
	164	for it using this function.
	165
	166	@see EscapeMnemonics()
	167	*/
	168	void SetLabelText(const wxString& text);
	169	};
	170