Added context-sensitive help docs

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

diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index c9710911c99ae78b5d38908c1c9f512dff45e73f..dc38e4f0012ff0f8eabeec1a508506f6c4e19d9e 100644 (file)
--- a/docs/latex/wx/category.tex
+++ b/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}
 
 \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
 {\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{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}
 \twocolitem{\helpref{wxLayoutAlgorithm}{wxlayoutalgorithm}}{An alternative window layout facility}
 \twocolitem{\helpref{wxProcess}{wxprocess}}{Process class}
 \twocolitem{\helpref{wxTimer}{wxtimer}}{Timer class}

diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index f5ea4f4356715a1fe3685c55b3ac469063d7511c..9503bd0952997e80e5243f0cc420f9e651a492a7 100644 (file)
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -117,7 +117,9 @@
 \input gridsizr.tex
 \input hash.tex
 \input helpinst.tex
 \input gridsizr.tex
 \input hash.tex
 \input helpinst.tex

+\input hprovcnt.tex

 \input helpevt.tex
 \input helpevt.tex

+\input helpprov.tex

 \input htcell.tex
 \input htcolor.tex
 \input htcontnr.tex
 \input htcell.tex
 \input htcolor.tex
 \input htcontnr.tex


@@ -243,6 +245,7 @@
 \input scrlwevt.tex
 \input scrolevt.tex
 \input scrolwin.tex
 \input scrlwevt.tex
 \input scrolevt.tex
 \input scrolwin.tex

+\input hprovsmp.tex

 \input sngchdlg.tex
 \input size.tex
 \input sizeevt.tex
 \input sngchdlg.tex
 \input size.tex
 \input sizeevt.tex

diff --git a/docs/latex/wx/cshelp.tex b/docs/latex/wx/cshelp.tex
index fc7b632f199bee22424485ac032fb784221a382d..8e3d862ca28b484f20caaca14f247be53dd84c90 100644 (file)
--- a/docs/latex/wx/cshelp.tex
+++ b/docs/latex/wx/cshelp.tex
@@ -10,6 +10,17 @@ For example:
   wxContextHelp contextHelp(myWindow);
 \end{verbatim}
 
   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}
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}


@@ -20,8 +31,9 @@ For example:
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxHelpEvent}{wxhelpevent},\rtfsp
-\helpref{wxHelpController}{wxhelpcontroller}
+\helpref{wxHelpEvent}{wxhelpevent}, 
+\helpref{wxHelpController}{wxhelpcontroller}, 
+\helpref{wxContextHelpButton}{wxcontexthelpbutton}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \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.
 
 
 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.
+

diff --git a/docs/latex/wx/helpinst.tex b/docs/latex/wx/helpinst.tex
index c93b02c26398de25361201a53579d13631f4b66d..7aae0d97e7ada32e36a4b62ed3613d00d729b137 100644 (file)
--- a/docs/latex/wx/helpinst.tex
+++ b/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.
 
 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}}
 \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.
 
 
 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},
 \membersection{wxHelpController::GetFrameParameters}\label{wxhelpcontrollergetframeparameters}
 
 \func{virtual wxFrame *}{GetFrameParameters}{\param{const wxSize * }{size = NULL}, \param{const wxPoint * }{pos = NULL},

diff --git a/docs/latex/wx/helpprov.tex b/docs/latex/wx/helpprov.tex
new file mode 100644 (file)
index 0000000..448c588
--- /dev/null
+++ b/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.
+

diff --git a/docs/latex/wx/hprovcnt.tex b/docs/latex/wx/hprovcnt.tex
new file mode 100644 (file)
index 0000000..c8a774e
--- /dev/null
+++ b/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.
+

diff --git a/docs/latex/wx/hprovsmp.tex b/docs/latex/wx/hprovsmp.tex
new file mode 100644 (file)
index 0000000..46fd475
--- /dev/null
+++ b/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}
+

diff --git a/docs/latex/wx/wx.hpj b/docs/latex/wx/wx.hpj
index c9c81be035a6b9c63bdcd9254b7e361943534c6e..7d53311fdd291152f5e7cd4c423a6dae9b38c957 100644 (file)
--- a/docs/latex/wx/wx.hpj
+++ b/docs/latex/wx/wx.hpj
@@ -1,5 +1,5 @@
 [OPTIONS]
 [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
 TITLE=wxWindows Manual
 CONTENTS=Contents
 COMPRESS=HIGH