feaca34f34
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@15704 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
252 lines
10 KiB
TeX
252 lines
10 KiB
TeX
\section{\class{wxHelpController}}\label{wxhelpcontroller}
|
|
|
|
This is a family of classes by which
|
|
applications may invoke a help viewer to provide on-line help.
|
|
|
|
A help controller allows an application to display help, at the contents
|
|
or at a particular topic, and shut the help program down on termination.
|
|
This avoids proliferation of many instances of the help viewer whenever the
|
|
user requests a different topic via the application's menus or buttons.
|
|
|
|
Typically, an application will create a help controller instance
|
|
when it starts, and immediately call {\bf Initialize}\rtfsp
|
|
to associate a filename with it. The help viewer will only get run, however,
|
|
just before the first call to display something.
|
|
|
|
Most help controller classes actually derive from wxHelpControllerBase and have
|
|
names of the form wxXXXHelpController or wxHelpControllerXXX. An
|
|
appropriate class is aliased to the name wxHelpController for each platform, as follows:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item On Windows, wxWinHelpController is used.
|
|
\item On all other platforms, wxHtmlHelpController is used if wxHTML is
|
|
compiled into wxWindows; otherwise wxExtHelpController is used (for invoking an external
|
|
browser).
|
|
\end{itemize}
|
|
|
|
The remaining help controller classess need to be named
|
|
explicitly by an application that wishes to make use of them.
|
|
|
|
There are currently the following help controller classes defined:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item wxWinHelpController, for controlling Windows Help.
|
|
\item wxCHMHelpController, for controlling MS HTML Help. To use this, you need to set wxUSE\_MS\_HTML\_HELP
|
|
to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you don't need
|
|
VC++ specific htmlhelp.lib because wxWindows loads neccessary DLL at runtime and so it
|
|
works with all compilers).
|
|
\item wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime is
|
|
not available, \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}. You need to provide
|
|
{\bf both} CHM and HTB versions of the help file. For 32bit Windows only.
|
|
\item wxExtHelpController, for controlling external browsers under Unix.
|
|
The default browser is Netscape Navigator. The 'help' sample shows its use.
|
|
\item \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, a sophisticated help controller using \helpref{wxHTML}{wxhtml}, in
|
|
a similar style to the Microsoft HTML Help viewer and using some of the same files.
|
|
Although it has an API compatible with other help controllers, it has more advanced features, so it is
|
|
recommended that you use the specific API for this class instead.
|
|
\end{itemize}
|
|
|
|
\wxheading{Derived from}
|
|
|
|
wxHelpControllerBase\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/help.h> (wxWindows chooses the appropriate help controller class)\\
|
|
<wx/helpbase.h> (wxHelpControllerBase class)\\
|
|
<wx/helpwin.h> (Windows Help controller)\\
|
|
<wx/msw/helpchm.h> (MS HTML Help controller)\\
|
|
<wx/generic/helpext.h> (external HTML browser controller)\\
|
|
<wx/html/helpctrl.h> (wxHTML based help controller: wxHtmlHelpController)
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, \helpref{wxHTML}{wxhtml}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxHelpController::wxHelpController}
|
|
|
|
\func{}{wxHelpController}{\void}
|
|
|
|
Constructs a help instance object, but does not invoke the help viewer.
|
|
|
|
\membersection{wxHelpController::\destruct{wxHelpController}}
|
|
|
|
\func{}{\destruct{wxHelpController}}{\void}
|
|
|
|
Destroys the help instance, closing down the viewer if it is running.
|
|
|
|
\membersection{wxHelpController::Initialize}\label{wxhelpcontrollerinitialize}
|
|
|
|
\func{virtual void}{Initialize}{\param{const wxString\& }{file}}
|
|
|
|
\func{virtual void}{Initialize}{\param{const wxString\& }{file}, \param{int}{ server}}
|
|
|
|
Initializes the help instance with a help filename, and optionally a server socket
|
|
number if using wxHelp (now obsolete). Does not invoke the help viewer.
|
|
This must be called directly after the help instance object is created and before
|
|
any attempts to communicate with the viewer.
|
|
|
|
You may omit the file extension and a suitable one will be chosen. For
|
|
wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for
|
|
a suitable file. For WinHelp, the hlp extension is appended.
|
|
|
|
\membersection{wxHelpController::DisplayBlock}\label{wxhelpcontrollerdisplayblock}
|
|
|
|
\func{virtual bool}{DisplayBlock}{\param{long}{ blockNo}}
|
|
|
|
If the help viewer is not running, runs it and displays the file at the given block number.
|
|
|
|
{\it WinHelp:} Refers to the context number.
|
|
|
|
{\it MS HTML Help:} Refers to the context number.
|
|
|
|
{\it External HTML help:} the same as for \helpref{wxHelpController::DisplaySection}{wxhelpcontrollerdisplaysection}.
|
|
|
|
{\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
|
|
|
|
This function is for backward compatibility only, and applications should use \helpref{wxHelpController}{wxhelpcontrollerdisplaysection} instead.
|
|
|
|
\membersection{wxHelpController::DisplayContents}\label{wxhelpcontrollerdisplaycontents}
|
|
|
|
\func{virtual bool}{DisplayContents}{\void}
|
|
|
|
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}}
|
|
|
|
If the help viewer is not running, runs it and displays the given section.
|
|
|
|
The interpretation of {\it section} differs between help viewers. For most viewers,
|
|
this call is equivalent to KeywordSearch. For MS HTML Help, wxHTML help and external HTML help,
|
|
if {\it section} has a .htm
|
|
or .html extension, that HTML file will be displayed; otherwise
|
|
a keyword search is done.
|
|
|
|
\func{virtual bool}{DisplaySection}{\param{int}{ sectionNo}}
|
|
|
|
If the help viewer is not running, runs it and displays the given section.
|
|
|
|
{\it WinHelp, MS HTML Help} {\it sectionNo} is a context id.
|
|
|
|
{\it External HTML help:} wxExtHelpController implements {\it sectionNo} as an id in a map file, which is of the form:
|
|
|
|
\begin{verbatim}
|
|
0 wx.html ; Index
|
|
1 wx34.html#classref ; Class reference
|
|
2 wx204.html ; Function reference
|
|
\end{verbatim}
|
|
|
|
{\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
|
|
|
|
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},
|
|
\param{bool *}{newFrameEachTime = NULL}}
|
|
|
|
wxHtmlHelpController returns the frame, size and position.
|
|
|
|
For all other help controllers, this function does nothing
|
|
and just returns NULL.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{viewer}{This defaults to "netscape" for wxExtHelpController.}
|
|
|
|
\docparam{flags}{This defaults to wxHELP\_NETSCAPE for wxExtHelpController, indicating
|
|
that the viewer is a variant of Netscape Navigator.}
|
|
|
|
\membersection{wxHelpController::KeywordSearch}\label{wxhelpcontrollerkeywordsearch}
|
|
|
|
\func{virtual bool}{KeywordSearch}{\param{const wxString\& }{keyWord}}
|
|
|
|
If the help viewer is not running, runs it, and searches for sections matching the given keyword. If one
|
|
match is found, the file is displayed at this section.
|
|
|
|
{\it WinHelp, MS HTML Help:} If more than one match is found,
|
|
the first topic is displayed.
|
|
|
|
{\it External HTML help, simple wxHTML help:} If more than one match is found,
|
|
a choice of topics is displayed.
|
|
|
|
{\it wxHtmlHelpController:} see \helpref{wxHtmlHelpController::KeywordSearch}{wxhtmlhelpcontrollerkeywordsearch}.
|
|
|
|
\membersection{wxHelpController::LoadFile}\label{wxhelpcontrollerloadfile}
|
|
|
|
\func{virtual bool}{LoadFile}{\param{const wxString\& }{file = ""}}
|
|
|
|
If the help viewer is not running, runs it and loads the given file.
|
|
If the filename is not supplied or is
|
|
empty, the file specified in {\bf Initialize} is used. If the viewer is
|
|
already displaying the specified file, it will not be reloaded. This
|
|
member function may be used before each display call in case the user
|
|
has opened another file.
|
|
|
|
wxHtmlHelpController ignores this call.
|
|
|
|
\membersection{wxHelpController::OnQuit}\label{wxhelpcontrolleronquit}
|
|
|
|
\func{virtual bool}{OnQuit}{\void}
|
|
|
|
Overridable member called when this application's viewer is quit by the user.
|
|
|
|
This does not work for all help controllers.
|
|
|
|
\membersection{wxHelpController::SetFrameParameters}\label{wxhelpcontrollersetframeparameters}
|
|
|
|
\func{virtual void}{SetFrameParameters}{\param{const wxString \& }{title},
|
|
\param{const wxSize \& }{size}, \param{const wxPoint \& }{pos = wxDefaultPosition},
|
|
\param{bool }{newFrameEachTime = FALSE}}
|
|
|
|
For wxHtmlHelpController, the title is set (again with \%s indicating the
|
|
page title) and also the size and position of the frame if the frame is already
|
|
open. {\it newFrameEachTime} is ignored.
|
|
|
|
For all other help controllers this function has no effect.
|
|
|
|
\membersection{wxHelpController::SetViewer}\label{wxhelpcontrollersetviewer}
|
|
|
|
\func{virtual void}{SetViewer}{\param{const wxString\& }{viewer}, \param{long}{ flags}}
|
|
|
|
Sets detailed viewer information. So far this is only relevant to wxExtHelpController.
|
|
|
|
Some examples of usage:
|
|
|
|
\begin{verbatim}
|
|
m_help.SetViewer("kdehelp");
|
|
m_help.SetViewer("gnome-help-browser");
|
|
m_help.SetViewer("netscape", wxHELP_NETSCAPE);
|
|
\end{verbatim}
|
|
|
|
\membersection{wxHelpController::Quit}\label{wxhelpcontrollerquit}
|
|
|
|
\func{virtual bool}{Quit}{\void}
|
|
|
|
If the viewer is running, quits it by disconnecting.
|
|
|
|
For Windows Help, the viewer will only close if no other application is using it.
|
|
|