interface/wx/cshelp.h

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