Added context-sensitive help docs

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

docs/latex/wx/category.tex

@@ -478,6 +478,19 @@ used internally by the HTML classes.
 \twocolitem{\helpref{wxFileSystemHandler}{wxfilesystemhandler}}{Class used to announce file system type}
 \end{twocollist}
 
+{\large {\bf Online help}}
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\helpref{wxHelpController}{wxhelpcontroller}}{Family of classes for controlling help windows}
+\twocolitem{\helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}}{HTML help controller class}
+\twocolitem{\helpref{wxContextHelp}{wxcontexthelp}}{Class to put application into context-sensitive help mode}
+\twocolitem{\helpref{wxContextHelpButton}{wxcontexthelpbutton}}{Button class for putting application into context-sensitive help mode}
+\twocolitem{\helpref{wxHelpProvider}{wxhelpprovider}}{Abstract class for context-sensitive help provision}
+\twocolitem{\helpref{wxSimpleHelpProvider}{wxsimplehelpprovider}}{Class for simple context-sensitive help provision}
+\twocolitem{\helpref{wxHelpControllerHelpProvider}{wxhelpcontrollerhelpprovider}}{Class for context-sensitive help provision via a help controller}
+\twocolitem{\helpref{wxToolTip}{wxtooltip}}{Class implementing tooltips}
+\end{twocollist}
+
 {\large {\bf Miscellaneous}}
 
 \begin{twocollist}\itemsep=0pt
@@ -486,7 +499,6 @@ used internally by the HTML classes.
 \twocolitem{\helpref{wxCmdLineParser}{wxcmdlineparser}}{Command line parser class}
 \twocolitem{\helpref{wxConfig}{wxconfigbase}}{Classes for configuration reading/writing (using either INI files or registry)}
 \twocolitem{\helpref{wxDllLoader}{wxdllloader}}{Class to work with shared libraries.}
-\twocolitem{\helpref{wxHelpController}{wxhelpcontroller}}{Family of classes for controlling help windows}
 \twocolitem{\helpref{wxLayoutAlgorithm}{wxlayoutalgorithm}}{An alternative window layout facility}
 \twocolitem{\helpref{wxProcess}{wxprocess}}{Process class}
 \twocolitem{\helpref{wxTimer}{wxtimer}}{Timer class}

docs/latex/wx/classes.tex

@@ -117,7 +117,9 @@
 \input gridsizr.tex
 \input hash.tex
 \input helpinst.tex
+\input hprovcnt.tex
 \input helpevt.tex
+\input helpprov.tex
 \input htcell.tex
 \input htcolor.tex
 \input htcontnr.tex
@@ -243,6 +245,7 @@
 \input scrlwevt.tex
 \input scrolevt.tex
 \input scrolwin.tex
+\input hprovsmp.tex
 \input sngchdlg.tex
 \input size.tex
 \input sizeevt.tex

docs/latex/wx/cshelp.tex

@@ -10,6 +10,17 @@ For example:
   wxContextHelp contextHelp(myWindow);
 \end{verbatim}
 
+There are a couple of ways to invoke this behaviour implicitly:
+
+\begin{itemize}
+\item Use the wxDIALOG\_EX\_CONTEXTHELP style for a dialog (Windows only). This will put a question mark
+in the titlebar, and Windows will put the application into context-sensitive help mode automatically,
+with further programming.
+\item Create a \helpref{wxContextHelpButton}{wxcontexthelpbutton}, whose predefined behaviour is to create a context help object.
+Normally you will write your application so that this button is only added to a dialog for non-Windows platforms
+(use wxDIALOG\_EX\_CONTEXTHELP on Windows).
+\end{itemize}
+
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
@@ -20,8 +31,9 @@ For example:
 
 \wxheading{See also}
 
-\helpref{wxHelpEvent}{wxhelpevent},\rtfsp
-\helpref{wxHelpController}{wxhelpcontroller}
+\helpref{wxHelpEvent}{wxhelpevent}, 
+\helpref{wxHelpController}{wxhelpcontroller}, 
+\helpref{wxContextHelpButton}{wxcontexthelpbutton}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -56,3 +68,63 @@ This function only returns when the event loop has finished.
 
 Ends context-sensitive help mode. Not normally called by the application.
 
