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 #include "wx/defs.h"
  16
  17 #if wxUSE_HELP
  18
  19 #include "wx/help.h"
  20
  21 #include "wx/hashmap.h"
  22 #if wxUSE_BMPBUTTON
  23 #include "wx/bmpbuttn.h"
  24 #endif
  25
  26 // ----------------------------------------------------------------------------
  27 // classes used to implement context help UI
  28 // ----------------------------------------------------------------------------
  29
  30 /*
  31  * wxContextHelp
  32  * Invokes context-sensitive help. When the user
  33  * clicks on a window, a wxEVT_HELP event will be sent to that
  34  * window for the application to display help for.
  35  */
  36
  37 class WXDLLEXPORT wxContextHelp : public wxObject
  38 {
  39 public:
  40     wxContextHelp(wxWindow* win = NULL, bool beginHelp = true);
  41     virtual ~wxContextHelp();
  42
  43     bool BeginContextHelp(wxWindow* win);
  44     bool EndContextHelp();
  45
  46     bool EventLoop();
  47     bool DispatchEvent(wxWindow* win, const wxPoint& pt);
  48
  49     void SetStatus(bool status) { m_status = status; }
  50
  51 protected:
  52     bool    m_inHelp;
  53     bool    m_status; // true if the user left-clicked
  54
  55 private:
  56     DECLARE_DYNAMIC_CLASS(wxContextHelp)
  57 };
  58
  59 #if wxUSE_BMPBUTTON
  60 /*
  61  * wxContextHelpButton
  62  * You can add this to your dialogs (especially on non-Windows platforms)
  63  * to put the application into context help mode.
  64  */
  65
  66 class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton
  67 {
  68 public:
  69     wxContextHelpButton(wxWindow* parent,
  70                         wxWindowID id = wxID_CONTEXT_HELP,
  71                         const wxPoint& pos = wxDefaultPosition,
  72                         const wxSize& size = wxDefaultSize,
  73                         long style = wxBU_AUTODRAW);
  74
  75     void OnContextHelp(wxCommandEvent& event);
  76
  77 private:
  78     DECLARE_DYNAMIC_CLASS_NO_COPY(wxContextHelpButton)
  79     DECLARE_EVENT_TABLE()
  80 };
  81
  82 #endif
  83
  84 // ----------------------------------------------------------------------------
  85 // classes used to implement context help support
  86 // ----------------------------------------------------------------------------
  87
  88 // wxHelpProvider is an abstract class used by the program implementing context help to
  89 // show the help text (or whatever: it may be HTML page or anything else) for
  90 // the given window.
  91 //
  92 // The current help provider must be explicitly set by the application using
  93 // wxHelpProvider::Set().
  94 class WXDLLEXPORT wxHelpProvider
  95 {
  96 public:
  97     // get/set the current (application-global) help provider (Set() returns
  98     // the previous one)
  99     static wxHelpProvider *Set(wxHelpProvider *helpProvider)
 100     {
 101         wxHelpProvider *helpProviderOld = ms_helpProvider;
 102         ms_helpProvider = helpProvider;
 103         return helpProviderOld;
 104     }
 105
 106     // unlike some other class, the help provider is not created on demand,
 107     // this must be explicitly done by the application
 108     static wxHelpProvider *Get() { return ms_helpProvider; }
 109
 110     // get the help string (whose interpretation is help provider dependent
 111     // except that empty string always means that no help is associated with
 112     // the window) for this window
 113     virtual wxString GetHelp(const wxWindowBase *window) = 0;
 114
 115     // do show help for the given window (uses GetHelp() internally if
 116     // applicable), return true if it was done or false if no help available
 117     // for this window
 118     virtual bool ShowHelp(wxWindowBase *window) = 0;
 119
 120     // associate the text with the given window or id: although all help
 121     // providers have these functions to allow making wxWindow::SetHelpText()
 122     // work, not all of them implement them
 123     virtual void AddHelp(wxWindowBase *window, const wxString& text);
 124
 125     // this version associates the given text with all window with this id
 126     // (may be used to set the same help string for all [Cancel] buttons in
 127     // the application, for example)
 128     virtual void AddHelp(wxWindowID id, const wxString& text);
 129
 130     // removes the association
 131     virtual void RemoveHelp(wxWindowBase* window);
 132
 133     // virtual dtor for any base class
 134     virtual ~wxHelpProvider();
 135
 136 private:
 137     static wxHelpProvider *ms_helpProvider;
 138 };
 139
 140 WX_DECLARE_EXPORTED_HASH_MAP( wxUIntPtr, wxString, wxIntegerHash,
 141                               wxIntegerEqual, wxSimpleHelpProviderHashMap );
 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     wxSimpleHelpProviderHashMap 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