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