+\section{\class{wxContextHelpButton}}\label{wxcontexthelpbutton}
+
+Instances of this class may be used to add a question mark button that when pressed, puts the
+application into context-help mode. It does this by creating a \helpref{wxContextHelp}{wxcontexthelp} object which itself
+generates a wxEVT\_HELP event when the user clicks on a window.
+
+On Windows, you may add a question-mark icon to a dialog by use of the wxDIALOG\_EX\_CONTEXTHELP extra style, but
+on other platforms you will have to add a button explicitly, usually next to OK, Cancel or similar buttons.
+
+\wxheading{Derived from}
+
+\helpref{wxBitmapButton}{wxbitmapbutton}\\
+\helpref{wxButton}{wxbutton}\\
+\helpref{wxControl}{wxcontrol}\\
+\helpref{wxWindow}{wxwindow}\\
+\helpref{wxEvtHandler}{wxevthandler}\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/cshelp.h>
+
+\wxheading{See also}
+
+\helpref{wxBitmapButton}{wxbitmapbutton}, \helpref{wxContextHelp}{wxcontexthelp}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxContextHelpButton::wxContextHelpButton}\label{wxcontexthelpbuttonconstr}
+
+\func{}{wxContextHelpButton}{\void}
+
+Default constructor.
+
+\func{}{wxContextHelpButton}{
+\param{wxWindow* }{parent}, 
+\param{wxWindowID }{id = wxID\_CONTEXT_HELP}, 
+\param{const wxPoint\& }{pos = wxDefaultPosition}, 
+\param{const wxSize\& }{size = wxDefaultSize}, 
+\param{long }{style = wxBU\_AUTODRAW}}
+
+Constructor, creating and showing a context help button.
+
+\wxheading{Parameters}
+
+\docparam{parent}{Parent window. Must not be NULL.}
+
+\docparam{id}{Button identifier. Defaults to wxID\_CONTEXT\_HELP.}
+
+\docparam{pos}{Button position.}
+
+\docparam{size}{Button size. If the default size (-1, -1) is specified then the button is sized
+appropriately for the question mark bitmap.}
+
+\docparam{style}{Window style.}
+
+\wxheading{Remarks}
+
+Normally you need pass only the parent window to the constructor, and use the defaults for the remaining parameters.
+

docs/latex/wx/helpinst.tex

@@ -116,6 +116,14 @@ This function is for backward compatibility only, and applications should use \h
 If the help viewer is not running, runs it and displays the
 contents.
 
+\membersection{wxHelpController::DisplayContextPopup}\label{wxhelpcontrollerdisplaycontextpopup}
+
+\func{virtual bool}{DisplayContextPopup}{\param{int }{contextId}}
+
+Displays the section as a popup window using a context id.
+
+Returns FALSE if unsuccessful or not implemented.
+
 \membersection{wxHelpController::DisplaySection}\label{wxhelpcontrollerdisplaysection}
 
 \func{virtual bool}{DisplaySection}{\param{const wxString\&}{ section}}
@@ -146,6 +154,14 @@ If the help viewer is not running, runs it and displays the given section.
 
 See also the help sample for notes on how to specify section numbers for various help file formats.
 
+\membersection{wxHelpController::DisplayTextPopup}\label{wxhelpcontrollerdisplaytextpopup}
+
+\func{virtual bool}{DisplayTextPopup}{\param{const wxString\&}{ text}, \param{const wxPoint\& }{pos}}
+
+Displays the text in a popup window, if possible.
+
+Returns FALSE if unsuccessful or not implemented.
+
 \membersection{wxHelpController::GetFrameParameters}\label{wxhelpcontrollergetframeparameters}
 
 \func{virtual wxFrame *}{GetFrameParameters}{\param{const wxSize * }{size = NULL}, \param{const wxPoint * }{pos = NULL},

docs/latex/wx/helpprov.tex

@@ -0,0 +1,74 @@
+\section{\class{wxHelpProvider}}\label{wxhelpprovider}
+
+wxHelpProvider is an abstract class used by a program implementing context-sensitive help to
+show the help text for the given window.
+
+The current help provider must be explicitly set by the application using
+wxHelpProvider::Set().
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{See also}
+
+\helpref{wxHelpContext}{wxhelpcontext}, \helpref{wxHelpContextButton}{wxhelpcontextbutton}, 
+\helpref{wxSimpleHelpProvider}{wxsimplehelpprovider}, \helpref{wxHelpControllerHelpProvider}{wxhelpcontrollerhelpprovider}, 
+\helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, \helpref{wxWindow::GetHelpText}{wxwindowgethelptext}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxHelpProvider::\destruct{wxHelpProvider}}\label{wxhelpproviderdtor}
+
+\func{}{\destruct{wxHelpProvider}}{\void}
+
+Virtual destructor for any base class.
+
+\membersection{wxHelpProvider::Set}\label{wxhelpproviderset}
+
+\func{wxHelpProvider*}{Set}{\param{wxHelpProvider* }{helpProvider}}
+
+Get/set the current, application-wide help provider. Returns
+the previous one.
+
+\membersection{wxHelpProvider::Get}\label{wxhelpproviderget}
+
+\func{wxHelpProvider*}{Get}{\void}
+
+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}}
+
+Gets the help string for this window. Its interpretation is dependent on the help provider
+except that empty string always means that no help is associated with
+the window.
+
+\membersection{wxHelpProvider::ShowHelp}\label{wxhelpprovidershowhelp}
+
+\func{bool}{ShowHelp}{\param{wxWindowBase* }{window}}
+
+Shows help for the given window. Uses \helpref{GetHelp}{wxhelpprovidergethelp} internally if
+applicable.
+
+Returns TRUE if it was done, or FALSE if no help was available
+for this window.
+
+\membersection{wxHelpProvider::AddHelp}\label{wxhelpprovideraddhelp}
+
+\func{void}{AddHelp}{\param{wxWindowBase* }{window}, \param{const wxString\& }{text}}
+
+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::AddHelp}\label{wxhelpprovideraddhelp}
+
+\func{void}{AddHelp}{\param{wxWindowID }{id}, \param{const wxString\& }{text}}
+
+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.
+

