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$
   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}
  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 and
 137         optionally set a delay before the tooltip is shown, in milliseconds.
 138
 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).
 144
 145         Notice that the tooltip will always be hidden if the user presses a key
 146         or clicks a mouse button.
 147
 148         Parameter @a millisecondsDelay is new since wxWidgets 2.9.5.
 149      */
 150     void SetTimeout(unsigned millisecondsTimeout, unsigned millisecondsDelay = 0);
 151
 152     /**
 153         Choose the tip kind, possibly none.
 154
 155         See wxTipKind documentation for the possible choices here.
 156
 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.
 161
 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.
 165      */
 166     void SetTipKind(wxTipKind tipKind);
 167
 168     /**
 169         Set the title text font.
 170
 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.
 174      */
 175     void SetTitleFont(const wxFont& font);
 176
 177     /**
 178         Show the tooltip for the given window and optionally specify where to
 179         show the tooltip.
 180
 181         By default the tooltip tip points to the (middle of the) specified
 182         window which must be non-@NULL or, if @a rect is non-@NULL, the middle
 183         of the specified wxRect.
 184
 185         The coordinates of the @a rect parameter are relative to the given window.
 186
 187         Currently the native MSW implementation is used only if @a win is a
 188         wxTextCtrl and @a rect is @NULL. This limitation may be removed in the
 189         future.
 190
 191         Parameter @a rect is new since wxWidgets 2.9.5.
 192      */
 193     void ShowFor(wxWindow* win, const wxRect* rect = NULL);
 194
 195     /**
 196         Destructor.
 197
 198         Notice that destroying this object does not hide the tooltip if it's
 199         currently shown, it will be hidden and destroyed when the user
 200         dismisses it or the timeout expires.
 201
 202         The destructor is non-virtual as this class is not supposed to be
 203         derived from.
 204      */
 205     ~wxRichToolTip();
 206 };