X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/655719367ac5e131d9642e5783f3ecf64d1a3385..e10972f6c1436a6dcd5427b4e3913bb0f398e045:/include/wx/cshelp.h?ds=sidebyside diff --git a/include/wx/cshelp.h b/include/wx/cshelp.h index eb21207da1..87e0dbd137 100644 --- a/include/wx/cshelp.h +++ b/include/wx/cshelp.h @@ -6,15 +6,11 @@ // 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__ - -#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA) - #pragma interface "cshelp.h" -#endif +#ifndef _WX_CSHELP_H_ +#define _WX_CSHELP_H_ #include "wx/defs.h" @@ -27,6 +23,8 @@ #include "wx/bmpbuttn.h" #endif +#include "wx/event.h" + // ---------------------------------------------------------------------------- // classes used to implement context help UI // ---------------------------------------------------------------------------- @@ -38,10 +36,10 @@ * window for the application to display help for. */ -class WXDLLEXPORT wxContextHelp : public wxObject +class WXDLLIMPEXP_CORE wxContextHelp : public wxObject { public: - wxContextHelp(wxWindow* win = NULL, bool beginHelp = TRUE); + wxContextHelp(wxWindow* win = NULL, bool beginHelp = true); virtual ~wxContextHelp(); bool BeginContextHelp(wxWindow* win); @@ -54,7 +52,7 @@ public: 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) @@ -67,7 +65,7 @@ private: * to put the application into context help mode. */ -class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton +class WXDLLIMPEXP_CORE wxContextHelpButton : public wxBitmapButton { public: wxContextHelpButton(wxWindow* parent, @@ -95,7 +93,20 @@ private: // // 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 @@ -116,10 +127,23 @@ public: // 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, wxT("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() @@ -137,22 +161,42 @@ public: // 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; }; -WX_DECLARE_EXPORTED_HASH_MAP( long, wxString, wxIntegerHash, wxIntegerEqual, - wxLongToStringHashMap ); +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 -class WXDLLEXPORT wxSimpleHelpProvider : public wxHelpProvider +class WXDLLIMPEXP_CORE wxSimpleHelpProvider : public wxHelpProvider { public: // implement wxHelpProvider methods virtual wxString GetHelp(const wxWindowBase *window); + + // override ShowHelp() and not ShowHelpAtPoint() as explained above virtual bool ShowHelp(wxWindowBase *window); + virtual void AddHelp(wxWindowBase *window, const wxString& text); virtual void AddHelp(wxWindowID id, const wxString& text); virtual void RemoveHelp(wxWindowBase* window); @@ -160,22 +204,25 @@ public: protected: // we use 2 hashes for storing the help strings associated with windows // and the ids - wxLongToStringHashMap m_hashWindows, - m_hashIds; + wxSimpleHelpProviderHashMap m_hashWindows, + m_hashIds; }; // 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 WXDLLEXPORT wxHelpControllerHelpProvider : public 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); + wxHelpControllerHelpProvider(wxHelpControllerBase* hc = 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 @@ -185,13 +232,13 @@ public: protected: wxHelpControllerBase* m_helpController; - DECLARE_NO_COPY_CLASS(wxHelpControllerHelpProvider) + wxDECLARE_NO_COPY_CLASS(wxHelpControllerHelpProvider); }; // Convenience function for turning context id into wxString -WXDLLEXPORT wxString wxContextId(int id); +WXDLLIMPEXP_CORE wxString wxContextId(int id); #endif // wxUSE_HELP -#endif // _WX_CSHELPH__ +#endif // _WX_CSHELP_H_