← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/richtooltip.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/richtooltip.h
 
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
};