Document wxDataViewListStore

[wxWidgets.git] / include / wx / cshelp.h

diff --git a/include/wx/cshelp.h b/include/wx/cshelp.h
index 836e76e195fcc4153d5137d167cceeabe9113360..a165ab220eafe7d850b062677462469594935925 100644 (file)
--- a/include/wx/cshelp.h
+++ b/include/wx/cshelp.h
@@ -6,21 +6,24 @@
 // Created:     08/09/2000
 // RCS-ID:      $Id$
 // Copyright:   (c) 2000 Julian Smart, Vadim Zeitlin
 // Created:     08/09/2000
 // RCS-ID:      $Id$
 // Copyright:   (c) 2000 Julian Smart, Vadim Zeitlin

-// Licence:    wxWindows licence
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-#ifndef _WX_CSHELPH__
-#define _WX_CSHELPH__
-
-#ifdef __GNUG__
-    #pragma interface "cshelp.h"
-#endif
+#ifndef _WX_CSHELP_H_
+#define _WX_CSHELP_H_

 
 #include "wx/defs.h"
 
 #if wxUSE_HELP
 
 
 #include "wx/defs.h"
 
 #if wxUSE_HELP
 

+#include "wx/help.h"
+
+#include "wx/hashmap.h"
+#if wxUSE_BMPBUTTON

 #include "wx/bmpbuttn.h"
 #include "wx/bmpbuttn.h"

+#endif
+
+#include "wx/event.h"

 
 // ----------------------------------------------------------------------------
 // classes used to implement context help UI
 
 // ----------------------------------------------------------------------------
 // classes used to implement context help UI


@@ -33,10 +36,10 @@
  * window for the application to display help for.
  */
 
  * window for the application to display help for.
  */
 

-class WXDLLEXPORT wxContextHelp : public wxObject
+class WXDLLIMPEXP_CORE wxContextHelp : public wxObject

 {
 public:
 {
 public:

-    wxContextHelp(wxWindow* win = NULL, bool beginHelp = TRUE);
+    wxContextHelp(wxWindow* win = NULL, bool beginHelp = true);

     virtual ~wxContextHelp();
 
     bool BeginContextHelp(wxWindow* win);
     virtual ~wxContextHelp();
 
     bool BeginContextHelp(wxWindow* win);


@@ -49,19 +52,20 @@ public:
 
 protected:
     bool    m_inHelp;
 
 protected:
     bool    m_inHelp;

-    bool    m_status; // TRUE if the user left-clicked
+    bool    m_status; // true if the user left-clicked

 
 private:
     DECLARE_DYNAMIC_CLASS(wxContextHelp)
 };
 
 
 private:
     DECLARE_DYNAMIC_CLASS(wxContextHelp)
 };
 

+#if wxUSE_BMPBUTTON

 /*
  * wxContextHelpButton
  * You can add this to your dialogs (especially on non-Windows platforms)
  * to put the application into context help mode.
  */
 
 /*
  * wxContextHelpButton
  * You can add this to your dialogs (especially on non-Windows platforms)
  * to put the application into context help mode.
  */
 

