home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / cshelp.h < prev    next >
C/C++ Source or Header  |  2002-08-31  |  7KB  |  186 lines
  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: cshelp.h,v 1.7 2002/08/31 11:29:09 GD Exp $
  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. #include "wx/bmpbuttn.h"
  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. /*
  60.  * wxContextHelpButton
  61.  * You can add this to your dialogs (especially on non-Windows platforms)
  62.  * to put the application into context help mode.
  63.  */
  64.  
  65. class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton
  66. {
  67. public:
  68.     wxContextHelpButton(wxWindow* parent,
  69.                         wxWindowID id = wxID_CONTEXT_HELP,
  70.                         const wxPoint& pos = wxDefaultPosition,
  71.                         const wxSize& size = wxDefaultSize,
  72.                         long style = wxBU_AUTODRAW);
  73.  
  74.     void OnContextHelp(wxCommandEvent& event);
  75.  
  76. private:
  77.     DECLARE_CLASS(wxContextHelpButton)
  78.     DECLARE_EVENT_TABLE()
  79. };
  80.  
  81. // ----------------------------------------------------------------------------
  82. // classes used to implement context help support
  83. // ----------------------------------------------------------------------------
  84.  
  85. // wxHelpProvider is an abstract class used by the program implementing context help to
  86. // show the help text (or whatever: it may be HTML page or anything else) for
  87. // the given window.
  88. //
  89. // The current help provider must be explicitly set by the application using
  90. // wxHelpProvider::Set().
  91. class WXDLLEXPORT wxHelpProvider
  92. {
  93. public:
  94.     // get/set the current (application-global) help provider (Set() returns
  95.     // the previous one)
  96.     static wxHelpProvider *Set(wxHelpProvider *helpProvider)
  97.     {
  98.         wxHelpProvider *helpProviderOld = ms_helpProvider;
  99.         ms_helpProvider = helpProvider;
  100.         return helpProviderOld;
  101.     }
  102.  
  103.     // unlike some other class, the help provider is not created on demand,
  104.     // this must be explicitly done by the application
  105.     static wxHelpProvider *Get() { return ms_helpProvider; }
  106.  
  107.     // get the help string (whose interpretation is help provider dependent
  108.     // except that empty string always means that no help is associated with
  109.     // the window) for this window
  110.     virtual wxString GetHelp(const wxWindowBase *window) = 0;
  111.  
  112.     // do show help for the given window (uses GetHelp() internally if
  113.     // applicable), return TRUE if it was done or FALSE if no help available
  114.     // for this window
  115.     virtual bool ShowHelp(wxWindowBase *window) = 0;
  116.  
  117.     // associate the text with the given window or id: although all help
  118.     // providers have these functions to allow making wxWindow::SetHelpText()
  119.     // work, not all of them implement them
  120.     virtual void AddHelp(wxWindowBase *window, const wxString& text);
  121.  
  122.     // this version associates the given text with all window with this id
  123.     // (may be used to set the same help string for all [Cancel] buttons in
  124.     // the application, for example)
  125.     virtual void AddHelp(wxWindowID id, const wxString& text);
  126.  
  127.     // removes the association
  128.     virtual void RemoveHelp(wxWindowBase* window);
  129.  
  130.     // virtual dtor for any base class
  131.     virtual ~wxHelpProvider();
  132.  
  133. private:
  134.     static wxHelpProvider *ms_helpProvider;
  135. };
  136.  
  137. // wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
  138. // only plain text help strings and shows the string associated with the
  139. // control (if any) in a tooltip
  140. class WXDLLEXPORT wxSimpleHelpProvider : public wxHelpProvider
  141. {
  142. public:
  143.     // implement wxHelpProvider methods
  144.     virtual wxString GetHelp(const wxWindowBase *window);
  145.     virtual bool ShowHelp(wxWindowBase *window);
  146.     virtual void AddHelp(wxWindowBase *window, const wxString& text);
  147.     virtual void AddHelp(wxWindowID id, const wxString& text);
  148.     virtual void RemoveHelp(wxWindowBase* window);
  149.  
  150. protected:
  151.     // we use 2 hashes for storing the help strings associated with windows
  152.     // and the ids
  153.     wxStringHashTable m_hashWindows,
  154.                      m_hashIds;
  155. };
  156.  
  157. // wxHelpControllerHelpProvider is an implementation of wxHelpProvider which supports
  158. // both context identifiers and plain text help strings. If the help text is an integer,
  159. // it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the string
  160. // in a tooltip as per wxSimpleHelpProvider.
  161. class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider
  162. {
  163. public:
  164.     // Note that it doesn't own the help controller. The help controller
  165.     // should be deleted separately.
  166.     wxHelpControllerHelpProvider(wxHelpControllerBase* hc = (wxHelpControllerBase*) NULL);
  167.  
  168.     // implement wxHelpProvider methods
  169.     virtual bool ShowHelp(wxWindowBase *window);
  170.  
  171.     // Other accessors
  172.     void SetHelpController(wxHelpControllerBase* hc) { m_helpController = hc; }
  173.     wxHelpControllerBase* GetHelpController() const { return m_helpController; }
  174.  
  175. protected:
  176.     wxHelpControllerBase*   m_helpController;
  177. };
  178.  
  179. // Convenience function for turning context id into wxString
  180. WXDLLEXPORT wxString wxContextId(int id);
  181.  
  182. #endif // wxUSE_HELP
  183.  
  184. #endif // _WX_CSHELPH__
  185.  
  186.