include/wx/cshelp.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/cshelp.h
   3 // Purpose:     Context-sensitive help support classes
   4 // Author:      Julian Smart, Vadim Zeitlin
   5 // Modified by:
   6 // Created:     08/09/2000
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2000 Julian Smart, Vadim Zeitlin
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_CSHELPH__
  13 #define _WX_CSHELPH__
  14
  15 #if defined(__GNUG__) && !defined(__APPLE__)
  16     #pragma interface "cshelp.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20
  21 #if wxUSE_HELP
  22
  23 #include "wx/help.h"
  24
  25 #if wxUSE_BMPBUTTON
  26 #include "wx/bmpbuttn.h"
  27 #endif
  28
  29 // ----------------------------------------------------------------------------
  30 // classes used to implement context help UI
  31 // ----------------------------------------------------------------------------
  32
  33 /*
  34  * wxContextHelp
  35  * Invokes context-sensitive help. When the user
  36  * clicks on a window, a wxEVT_HELP event will be sent to that
  37  * window for the application to display help for.
  38  */
  39
  40 class WXDLLEXPORT wxContextHelp : public wxObject
  41 {
  42 public:
  43     wxContextHelp(wxWindow* win = NULL, bool beginHelp = TRUE);
  44     virtual ~wxContextHelp();
  45
  46     bool BeginContextHelp(wxWindow* win);
  47     bool EndContextHelp();
  48
  49     bool EventLoop();
  50     bool DispatchEvent(wxWindow* win, const wxPoint& pt);
  51
  52     void SetStatus(bool status) { m_status = status; }
  53
  54 protected:
  55     bool    m_inHelp;
  56     bool    m_status; // TRUE if the user left-clicked
  57
  58 private:
  59     DECLARE_DYNAMIC_CLASS(wxContextHelp)
  60 };
  61
  62 #if wxUSE_BMPBUTTON
  63 /*
  64  * wxContextHelpButton
  65  * You can add this to your dialogs (especially on non-Windows platforms)
  66  * to put the application into context help mode.
  67  */
  68
  69 class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton
  70 {
  71 public:
  72     wxContextHelpButton(wxWindow* parent,
  73                         wxWindowID id = wxID_CONTEXT_HELP,
  74                         const wxPoint& pos = wxDefaultPosition,
  75                         const wxSize& size = wxDefaultSize,
  76                         long style = wxBU_AUTODRAW);
  77
  78     void OnContextHelp(wxCommandEvent& event);
  79
  80 private:
  81     DECLARE_CLASS(wxContextHelpButton)
  82     DECLARE_EVENT_TABLE()
  83 };
  84
  85 #endif
  86
  87 // ----------------------------------------------------------------------------
  88 // classes used to implement context help support
  89 // ----------------------------------------------------------------------------
  90
  91 // wxHelpProvider is an abstract class used by the program implementing context help to
  92 // show the help text (or whatever: it may be HTML page or anything else) for
  93 // the given window.
  94 //
  95 // The current help provider must be explicitly set by the application using
  96 // wxHelpProvider::Set().
  97 class WXDLLEXPORT wxHelpProvider
  98 {
  99 public:
 100     // get/set the current (application-global) help provider (Set() returns
 101     // the previous one)
 102     static wxHelpProvider *Set(wxHelpProvider *helpProvider)
 103     {
 104         wxHelpProvider *helpProviderOld = ms_helpProvider;
 105         ms_helpProvider = helpProvider;
 106         return helpProviderOld;
 107     }
 108
 109     // unlike some other class, the help provider is not created on demand,
 110     // this must be explicitly done by the application
 111     static wxHelpProvider *Get() { return ms_helpProvider; }
 112
 113     // get the help string (whose interpretation is help provider dependent
 114     // except that empty string always means that no help is associated with
 115     // the window) for this window
 116     virtual wxString GetHelp(const wxWindowBase *window) = 0;
 117
 118     // do show help for the given window (uses GetHelp() internally if
 119     // applicable), return TRUE if it was done or FALSE if no help available
 120     // for this window
 121     virtual bool ShowHelp(wxWindowBase *window) = 0;
 122
 123     // associate the text with the given window or id: although all help
 124     // providers have these functions to allow making wxWindow::SetHelpText()
 125     // work, not all of them implement them
 126     virtual void AddHelp(wxWindowBase *window, const wxString& text);
 127
 128     // this version associates the given text with all window with this id
 129     // (may be used to set the same help string for all [Cancel] buttons in
 130     // the application, for example)
 131     virtual void AddHelp(wxWindowID id, const wxString& text);
 132
 133     // removes the association
 134     virtual void RemoveHelp(wxWindowBase* window);
 135
 136     // virtual dtor for any base class
 137     virtual ~wxHelpProvider();
 138
 139 private:
 140     static wxHelpProvider *ms_helpProvider;
 141 };
 142
 143 // wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
 144 // only plain text help strings and shows the string associated with the
 145 // control (if any) in a tooltip
 146 class WXDLLEXPORT wxSimpleHelpProvider : public wxHelpProvider
 147 {
 148 public:
 149     // implement wxHelpProvider methods
 150     virtual wxString GetHelp(const wxWindowBase *window);
 151     virtual bool ShowHelp(wxWindowBase *window);
 152     virtual void AddHelp(wxWindowBase *window, const wxString& text);
 153     virtual void AddHelp(wxWindowID id, const wxString& text);
 154     virtual void RemoveHelp(wxWindowBase* window);
 155
 156 protected:
 157     // we use 2 hashes for storing the help strings associated with windows
 158     // and the ids
 159     wxStringHashTable m_hashWindows,
 160                      m_hashIds;
 161 };
 162
 163 // wxHelpControllerHelpProvider is an implementation of wxHelpProvider which supports
 164 // both context identifiers and plain text help strings. If the help text is an integer,
 165 // it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the string
 166 // in a tooltip as per wxSimpleHelpProvider.
 167 class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 168 {
 169 public:
 170     // Note that it doesn't own the help controller. The help controller
 171     // should be deleted separately.
 172     wxHelpControllerHelpProvider(wxHelpControllerBase* hc = (wxHelpControllerBase*) NULL);
 173
 174     // implement wxHelpProvider methods
 175     virtual bool ShowHelp(wxWindowBase *window);
 176
 177     // Other accessors
 178     void SetHelpController(wxHelpControllerBase* hc) { m_helpController = hc; }
 179     wxHelpControllerBase* GetHelpController() const { return m_helpController; }
 180
 181 protected:
 182     wxHelpControllerBase*   m_helpController;
 183
 184     DECLARE_NO_COPY_CLASS(wxHelpControllerHelpProvider)
 185 };
 186
 187 // Convenience function for turning context id into wxString
 188 WXDLLEXPORT wxString wxContextId(int id);
 189
 190 #endif // wxUSE_HELP
 191
 192 #endif // _WX_CSHELPH__
 193