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

... / ...

Commit	Line	Data
	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: interface/wx/richtooltip.h
	3	// Purpose: wxRichToolTip class documentation
	4	// Author: Vadim Zeitlin
	5	// Created: 2011-10-18
	6	// Copyright: (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
	7	// Licence: wxWindows licence
	8	///////////////////////////////////////////////////////////////////////////////
	9
	10	/**
	11	Support tip kinds for wxRichToolTip.
	12
	13	This enum describes the kind of the tip shown which combines both the tip
	14	position and appearance because the two are related (when the tip is
	15	positioned asymmetrically, a right handed triangle is used but an
	16	equilateral one when it's in the middle of a side).
	17
	18	Automatic selects the tip appearance best suited for the current platform
	19	and the position best suited for the window the tooltip is shown for, i.e.
	20	chosen in such a way that the tooltip is always fully on screen.
	21
	22	Other values describe the position of the tooltip itself, not the window it
	23	relates to. E.g. wxTipKind_Top places the tip on the top of the tooltip and
	24	so the tooltip itself is located beneath its associated window.
	25	*/
	26	enum wxTipKind
	27	{
	28	/// Don't show any tip, the tooltip will be (roughly) rectangular.
	29	wxTipKind_None,
	30	/// Show a right triangle tip in the top left corner of the tooltip.
	31	wxTipKind_TopLeft,
	32	/// Show an equilateral triangle tip in the middle of the tooltip top side.
	33	wxTipKind_Top,
	34	/// Show a right triangle tip in the top right corner of the tooltip.
	35	wxTipKind_TopRight,
	36	/// Show a right triangle tip in the bottom left corner of the tooltip.
	37	wxTipKind_BottomLeft,
	38	/// Show an equilateral triangle tip in the middle of the tooltip bottom side.
	39	wxTipKind_Bottom,
	40	/// Show a right triangle tip in the bottom right corner of the tooltip.
	41	wxTipKind_BottomRight,
	42	/**
	43	Choose the appropriate tip shape and position automatically.
	44
	45	This is the default and shouldn't normally need to be changed.
	46
	47	Notice that currently wxTipKind_Top or wxTipKind_Bottom are used under
	48	Mac while one of the other four values is selected for the other
	49	platforms.
	50	*/
	51	wxTipKind_Auto
	52	};
	53	/**
	54	Allows to show a tool tip with more customizations than wxToolTip.
	55
	56	Using this class is very simple, to give a standard warning for a password
	57	text control if the password was entered correctly you could simply do:
	58	@code
	59	wxTextCtrl* password = new wxTextCtrl(..., wxTE_PASSWORD);
	60	...
	61	wxRichToolTip tip("Caps Lock is on",
	62	"You might have made an error in your password\n"
	63	"entry because Caps Lock is turned on.\n"
	64	"\n"
	65	"Press Caps Lock key to turn it off.");
	66	tip.SetIcon(wxICON_WARNING);
	67	tip.ShowFor(password);
	68	@endcode
	69
	70	Currently this class has generic implementation that can be used with any
	71	window and implements all the functionality but doesn't exactly match the
	72	appearance of the native tooltips (even though it makes some efforts to
	73	use the style most appropriate for the current platform) and a native MSW
	74	version which can be only used with text controls and doesn't provide as
	75	much in the way of customization. Because of this, it's inadvisable to
	76	customize the tooltips unnecessarily as doing this turns off auto-detection
	77	of the native style in the generic version and may prevent the native MSW
	78	version from being used at all.
	79
	80	Notice that this class is not derived from wxWindow and hence doesn't
	81	represent a window, even if its ShowFor() method does create one internally
	82	to show the tooltip.
	83
	84	The images below show some examples of rich tooltips on different
	85	platforms, with various customizations applied.
	86
	87	@library{wxadv}
	88	@category{miscwnd}
	89	@appearance{richtooltip}
	90
	91	@since 2.9.3
	92	*/
	93	class wxRichToolTip
	94	{
	95	public:
	96	/**
	97	Constructor must specify the tooltip title and main message.
	98
	99	The main message can contain embedded new lines. Both the title and
	100	message must be non-empty.
	101
	102	Additional attributes can be set later.
	103	*/
	104	wxRichToolTip(const wxString& title, const wxString& message);
	105
	106	/**
	107	Set the background colour.
	108
	109	If two colours are specified, the background is drawn using a gradient
	110	from top to bottom, otherwise a single solid colour is used.
	111
	112	By default the colour or colours most appropriate for the current
	113	platform are used. If a colour is explicitly set, native MSW version
	114	won't be used as it doesn't support setting the colour.
	115	*/
	116	void SetBackgroundColour(const wxColour& col,
	117	const wxColour& colEnd = wxColour());
	118
	119	/**
	120	Set the small icon to show.
	121
	122	The icon can be either one of the standard information/warning/error
	123	ones, i.e. wxICON_INFORMATION, wxICON_WARNING or wxICON_ERROR
	124	respectively (the question icon doesn't make sense for a tooltip so
	125	wxICON_QUESTION can't be used here) or a custom icon. The latter is
	126	unsupported by the native MSW implementation of this class so the use
	127	of a standard icon is preferred.
	128	*/
	129	//@{
	130	void SetIcon(int icon = wxICON_INFORMATION);
	131	void SetIcon(const wxIcon& icon);
	132	//@}
	133
	134	/**
	135	Set timeout after which the tooltip should disappear and
	136	optionally set a delay before the tooltip is shown, in milliseconds.
	137
	138	By default the tooltip is shown immediately and hidden after a
	139	system-dependent interval of time elapses. This method can be used to
	140	change this or also disable hiding the tooltip automatically entirely
	141	by passing 0 in this parameter (but doing this will prevent the native
	142	MSW version from being used).
	143
	144	Notice that the tooltip will always be hidden if the user presses a key
	145	or clicks a mouse button.
	146
	147	Parameter @a millisecondsDelay is new since wxWidgets 2.9.5.
	148	*/
	149	void SetTimeout(unsigned millisecondsTimeout, unsigned millisecondsDelay = 0);
	150
	151	/**
	152	Choose the tip kind, possibly none.
	153
	154	See wxTipKind documentation for the possible choices here.
	155
	156	By default the tip is positioned automatically, as if wxTipKind_Auto
	157	was used. Native MSW implementation doesn't support setting the tip
	158	kind explicitly and won't be used if this method is called with any
	159	value other than wxTipKind_Auto.
	160
	161	Notice that using non automatic tooltip kind may result in the tooltip
	162	being positioned partially off screen and it's the callers
	163	responsibility to ensure that this doesn't happen in this case.
	164	*/
	165	void SetTipKind(wxTipKind tipKind);
	166
	167	/**
	168	Set the title text font.
	169
	170	By default it's emphasized using the font style or colour appropriate
	171	for the current platform. Calling this method prevents the native MSW
	172	implementation from being used as it doesn't support changing the font.
	173	*/
	174	void SetTitleFont(const wxFont& font);
	175
	176	/**
	177	Show the tooltip for the given window and optionally specify where to
	178	show the tooltip.
	179
	180	By default the tooltip tip points to the (middle of the) specified
	181	window which must be non-@NULL or, if @a rect is non-@NULL, the middle
	182	of the specified wxRect.
	183
	184	The coordinates of the @a rect parameter are relative to the given window.
	185
	186	Currently the native MSW implementation is used only if @a win is a
	187	wxTextCtrl and @a rect is @NULL. This limitation may be removed in the
	188	future.
	189
	190	Parameter @a rect is new since wxWidgets 2.9.5.
	191	*/
	192	void ShowFor(wxWindow* win, const wxRect* rect = NULL);
	193
	194	/**
	195	Destructor.
	196
	197	Notice that destroying this object does not hide the tooltip if it's
	198	currently shown, it will be hidden and destroyed when the user
	199	dismisses it or the timeout expires.
	200
	201	The destructor is non-virtual as this class is not supposed to be
	202	derived from.
	203	*/
	204	~wxRichToolTip();
	205	};