interface/cshelp.h

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