-class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton
+class WXDLLIMPEXP_CORE wxContextHelpButton : public wxBitmapButton

 {
 public:
     wxContextHelpButton(wxWindow* parent,
 {
 public:
     wxContextHelpButton(wxWindow* parent,


@@ -73,23 +77,36 @@ public:
     void OnContextHelp(wxCommandEvent& event);
 
 private:
     void OnContextHelp(wxCommandEvent& event);
 
 private:

-    DECLARE_CLASS(wxContextHelpButton)
+    DECLARE_DYNAMIC_CLASS_NO_COPY(wxContextHelpButton)

     DECLARE_EVENT_TABLE()
 };
 
     DECLARE_EVENT_TABLE()
 };
 

-#endif // wxUSE_HELP
+#endif

 
 // ----------------------------------------------------------------------------
 // classes used to implement context help support
 // ----------------------------------------------------------------------------
 
 
 // ----------------------------------------------------------------------------
 // classes used to implement context help support
 // ----------------------------------------------------------------------------
 

-// wxHelpProvider is an ABC used by the program implementing context help to
+// wxHelpProvider is an abstract class used by the program implementing context help to

 // show the help text (or whatever: it may be HTML page or anything else) for
 // the given window.
 //
 // The current help provider must be explicitly set by the application using
 // wxHelpProvider::Set().
 // show the help text (or whatever: it may be HTML page or anything else) for
 // the given window.
 //
 // The current help provider must be explicitly set by the application using
 // wxHelpProvider::Set().

-class WXDLLEXPORT wxHelpProvider
+//
+// Special note about ShowHelpAtPoint() and ShowHelp(): we want to be able to
+// override ShowHelpAtPoint() when we need to use different help messages for
+// different parts of the window, but it should also be possible to override
+// just ShowHelp() both for backwards compatibility and just because most
+// often the help does not, in fact, depend on the position and so
+// implementing just ShowHelp() is simpler and more natural, so by default
+// ShowHelpAtPoint() forwards to ShowHelp(). But this means that
+// wxSimpleHelpProvider has to override ShowHelp() and not ShowHelpAtPoint()
+// for backwards compatibility as otherwise the existing code deriving from it
+// and overriding ShowHelp() but calling the base class version wouldn't work
+// any more, which forces us to use a rather ugly hack and pass the extra
+// parameters of ShowHelpAtPoint() to ShowHelp() via member variables.
+class WXDLLIMPEXP_CORE wxHelpProvider

 {
 public:
     // get/set the current (application-global) help provider (Set() returns
 {
 public:
     // get/set the current (application-global) help provider (Set() returns


@@ -110,10 +127,23 @@ public:
     // the window) for this window
     virtual wxString GetHelp(const wxWindowBase *window) = 0;
 
     // the window) for this window
     virtual wxString GetHelp(const wxWindowBase *window) = 0;
 

-    // do show help for the given window (uses GetHelp() internally if
-    // applicable), return TRUE if it was done or FALSE if no help available
-    // for this window
-    virtual bool ShowHelp(wxWindowBase *window) = 0;
+    // do show help for the given window (uses window->GetHelpAtPoint()
+    // internally if applicable), return true if it was done or false
+    // if no help available for this window
+    virtual bool ShowHelpAtPoint(wxWindowBase *window,
+                                 const wxPoint& pt,
+                                 wxHelpEvent::Origin origin)
+    {
+        wxCHECK_MSG( window, false, _T("window must not be NULL") );
+
+        m_helptextAtPoint = pt;
+        m_helptextOrigin = origin;
+
+        return ShowHelp(window);
+    }
+
+    // show help for the given window, see ShowHelpAtPoint() above
+    virtual bool ShowHelp(wxWindowBase * WXUNUSED(window)) { return false; }

 
     // associate the text with the given window or id: although all help
     // providers have these functions to allow making wxWindow::SetHelpText()
 
     // associate the text with the given window or id: although all help
     // providers have these functions to allow making wxWindow::SetHelpText()


@@ -125,31 +155,90 @@ public:
     // the application, for example)
     virtual void AddHelp(wxWindowID id, const wxString& text);
 
     // the application, for example)
     virtual void AddHelp(wxWindowID id, const wxString& text);
 

+    // removes the association
+    virtual void RemoveHelp(wxWindowBase* window);
+

     // virtual dtor for any base class
     virtual ~wxHelpProvider();
 
     // virtual dtor for any base class
     virtual ~wxHelpProvider();
 

+protected:
+    wxHelpProvider()
+        : m_helptextAtPoint(wxDefaultPosition),
+          m_helptextOrigin(wxHelpEvent::Origin_Unknown)
+    {
+    }
+
+    // helper method used by ShowHelp(): returns the help string to use by
+    // using m_helptextAtPoint/m_helptextOrigin if they're set or just GetHelp
+    // otherwise
+    wxString GetHelpTextMaybeAtPoint(wxWindowBase *window);
+
+
+    // parameters of the last ShowHelpAtPoint() call, used by ShowHelp()
+    wxPoint m_helptextAtPoint;
+    wxHelpEvent::Origin m_helptextOrigin;
+

 private:
     static wxHelpProvider *ms_helpProvider;
 };
 
 private:
     static wxHelpProvider *ms_helpProvider;
 };
 

+WX_DECLARE_EXPORTED_HASH_MAP( wxUIntPtr, wxString, wxIntegerHash,
+                              wxIntegerEqual, wxSimpleHelpProviderHashMap );
+

 // wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
 // only plain text help strings and shows the string associated with the
 // control (if any) in a tooltip
 // wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
 // only plain text help strings and shows the string associated with the
 // control (if any) in a tooltip

-class WXDLLEXPORT wxSimpleHelpProvider : public wxHelpProvider
+class WXDLLIMPEXP_CORE wxSimpleHelpProvider : public wxHelpProvider

 {
 public:
     // implement wxHelpProvider methods
     virtual wxString GetHelp(const wxWindowBase *window);
 {
 public:
     // implement wxHelpProvider methods
     virtual wxString GetHelp(const wxWindowBase *window);

+
+    // override ShowHelp() and not ShowHelpAtPoint() as explained above

     virtual bool ShowHelp(wxWindowBase *window);
     virtual bool ShowHelp(wxWindowBase *window);

+

     virtual void AddHelp(wxWindowBase *window, const wxString& text);
     virtual void AddHelp(wxWindowID id, const wxString& text);
     virtual void AddHelp(wxWindowBase *window, const wxString& text);
     virtual void AddHelp(wxWindowID id, const wxString& text);

+    virtual void RemoveHelp(wxWindowBase* window);

 
 protected:
     // we use 2 hashes for storing the help strings associated with windows
     // and the ids
 
 protected:
     // we use 2 hashes for storing the help strings associated with windows
     // and the ids

-    wxStringHashTable m_hashWindows,
-                     m_hashIds;
+    wxSimpleHelpProviderHashMap m_hashWindows,
+                                m_hashIds;

 };
 
 };
 

-#endif // _WX_CSHELPH__
+// wxHelpControllerHelpProvider is an implementation of wxHelpProvider which supports
+// both context identifiers and plain text help strings. If the help text is an integer,
+// it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the string
+// in a tooltip as per wxSimpleHelpProvider.
+class WXDLLIMPEXP_CORE wxHelpControllerHelpProvider : public wxSimpleHelpProvider
+{
+public:
+    // Note that it doesn't own the help controller. The help controller
+    // should be deleted separately.
+    wxHelpControllerHelpProvider(wxHelpControllerBase* hc = (wxHelpControllerBase*) NULL);
+
+    // implement wxHelpProvider methods
+
+    // again (see above): this should be ShowHelpAtPoint() but we need to
+    // override ShowHelp() to avoid breaking existing code
+    virtual bool ShowHelp(wxWindowBase *window);
+
+    // Other accessors
+    void SetHelpController(wxHelpControllerBase* hc) { m_helpController = hc; }
+    wxHelpControllerBase* GetHelpController() const { return m_helpController; }
+
+protected:
+    wxHelpControllerBase*   m_helpController;
+
+    DECLARE_NO_COPY_CLASS(wxHelpControllerHelpProvider)
+};
+
+// Convenience function for turning context id into wxString
+WXDLLIMPEXP_CORE wxString wxContextId(int id);
+
+#endif // wxUSE_HELP
+
+#endif // _WX_CSHELP_H_