interface/cshelp.h

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