made it possible to associate context help to a region of a window

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@39675 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/helpprov.tex

@@ -18,16 +18,18 @@ No base class
 
 \helpref{wxContextHelp}{wxcontexthelp}, \helpref{wxContextHelpButton}{wxcontexthelpbutton}, 
 \helpref{wxSimpleHelpProvider}{wxsimplehelpprovider}, \helpref{wxHelpControllerHelpProvider}{wxhelpcontrollerhelpprovider}, 
-\helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, \helpref{wxWindow::GetHelpText}{wxwindowgethelptext}
+\helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, \helpref{wxWindow::GetHelpTextAtPoint}{wxwindowgethelptextatpoint}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{wxHelpProvider::\destruct{wxHelpProvider}}\label{wxhelpproviderdtor}
 
 \func{}{\destruct{wxHelpProvider}}{\void}
 
 Virtual destructor for any base class.
 
+
 \membersection{wxHelpProvider::AddHelp}\label{wxhelpprovideraddhelp}
 
 \func{void}{AddHelp}{\param{wxWindowBase* }{window}, \param{const wxString\& }{text}}
@@ -36,6 +38,7 @@ Associates the text with the given window or id. Although all help
 providers have these functions to allow making \helpref{wxWindow::SetHelpText}{wxwindowsethelptext} 
 work, not all of them implement the functions.
 
+
 \membersection{wxHelpProvider::Get}\label{wxhelpproviderget}
 
 \func{wxHelpProvider*}{Get}{\void}
@@ -43,6 +46,7 @@ work, not all of them implement the functions.
 Unlike some other classes, the help provider is not created on demand.
 This must be explicitly done by the application.
 
+
 \membersection{wxHelpProvider::GetHelp}\label{wxhelpprovidergethelp}
 
 \func{wxString}{GetHelp}{\param{const wxWindowBase* }{window}}
@@ -57,6 +61,7 @@ This version associates the given text with all windows with this id.
 May be used to set the same help string for all Cancel buttons in
 the application, for example.
 
+
 \membersection{wxHelpProvider::RemoveHelp}\label{wxhelpproviderremovehelp}
 
 \func{void}{RemoveHelp}{\param{wxWindowBase* }{window}}
@@ -65,6 +70,7 @@ Removes the association between the window pointer and the help text. This is
 called by the wxWindow destructor. Without this, the table of help strings will fill up
 and when window pointers are reused, the wrong help string will be found.
 
+
 \membersection{wxHelpProvider::Set}\label{wxhelpproviderset}
 
 \func{wxHelpProvider*}{Set}{\param{wxHelpProvider* }{helpProvider}}
@@ -72,13 +78,38 @@ and when window pointers are reused, the wrong help string will be found.
 Get/set the current, application-wide help provider. Returns
 the previous one.
 
+
+\membersection{wxHelpProvider::ShowHelpAtPoint}\label{wxhelpprovidershowhelpatpoint}
+
+\func{bool}{ShowHelpAtPoint}{\param{wxWindowBase* }{window}, \param{const wxPoint & }{point}, \param{wxHelpEvent::Origin }{origin}}
+
+This function may be overridden to show help for the window when it should
+depend on the position inside the window, By default this method forwards to 
+\helpref{ShowHelp}{wxhelpprovidershowhelp}, so it is enough to only implement
+the latter if the help doesn't depend on the position.
+
+Returns \true if help was shown, or \false if no help was available for this
+window.
+
+\wxheading{Parameters}
+
+\docparam{window}{Window to show help text for.}
+
+\docparam{point}{Coordinates of the mouse at the moment of help event emission.}
+
+\docparam{origin}{Help event origin, see also \helpref{wxHelpEvent::Origin}{wxhelpeventorigin}.}
+
+\newsince{2.7.0}
+
+
 \membersection{wxHelpProvider::ShowHelp}\label{wxhelpprovidershowhelp}
 
 \func{bool}{ShowHelp}{\param{wxWindowBase* }{window}}
 
-Shows help for the given window. Uses \helpref{GetHelp}{wxhelpprovidergethelp} internally if
-applicable.
+Shows help for the given window. Override this function if the help doesn't
+depend on the exact position inside the window, otherwise you need to override 
+\helpref{ShowHelpAtPoint}{wxhelpprovidershowhelpatpoint}.
 
-Returns true if it was done, or false if no help was available
-for this window.
+Returns \true if help was shown, or \false if no help was available for this
+window.
 

docs/latex/wx/hprovcnt.tex

@@ -22,7 +22,7 @@ id to a string for passing to \helpref{wxWindow::SetHelpText}{wxwindowsethelptex
 
 \helpref{wxHelpProvider}{wxhelpprovider}, \helpref{wxSimpleHelpProvider}{wxsimplehelpprovider}, 
 \helpref{wxContextHelp}{wxcontexthelp}, \helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, 
-\helpref{wxWindow::GetHelpText}{wxwindowgethelptext}
+\helpref{wxWindow::GetHelpTextAtPoint}{wxwindowgethelptextatpoint}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

docs/latex/wx/hprovsmp.tex

@@ -16,5 +16,5 @@ control (if any) in a tooltip.
 
 \helpref{wxHelpProvider}{wxhelpprovider}, \helpref{wxHelpControllerHelpProvider}{wxhelpcontrollerhelpprovider}, 
 \helpref{wxContextHelp}{wxcontexthelp}, \helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, 
-\helpref{wxWindow::GetHelpText}{wxwindowgethelptext}
+\helpref{wxWindow::GetHelpTextAtPoint}{wxwindowgethelptextatpoint}
 

docs/latex/wx/window.tex

@@ -1016,6 +1016,23 @@ handle, such as {\bf HWND} for Windows, {\bf Widget} for Motif, {\bf GtkWidget}
 \perlnote{This method will return an integer in wxPerl.}
 
 
+\membersection{wxWindow::GetHelpTextAtPoint}\label{wxwindowgethelptextatpoint}
+
+\constfunc{virtual wxString}{GetHelpTextAtPoint}{\param{const wxPoint &}{point}, \param{wxHelpEvent::Origin }{origin}}
+
+Gets the help text to be used as context-sensitive help for this window. This
+method should be overridden if the help message depends on the position inside
+the window, otherwise \helpref{GetHelpText}{wxwindowgethelptext} can be used.
+
+\wxheading{Parameters}
+
+\docparam{point}{Coordinates of the mouse at the moment of help event emission.}
+
+\docparam{origin}{Help event origin, see also \helpref{wxHelpEvent::Origin}{wxhelpeventorigin}.}
+
+\newsince{2.7.0}
+
+
 \membersection{wxWindow::GetHelpText}\label{wxwindowgethelptext}
 
 \constfunc{virtual wxString}{GetHelpText}{\void}
@@ -1027,7 +1044,7 @@ and not in the window object itself.
 
 \wxheading{See also}
 
-\helpref{SetHelpText}{wxwindowsethelptext}, \helpref{wxHelpProvider}{wxhelpprovider}
+\helpref{SetHelpText}{wxwindowsethelptext}, \helpref{GetHelpTextAtPoint}{wxwindowgethelptextatpoint}, \helpref{wxHelpProvider}{wxhelpprovider}
 
 
 \membersection{wxWindow::GetId}\label{wxwindowgetid}