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