docs/latex/wx/hprovcnt.tex

@@ -0,0 +1,42 @@
+\section{\class{wxHelpControllerHelpProvider}}\label{wxhelpcontrollerhelpprovider}
+
+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.
+
+You can use the convenience function {\bf wxContextId} to convert an integer context
+id to a string for passing to \helpref{wxWindow::SetHelpText}{wxwindowsethelptext}.
+
+\wxheading{Derived from}
+
+\helpref{wxSimpleHelpProvider}{wxsimplehelpprovider}\\
+\helpref{wxHelpProvider}{wxhelpprovider}
+
+\wxheading{See also}
+
+\helpref{wxHelpProvider}{wxhelpprovider}, \helpref{wxSimpleHelpProvider}{wxsimplehelpprovider}, 
+\helpref{wxHelpContext}{wxhelpcontext}, \helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, 
+\helpref{wxWindow::GetHelpText}{wxwindowgethelptext}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxHelpControllerHelpProvider::wxHelpControllerHelpProvider}\label{wxhelpcontrollerhelpproviderwxhelpcontrollerhelpprovider}
+
+\func{}{wxHelpControllerHelpProvider}{\param{wxHelpControllerBase* }{hc = NULL}}
+
+Note that the instance doesn't own the help controller. The help controller
+should be deleted separately.
+
+\membersection{wxHelpControllerHelpProvider::SetHelpController}\label{wxhelpcontrollerhelpprovidersethelpcontroller}
+
+\func{void}{SetHelpController}{\param{wxHelpControllerBase* }{hc}}
+
+Sets the help controller associated with this help provider.
+
+\membersection{wxHelpControllerHelpProvider::GetHelpController}\label{wxhelpcontrollerhelpprovidergethelpcontroller}
+
+\constfunc{wxHelpControllerBase*}{GetHelpController}{\void}
+
+Returns the help controller associated with this help provider.
+

docs/latex/wx/hprovsmp.tex

@@ -0,0 +1,16 @@
+\section{\class{wxSimpleHelpProvider}}\label{wxsimplehelpprovider}
+
+wxSimpleHelpProvider is an implementation of \helpref{wxHelpProvider}{wxhelpprovider} which supports
+only plain text help strings, and shows the string associated with the
+control (if any) in a tooltip.
+
+\wxheading{Derived from}
+
+\helpref{wxHelpProvider}{wxhelpprovider}
+
+\wxheading{See also}
+
+\helpref{wxHelpProvider}{wxhelpprovider}, \helpref{wxHelpControllerHelpProvider}{wxhelpcontrollerhelpprovider}, 
+\helpref{wxHelpContext}{wxhelpcontext}, \helpref{wxWindow::SetHelpText}{wxwindowsethelptext}, 
+\helpref{wxWindow::GetHelpText}{wxwindowgethelptext}
+

docs/latex/wx/wx.hpj

@@ -1,5 +1,5 @@
 [OPTIONS]
-BMROOT=p:\wx23\wxWind~1\docs/latex/wx ; Assume that bitmaps are where the source is
+BMROOT=. ; Assume that bitmaps are where the source is
 TITLE=wxWindows Manual
 CONTENTS=Contents
 COMPRESS=HIGH