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