interface/wx/cshelp.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        cshelp.h
   3 // Purpose:     interface of wxHelpProvider
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHelpProvider
  11
  12     wxHelpProvider is an abstract class used by a program implementing
  13     context-sensitive help to show the help text for the given window.
  14
  15     The current help provider must be explicitly set by the application using
  16     Set().
  17
  18     @library{wxcore}
  19     @category{help}
  20
  21     @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,
  22          wxHelpControllerHelpProvider, wxWindow::SetHelpText(),
  23          wxWindow::GetHelpTextAtPoint()
  24 */
  25 class wxHelpProvider
  26 {
  27 public:
  28     /**
  29         Virtual destructor for any base class.
  30     */
  31     virtual ~wxHelpProvider();
  32
  33     /**
  34         Associates the text with the given window.
  35
  36         @remarks
  37         Although all help providers have these functions to allow making
  38         wxWindow::SetHelpText() work, not all of them implement the functions.
  39     */
  40     virtual void AddHelp(wxWindowBase* window, const wxString& text);
  41
  42     /**
  43         Associates the text with the given ID.
  44
  45         This help text will be shown for all windows with ID @a id, unless they
  46         have more specific help text associated using the other AddHelp()
  47         prototype.  May be used to set the same help string for all Cancel
  48         buttons in the application, for example.
  49
  50         @remarks
  51         Although all help providers have these functions to allow making
  52         wxWindow::SetHelpText() work, not all of them implement the functions.
  53     */
  54     virtual void AddHelp(wxWindowID id, const wxString& text);
  55
  56     /**
  57         Returns pointer to help provider instance.
  58
  59         Unlike some other classes, the help provider is not created on demand.
  60         This must be explicitly done by the application using Set().
  61     */
  62     static wxHelpProvider* Get();
  63
  64     /**
  65         This version associates the given text with all windows with this id.
  66         May be used to set the same help string for all Cancel buttons in
  67         the application, for example.
  68     */
  69     virtual wxString GetHelp(const wxWindowBase* window) = 0;
  70
  71     /**
  72         Removes the association between the window pointer and the help text.
  73         This is called by the wxWindow destructor. Without this, the table of
  74         help strings will fill up and when window pointers are reused, the
  75         wrong help string will be found.
  76     */
  77     virtual void RemoveHelp(wxWindowBase* window);
  78
  79     /**
  80         Set the current, application-wide help provider.
  81
  82         @return Pointer to previous help provider or @NULL if there wasn't any.
  83     */
  84     static wxHelpProvider* Set(wxHelpProvider* helpProvider);
  85
  86     /**
  87         Shows help for the given window.
  88
  89         Override this function if the help doesn't depend on the exact position
  90         inside the window, otherwise you need to override ShowHelpAtPoint().
  91         Returns @true if help was shown, or @false if no help was available for
  92         this window.
  93     */
  94     virtual bool ShowHelp(wxWindowBase* window);
  95
  96     /**
  97         This function may be overridden to show help for the window when it
  98         should depend on the position inside the window, By default this method
  99         forwards to ShowHelp(), so it is enough to only implement the latter if
 100         the help doesn't depend on the position.
 101
 102         @param window
 103             Window to show help text for.
 104         @param point
 105             Coordinates of the mouse at the moment of help event emission.
 106         @param origin
 107             Help event origin, see wxHelpEvent::GetOrigin.
 108
 109         @return @true if help was shown, or @false if no help was available
 110                 for this window.
 111
 112         @since 2.7.0
 113     */
 114     virtual bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint& point,
 115                                  wxHelpEvent::Origin origin);
 116 };
 117
 118
 119
 120 /**
 121     @class wxHelpControllerHelpProvider
 122
 123     wxHelpControllerHelpProvider is an implementation of wxHelpProvider which
 124     supports both context identifiers and plain text help strings. If the help
 125     text is an integer, it is passed to wxHelpController::DisplayContextPopup().
 126     Otherwise, it shows the string in a tooltip as per wxSimpleHelpProvider. If
 127     you use this with a wxCHMHelpController instance on windows, it will use
 128     the native style of tip window instead of wxTipWindow.
 129
 130     You can use the convenience function wxContextId() to convert an integer
 131     context id to a string for passing to wxWindow::SetHelpText().
 132
 133     @library{wxcore}
 134     @category{help}
 135
 136     @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp,
 137          wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint()
 138 */
 139 class wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 140 {
 141 public:
 142     /**
 143         Note that the instance doesn't own the help controller. The help
 144         controller should be deleted separately.
 145     */
 146     wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL);
 147
 148     /**
 149         Returns the help controller associated with this help provider.
 150     */
 151     wxHelpControllerBase* GetHelpController() const;
 152
 153     /**
 154         Sets the help controller associated with this help provider.
 155     */
 156     void SetHelpController(wxHelpControllerBase* hc);
 157 };
 158
 159
 160
 161 /**
 162     @class wxContextHelp
 163
 164     This class changes the cursor to a query and puts the application into a
 165     'context-sensitive help mode'.  When the user left-clicks on a window
 166     within the specified window, a @c wxEVT_HELP event is sent to that control,
 167     and the application may respond to it by popping up some help.
 168
 169     For example:
 170     @code
 171     wxContextHelp contextHelp(myWindow);
 172     @endcode
 173
 174     There are a couple of ways to invoke this behaviour implicitly:
 175
 176     - Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This
 177       will put a question mark in the titlebar, and Windows will put the
 178       application into context-sensitive help mode automatically, with further
 179       programming.
 180
 181     - Create a wxContextHelpButton, whose predefined behaviour is
 182       to create a context help object.  Normally you will write your application
 183       so that this button is only added to a dialog for non-Windows platforms
 184       (use wxDIALOG_EX_CONTEXTHELP on Windows).
 185
 186     Note that on Mac OS X, the cursor does not change when in context-sensitive
 187     help mode.
 188
 189     @library{wxcore}
 190     @category{help}
 191
 192     @see wxHelpEvent, wxHelpController, wxContextHelpButton
 193 */
 194 class wxContextHelp : public wxObject
 195 {
 196 public:
 197     /**
 198         Constructs a context help object, calling BeginContextHelp() if
 199         @a doNow is @true (the default).
 200
 201         If @a window is @NULL, the top window is used.
 202     */
 203     wxContextHelp(wxWindow* window = NULL, bool doNow = true);
 204
 205     /**
 206         Destroys the context help object.
 207     */
 208     virtual ~wxContextHelp();
 209
 210     /**
 211         Puts the application into context-sensitive help mode. @a window is the
 212         window which will be used to catch events; if @NULL, the top window
 213         will be used.
 214
 215         Returns @true if the application was successfully put into
 216         context-sensitive help mode.
 217         This function only returns when the event loop has finished.
 218     */
 219     bool BeginContextHelp(wxWindow* window);
 220
 221     /**
 222         Ends context-sensitive help mode. Not normally called by the
 223         application.
 224     */
 225     bool EndContextHelp();
 226 };
 227
 228
 229
 230 /**
 231     @class wxContextHelpButton
 232
 233     Instances of this class may be used to add a question mark button that when
 234     pressed, puts the application into context-help mode. It does this by
 235     creating a wxContextHelp object which itself generates a @c wxEVT_HELP event
 236     when the user clicks on a window.
 237
 238     On Windows, you may add a question-mark icon to a dialog by use of the
 239     wxDIALOG_EX_CONTEXTHELP extra style, but on other platforms you will have
 240     to add a button explicitly, usually next to OK, Cancel or similar buttons.
 241
 242     @library{wxcore}
 243     @category{help}
 244
 245     @see wxBitmapButton, wxContextHelp
 246 */
 247 class wxContextHelpButton : public wxBitmapButton
 248 {
 249 public:
 250     /**
 251         Constructor, creating and showing a context help button.
 252
 253         @param parent
 254             Parent window. Must not be @NULL.
 255         @param id
 256             Button identifier. Defaults to wxID_CONTEXT_HELP.
 257         @param pos
 258             Button position.
 259             If ::wxDefaultPosition is specified then a default position is chosen.
 260         @param size
 261             Button size.
 262             If ::wxDefaultSize is specified then the button is sized appropriately
 263             for the question mark bitmap.
 264         @param style
 265             Window style.
 266
 267         @remarks
 268         Normally you only need pass the parent window to the constructor, and
 269         use the defaults for the remaining parameters.
 270     */
 271     wxContextHelpButton(wxWindow* parent,
 272                         wxWindowID id = wxID_CONTEXT_HELP,
 273                         const wxPoint& pos = wxDefaultPosition,
 274                         const wxSize& size = wxDefaultSize,
 275                         long style = wxBU_AUTODRAW);
 276 };
 277
 278
 279 /**
 280     @class wxSimpleHelpProvider
 281
 282     wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
 283     only plain text help strings, and shows the string associated with the
 284     control (if any) in a tooltip.
 285
 286     @library{wxcore}
 287     @category{help}
 288
 289     @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
 290          wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint()
 291 */
 292 class wxSimpleHelpProvider : public wxHelpProvider
 293 {
 294 public:
 295
 296 };
 297