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