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 // Copyright:   (c) 2000 Julian Smart, Vadim Zeitlin
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_CSHELP_H_
  12 #define _WX_CSHELP_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_HELP
  17
  18 #include "wx/help.h"
  19
  20 #include "wx/hashmap.h"
  21 #if wxUSE_BMPBUTTON
  22 #include "wx/bmpbuttn.h"
  23 #endif
  24
  25 #include "wx/event.h"
  26
  27 // ----------------------------------------------------------------------------
  28 // classes used to implement context help UI
  29 // ----------------------------------------------------------------------------
  30
  31 /*
  32  * wxContextHelp
  33  * Invokes context-sensitive help. When the user
  34  * clicks on a window, a wxEVT_HELP event will be sent to that
  35  * window for the application to display help for.
  36  */
  37
  38 class WXDLLIMPEXP_CORE wxContextHelp : public wxObject
  39 {
  40 public:
  41     wxContextHelp(wxWindow* win = NULL, bool beginHelp = true);
  42     virtual ~wxContextHelp();
  43
  44     bool BeginContextHelp(wxWindow* win);
  45     bool EndContextHelp();
  46
  47     bool EventLoop();
  48     bool DispatchEvent(wxWindow* win, const wxPoint& pt);
  49
  50     void SetStatus(bool status) { m_status = status; }
  51
  52 protected:
  53     bool    m_inHelp;
  54     bool    m_status; // true if the user left-clicked
  55
  56 private:
  57     DECLARE_DYNAMIC_CLASS(wxContextHelp)
  58 };
  59
  60 #if wxUSE_BMPBUTTON
  61 /*
  62  * wxContextHelpButton
  63  * You can add this to your dialogs (especially on non-Windows platforms)
  64  * to put the application into context help mode.
  65  */
  66
  67 class WXDLLIMPEXP_CORE wxContextHelpButton : public wxBitmapButton
  68 {
  69 public:
  70     wxContextHelpButton(wxWindow* parent,
  71                         wxWindowID id = wxID_CONTEXT_HELP,
  72                         const wxPoint& pos = wxDefaultPosition,
  73                         const wxSize& size = wxDefaultSize,
  74                         long style = wxBU_AUTODRAW);
  75
  76     void OnContextHelp(wxCommandEvent& event);
  77
  78 private:
  79     DECLARE_DYNAMIC_CLASS_NO_COPY(wxContextHelpButton)
  80     DECLARE_EVENT_TABLE()
  81 };
  82
  83 #endif
  84
  85 // ----------------------------------------------------------------------------
  86 // classes used to implement context help support
  87 // ----------------------------------------------------------------------------
  88
  89 // wxHelpProvider is an abstract class used by the program implementing context help to
  90 // show the help text (or whatever: it may be HTML page or anything else) for
  91 // the given window.
  92 //
  93 // The current help provider must be explicitly set by the application using
  94 // wxHelpProvider::Set().
  95 //
  96 // Special note about ShowHelpAtPoint() and ShowHelp(): we want to be able to
  97 // override ShowHelpAtPoint() when we need to use different help messages for
  98 // different parts of the window, but it should also be possible to override
  99 // just ShowHelp() both for backwards compatibility and just because most
 100 // often the help does not, in fact, depend on the position and so
 101 // implementing just ShowHelp() is simpler and more natural, so by default
 102 // ShowHelpAtPoint() forwards to ShowHelp(). But this means that
 103 // wxSimpleHelpProvider has to override ShowHelp() and not ShowHelpAtPoint()
 104 // for backwards compatibility as otherwise the existing code deriving from it
 105 // and overriding ShowHelp() but calling the base class version wouldn't work
 106 // any more, which forces us to use a rather ugly hack and pass the extra
 107 // parameters of ShowHelpAtPoint() to ShowHelp() via member variables.
 108 class WXDLLIMPEXP_CORE wxHelpProvider
 109 {
 110 public:
 111     // get/set the current (application-global) help provider (Set() returns
 112     // the previous one)
 113     static wxHelpProvider *Set(wxHelpProvider *helpProvider)
 114     {
 115         wxHelpProvider *helpProviderOld = ms_helpProvider;
 116         ms_helpProvider = helpProvider;
 117         return helpProviderOld;
 118     }
 119
 120     // unlike some other class, the help provider is not created on demand,
 121     // this must be explicitly done by the application
 122     static wxHelpProvider *Get() { return ms_helpProvider; }
 123
 124     // get the help string (whose interpretation is help provider dependent
 125     // except that empty string always means that no help is associated with
 126     // the window) for this window
 127     virtual wxString GetHelp(const wxWindowBase *window) = 0;
 128
 129     // do show help for the given window (uses window->GetHelpAtPoint()
 130     // internally if applicable), return true if it was done or false
 131     // if no help available for this window
 132     virtual bool ShowHelpAtPoint(wxWindowBase *window,
 133                                  const wxPoint& pt,
 134                                  wxHelpEvent::Origin origin)
 135     {
 136         wxCHECK_MSG( window, false, wxT("window must not be NULL") );
 137
 138         m_helptextAtPoint = pt;
 139         m_helptextOrigin = origin;
 140
 141         return ShowHelp(window);
 142     }
 143
 144     // show help for the given window, see ShowHelpAtPoint() above
 145     virtual bool ShowHelp(wxWindowBase * WXUNUSED(window)) { return false; }
 146
 147     // associate the text with the given window or id: although all help
 148     // providers have these functions to allow making wxWindow::SetHelpText()
 149     // work, not all of them implement them
 150     virtual void AddHelp(wxWindowBase *window, const wxString& text);
 151
 152     // this version associates the given text with all window with this id
 153     // (may be used to set the same help string for all [Cancel] buttons in
 154     // the application, for example)
 155     virtual void AddHelp(wxWindowID id, const wxString& text);
 156
 157     // removes the association
 158     virtual void RemoveHelp(wxWindowBase* window);
 159
 160     // virtual dtor for any base class
 161     virtual ~wxHelpProvider();
 162
 163 protected:
 164     wxHelpProvider()
 165         : m_helptextAtPoint(wxDefaultPosition),
 166           m_helptextOrigin(wxHelpEvent::Origin_Unknown)
 167     {
 168     }
 169
 170     // helper method used by ShowHelp(): returns the help string to use by
 171     // using m_helptextAtPoint/m_helptextOrigin if they're set or just GetHelp
 172     // otherwise
 173     wxString GetHelpTextMaybeAtPoint(wxWindowBase *window);
 174
 175
 176     // parameters of the last ShowHelpAtPoint() call, used by ShowHelp()
 177     wxPoint m_helptextAtPoint;
 178     wxHelpEvent::Origin m_helptextOrigin;
 179
 180 private:
 181     static wxHelpProvider *ms_helpProvider;
 182 };
 183
 184 WX_DECLARE_EXPORTED_HASH_MAP( wxUIntPtr, wxString, wxIntegerHash,
 185                               wxIntegerEqual, wxSimpleHelpProviderHashMap );
 186
 187 // wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
 188 // only plain text help strings and shows the string associated with the
 189 // control (if any) in a tooltip
 190 class WXDLLIMPEXP_CORE wxSimpleHelpProvider : public wxHelpProvider
 191 {
 192 public:
 193     // implement wxHelpProvider methods
 194     virtual wxString GetHelp(const wxWindowBase *window);
 195
 196     // override ShowHelp() and not ShowHelpAtPoint() as explained above
 197     virtual bool ShowHelp(wxWindowBase *window);
 198
 199     virtual void AddHelp(wxWindowBase *window, const wxString& text);
 200     virtual void AddHelp(wxWindowID id, const wxString& text);
 201     virtual void RemoveHelp(wxWindowBase* window);
 202
 203 protected:
 204     // we use 2 hashes for storing the help strings associated with windows
 205     // and the ids
 206     wxSimpleHelpProviderHashMap m_hashWindows,
 207                                 m_hashIds;
 208 };
 209
 210 // wxHelpControllerHelpProvider is an implementation of wxHelpProvider which supports
 211 // both context identifiers and plain text help strings. If the help text is an integer,
 212 // it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the string
 213 // in a tooltip as per wxSimpleHelpProvider.
 214 class WXDLLIMPEXP_CORE wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 215 {
 216 public:
 217     // Note that it doesn't own the help controller. The help controller
 218     // should be deleted separately.
 219     wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL);
 220
 221     // implement wxHelpProvider methods
 222
 223     // again (see above): this should be ShowHelpAtPoint() but we need to
 224     // override ShowHelp() to avoid breaking existing code
 225     virtual bool ShowHelp(wxWindowBase *window);
 226
 227     // Other accessors
 228     void SetHelpController(wxHelpControllerBase* hc) { m_helpController = hc; }
 229     wxHelpControllerBase* GetHelpController() const { return m_helpController; }
 230
 231 protected:
 232     wxHelpControllerBase*   m_helpController;
 233
 234     wxDECLARE_NO_COPY_CLASS(wxHelpControllerHelpProvider);
 235 };
 236
 237 // Convenience function for turning context id into wxString
 238 WXDLLIMPEXP_CORE wxString wxContextId(int id);
 239
 240 #endif // wxUSE_HELP
 241
 242 #endif // _WX_CSHELP_H_
 243