1
by Brian Sidebotham
Initial import into Bazaar |
1 |
///////////////////////////////////////////////////////////////////////////////
|
2 |
// Name: interface/wx/richtooltip.h
|
|
3 |
// Purpose: wxRichToolTip class documentation
|
|
4 |
// Author: Vadim Zeitlin
|
|
5 |
// Created: 2011-10-18
|
|
6 |
// RCS-ID: $Id: richtooltip.h 69463 2011-10-18 21:57:02Z VZ $
|
|
7 |
// Copyright: (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
|
|
8 |
// Licence: wxWindows licence
|
|
9 |
///////////////////////////////////////////////////////////////////////////////
|
|
10 |
||
11 |
/**
|
|
12 |
Support tip kinds for wxRichToolTip.
|
|
13 |
||
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).
|
|
18 |
||
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.
|
|
22 |
||
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.
|
|
26 |
*/
|
|
27 |
enum wxTipKind |
|
28 |
{
|
|
29 |
/// Don't show any tip, the tooltip will be (roughly) rectangular.
|
|
30 |
wxTipKind_None, |
|
31 |
/// Show a right triangle tip in the top left corner of the tooltip.
|
|
32 |
wxTipKind_TopLeft, |
|
33 |
/// Show an equilateral triangle tip in the middle of the tooltip top side.
|
|
34 |
wxTipKind_Top, |
|
35 |
/// Show a right triangle tip in the top right corner of the tooltip.
|
|
36 |
wxTipKind_TopRight, |
|
37 |
/// Show a right triangle tip in the bottom left corner of the tooltip.
|
|
38 |
wxTipKind_BottomLeft, |
|
39 |
/// Show an equilateral triangle tip in the middle of the tooltip bottom side.
|
|
40 |
wxTipKind_Bottom, |
|
41 |
/// Show a right triangle tip in the bottom right corner of the tooltip.
|
|
42 |
wxTipKind_BottomRight, |
|
43 |
/**
|
|
44 |
Choose the appropriate tip shape and position automatically.
|
|
45 |
||
46 |
This is the default and shouldn't normally need to be changed.
|
|
47 |
||
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
|
|
50 |
platforms.
|
|
51 |
*/
|
|
52 |
wxTipKind_Auto
|
|
53 |
};
|
|
54 |
/**
|
|
55 |
Allows to show a tool tip with more customizations than wxToolTip.
|
|
56 |
||
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:
|
|
59 |
@code
|
|
60 |
wxTextCtrl* password = new wxTextCtrl(..., wxTE_PASSWORD);
|
|
61 |
...
|
|
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"
|
|
65 |
"\n"
|
|
66 |
"Press Caps Lock key to turn it off.");
|
|
67 |
tip.SetIcon(wxICON_WARNING);
|
|
68 |
tip.ShowFor(password);
|
|
69 |
@endcode
|
|
70 |
||
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.
|
|
80 |
||
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
|
|
83 |
to show the tooltip.
|
|
84 |
||
85 |
The images below show some examples of rich tooltips on different
|
|
86 |
platforms, with various customizations applied.
|
|
87 |
||
88 |
@library{wxadv}
|
|
89 |
@category{miscwnd}
|
|
90 |
@appearance{richtooltip.png}
|
|
91 |
||
92 |
@since 2.9.3
|
|
93 |
*/
|
|
94 |
class wxRichToolTip |
|
95 |
{
|
|
96 |
public: |
|
97 |
/**
|
|
98 |
Constructor must specify the tooltip title and main message.
|
|
99 |
||
100 |
The main message can contain embedded new lines. Both the title and
|
|
101 |
message must be non-empty.
|
|
102 |
||
103 |
Additional attributes can be set later.
|
|
104 |
*/
|
|
105 |
wxRichToolTip(const wxString& title, const wxString& message); |
|
106 |
||
107 |
/**
|
|
108 |
Set the background colour.
|
|
109 |
||
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.
|
|
112 |
||
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.
|
|
116 |
*/
|
|
117 |
void SetBackgroundColour(const wxColour& col, |
|
118 |
const wxColour& colEnd = wxColour()); |
|
119 |
||
120 |
/**
|
|
121 |
Set the small icon to show.
|
|
122 |
||
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.
|
|
129 |
*/
|
|
130 |
//@{
|
|
131 |
void SetIcon(int icon = wxICON_INFORMATION); |
|
132 |
void SetIcon(const wxIcon& icon); |
|
133 |
//@}
|
|
134 |
||
135 |
/**
|
|
136 |
Set timeout after which the tooltip should disappear, in milliseconds.
|
|
137 |
||
138 |
By default the tooltip is hidden after system-dependent interval of
|
|
139 |
time elapses but this method can be used to change this or also disable
|
|
140 |
hiding the tooltip automatically entirely by passing 0 in this parameter
|
|
141 |
(but doing this will prevent the native MSW version from being used).
|
|
142 |
||
143 |
Notice that the tooltip will always be hidden if the user presses a key
|
|
144 |
or clicks a mouse button.
|
|
145 |
*/
|
|
146 |
void SetTimeout(unsigned milliseconds); |
|
147 |
||
148 |
/**
|
|
149 |
Choose the tip kind, possibly none.
|
|
150 |
||
151 |
See wxTipKind documentation for the possible choices here.
|
|
152 |
||
153 |
By default the tip is positioned automatically, as if wxTipKind_Auto
|
|
154 |
was used. Native MSW implementation doesn't support setting the tip
|
|
155 |
kind explicitly and won't be used if this method is called with any
|
|
156 |
value other than wxTipKind_Auto.
|
|
157 |
||
158 |
Notice that using non automatic tooltip kind may result in the tooltip
|
|
159 |
being positioned partially off screen and it's the callers
|
|
160 |
responsibility to ensure that this doesn't happen in this case.
|
|
161 |
*/
|
|
162 |
void SetTipKind(wxTipKind tipKind); |
|
163 |
||
164 |
/**
|
|
165 |
Set the title text font.
|
|
166 |
||
167 |
By default it's emphasized using the font style or colour appropriate
|
|
168 |
for the current platform. Calling this method prevents the native MSW
|
|
169 |
implementation from being used as it doesn't support changing the font.
|
|
170 |
*/
|
|
171 |
void SetTitleFont(const wxFont& font); |
|
172 |
||
173 |
/**
|
|
174 |
Show the tooltip for the given window.
|
|
175 |
||
176 |
The tooltip tip points to the (middle of the) specified window which
|
|
177 |
must be non-@NULL.
|
|
178 |
||
179 |
Currently the native MSW implementation is used only if @a win is a
|
|
180 |
wxTextCtrl. This limitation may be removed in the future.
|
|
181 |
*/
|
|
182 |
void ShowFor(wxWindow* win); |
|
183 |
||
184 |
/**
|
|
185 |
Destructor.
|
|
186 |
||
187 |
Notice that destroying this object does not hide the tooltip if it's
|
|
188 |
currently shown, it will be hidden and destroyed when the user
|
|
189 |
dismisses it or the timeout expires.
|
|
190 |
||
191 |
The destructor is non-virtual as this class is not supposed to be
|
|
192 |
derived from.
|
|
193 |
*/
|
|
194 |
~wxRichToolTip(); |
|
195 |
};
|