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     wxHelpProvider* Get();
  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     wxHelpProvider* Set(wxHelpProvider* helpProvider);
  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         Returns @true if help was shown, or @false if no help was available for this
  77         window.
  78     */
  79     bool ShowHelp(wxWindowBase* window);
  80
  81     /**
  82         This function may be overridden to show help for the window when it should
  83         depend on the position inside the window, By default this method forwards to
  84         ShowHelp(), so it is enough to only implement
  85         the latter if the help doesn't depend on the position.
  86         Returns @true if help was shown, or @false if no help was available for this
  87         window.
  88
  89         @param window
  90             Window to show help text for.
  91         @param point
  92             Coordinates of the mouse at the moment of help event emission.
  93         @param origin
  94             Help event origin, see wxHelpEvent::GetOrigin.
  95     */
  96     bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point,
  97                          wxHelpEvent::Origin origin);
  98 };
  99
 100
 101 /**
 102     @class wxHelpControllerHelpProvider
 103     @wxheader{cshelp.h}
 104
 105     wxHelpControllerHelpProvider is an implementation of wxHelpProvider which
 106     supports
 107     both context identifiers and plain text help strings. If the help text is an
 108     integer,
 109     it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the
 110     string
 111     in a tooltip as per wxSimpleHelpProvider. If you use this with a
 112     wxCHMHelpController instance
 113     on windows, it will use the native style of tip window instead of wxTipWindow.
 114
 115     You can use the convenience function @b wxContextId to convert an integer
 116     context
 117     id to a string for passing to wxWindow::SetHelpText.
 118
 119     @library{wxcore}
 120     @category{help}
 121
 122     @seealso
 123     wxHelpProvider, wxSimpleHelpProvider, wxContextHelp, wxWindow::SetHelpText,
 124     wxWindow::GetHelpTextAtPoint
 125 */
 126 class wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 127 {
 128 public:
 129     /**
 130         Note that the instance doesn't own the help controller. The help controller
 131         should be deleted separately.
 132     */
 133     wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL);
 134
 135     /**
 136         Returns the help controller associated with this help provider.
 137     */
 138     wxHelpControllerBase* GetHelpController() const;
 139
 140     /**
 141         Sets the help controller associated with this help provider.
 142     */
 143     void SetHelpController(wxHelpControllerBase* hc);
 144 };
 145
 146
 147 /**
 148     @class wxContextHelp
 149     @wxheader{cshelp.h}
 150
 151     This class changes the cursor to a query and puts the application into a
 152     'context-sensitive help mode'.
 153     When the user left-clicks on a window within the specified window, a wxEVT_HELP
 154     event is
 155     sent to that control, and the application may respond to it by popping up some
 156     help.
 157
 158     For example:
 159
 160     @code
 161     wxContextHelp contextHelp(myWindow);
 162     @endcode
 163
 164     There are a couple of ways to invoke this behaviour implicitly:
 165
 166      Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This will
 167     put a question mark
 168     in the titlebar, and Windows will put the application into context-sensitive
 169     help mode automatically,
 170     with further programming.
 171      Create a wxContextHelpButton, whose predefined behaviour is to create a
 172     context help object.
 173     Normally you will write your application so that this button is only added to a
 174     dialog for non-Windows platforms
 175     (use wxDIALOG_EX_CONTEXTHELP on Windows).
 176
 177     Note that on Mac OS X, the cursor does not change when in context-sensitive
 178     help mode.
 179
 180     @library{wxcore}
 181     @category{help}
 182
 183     @seealso
 184     wxHelpEvent, wxHelpController, wxContextHelpButton
 185 */
 186 class wxContextHelp : public wxObject
 187 {
 188 public:
 189     /**
 190         Constructs a context help object, calling BeginContextHelp() if
 191         @a doNow is @true (the default).
 192         If @a window is @NULL, the top window is used.
 193     */
 194     wxContextHelp(wxWindow* window = NULL, bool doNow = true);
 195
 196     /**
 197         Destroys the context help object.
 198     */
 199     ~wxContextHelp();
 200
 201     /**
 202         Puts the application into context-sensitive help mode. @a window is the window
 203         which will be used to catch events; if @NULL, the top window will be used.
 204         Returns @true if the application was successfully put into context-sensitive
 205         help mode.
 206         This function only returns when the event loop has finished.
 207     */
 208     bool BeginContextHelp(wxWindow* window = NULL);
 209
 210     /**
 211         Ends context-sensitive help mode. Not normally called by the application.
 212     */
 213     bool EndContextHelp();
 214 };
 215
 216
 217 /**
 218     @class wxContextHelpButton
 219     @wxheader{cshelp.h}
 220
 221     Instances of this class may be used to add a question mark button that when
 222     pressed, puts the
 223     application into context-help mode. It does this by creating a wxContextHelp
 224     object which itself
 225     generates a wxEVT_HELP event when the user clicks on a window.
 226
 227     On Windows, you may add a question-mark icon to a dialog by use of the
 228     wxDIALOG_EX_CONTEXTHELP extra style, but
 229     on other platforms you will have to add a button explicitly, usually next to
 230     OK, Cancel or similar buttons.
 231
 232     @library{wxcore}
 233     @category{help}
 234
 235     @seealso
 236     wxBitmapButton, wxContextHelp
 237 */
 238 class wxContextHelpButton : public wxBitmapButton
 239 {
 240 public:
 241     //@{
 242     /**
 243         Constructor, creating and showing a context help button.
 244
 245         @param parent
 246             Parent window. Must not be @NULL.
 247         @param id
 248             Button identifier. Defaults to wxID_CONTEXT_HELP.
 249         @param pos
 250             Button position.
 251         @param size
 252             Button size. If wxDefaultSize is specified then the button is
 253         sized
 254             appropriately for the question mark bitmap.
 255         @param style
 256             Window style.
 257     */
 258     wxContextHelpButton();
 259     wxContextHelpButton(wxWindow* parent,
 260                         wxWindowID id = wxID_CONTEXT_HELP,
 261                         const wxPoint& pos = wxDefaultPosition,
 262                         const wxSize& size = wxDefaultSize,
 263                         long style = wxBU_AUTODRAW);
 264     //@}
 265 };
 266
 267
 268 /**
 269     @class wxSimpleHelpProvider
 270     @wxheader{cshelp.h}
 271
 272     wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
 273     only plain text help strings, and shows the string associated with the
 274     control (if any) in a tooltip.
 275
 276     @library{wxcore}
 277     @category{help}
 278
 279     @seealso
 280     wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
 281     wxWindow::SetHelpText, wxWindow::GetHelpTextAtPoint
 282 */
 283 class wxSimpleHelpProvider : public wxHelpProvider
 284 {
 285 public:
 286
 287 };