3755cfa64d
for embedded and modal help git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@36802 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
240 lines
10 KiB
TeX
240 lines
10 KiB
TeX
%
|
|
% automatically generated by HelpGen from
|
|
% htmlhelp.h at 02/May/99 19:58:53
|
|
%
|
|
|
|
\section{\class{wxHtmlHelpController}}\label{wxhtmlhelpcontroller}
|
|
|
|
This help controller provides an easy way of displaying HTML help in your
|
|
application (see {\it test} sample). The help system is based on {\bf books}
|
|
(see \helpref{AddBook}{wxhtmlhelpcontrolleraddbook}). A book is a logical
|
|
section of documentation (for example "User's Guide" or "Programmer's Guide" or
|
|
"C++ Reference" or "wxWidgets Reference"). The help controller can handle as
|
|
many books as you want.
|
|
|
|
Although this class has an API compatible with other wxWidgets
|
|
help controllers as documented by \helpref{wxHelpController}{wxhelpcontroller}, it
|
|
is recommended that you use the enhanced capabilities of wxHtmlHelpController's API.
|
|
|
|
wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as its
|
|
native format. The file format is described \helpref{here}{helpformat}.
|
|
Have a look at docs/html/ directory where sample project files are stored.
|
|
|
|
You can use Tex2RTF to produce these files when generating HTML, if you set {\bf htmlWorkshopFiles} to {\bf true} in
|
|
your tex2rtf.ini file. The commercial tool HelpBlocks (www.helpblocks.com) can also create these files.
|
|
|
|
\wxheading{Note}
|
|
|
|
It is strongly recommended to use preprocessed {\bf .hhp.cached} version of
|
|
projects. It can be either created on-the-fly (see
|
|
\helpref{SetTempDir}{wxhtmlhelpcontrollersettempdir}) or you can use
|
|
{\bf hhp2cached} utility from {\it utils/hhp2cached} to create it and
|
|
distribute the cached version together with helpfiles. See {\it samples/html/help}
|
|
sample for demonstration of its use.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{Information about wxBestHelpController}{wxhelpcontroller},
|
|
\helpref{wxHtmlHelpFrame}{wxhtmlhelpframe},
|
|
\helpref{wxHtmlHelpDialog}{wxhtmlhelpdialog},
|
|
\helpref{wxHtmlHelpWindow}{wxhtmlhelpwindow},
|
|
\helpref{wxHtmlModalHelp}{wxhtmlmodalhelp}
|
|
|
|
\wxheading{Derived from}
|
|
|
|
wxHelpControllerBase
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/html/helpctrl.h>
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxHtmlHelpController::wxHtmlHelpController}\label{wxhtmlhelpcontrollerwxhtmlhelpcontroller}
|
|
|
|
\func{}{wxHtmlHelpController}{\param{int }{style = wxHF\_DEFAULT\_STYLE}, \param{wxWindow* }{parentWindow = NULL}}
|
|
|
|
Constructor.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
{\it style} is a combination of these flags:
|
|
|
|
\begin{twocollist}\itemsep=0pt
|
|
\twocolitem{\windowstyle{wxHF\_TOOLBAR}}{The help window has a toolbar.}
|
|
\twocolitem{\windowstyle{wxHF\_FLAT\_TOOLBAR}}{The help window has a toolbar with flat buttons (aka coolbar).}
|
|
\twocolitem{\windowstyle{wxHF\_CONTENTS}}{The help window has a contents panel.}
|
|
\twocolitem{\windowstyle{wxHF\_INDEX}}{The help window has an index panel.}
|
|
\twocolitem{\windowstyle{wxHF\_SEARCH}}{The help window has a search panel.}
|
|
\twocolitem{\windowstyle{wxHF\_BOOKMARKS}}{The help window has bookmarks controls.}
|
|
\twocolitem{\windowstyle{wxHF\_OPEN\_FILES}}{Allows user to open arbitrary HTML document.}
|
|
\twocolitem{\windowstyle{wxHF\_PRINT}}{The toolbar contains "print" button.}
|
|
\twocolitem{\windowstyle{wxHF\_MERGE\_BOOKS}}{The contents pane does not show
|
|
book nodes. All books are merged together and appear as single book to the
|
|
user.}
|
|
\twocolitem{\windowstyle{wxHF\_ICONS\_BOOK}}{All nodes in contents pane
|
|
have a book icon. This is how Microsoft's HTML help viewer behaves.}
|
|
\twocolitem{\windowstyle{wxHF\_ICONS\_FOLDER}}{Book nodes in contents pane have
|
|
a book icon, book's sections have a folder icon. This is the default.}
|
|
\twocolitem{\windowstyle{wxHF\_ICONS\_BOOK\_CHAPTER}}{Both book nodes and
|
|
nodes of top-level sections of a book (i.e. chapters) have a book icon,
|
|
all other sections (sections, subsections, ...) have a folder icon.}
|
|
\twocolitem{\windowstyle{wxHF\_EMBEDDED}}{Specifies that the help controller controls an embedded window of class \helpref{wxHtmlHelpWindow}{wxhtmlhelpwindow} that
|
|
should not be destroyed when the controller is destroyed.}
|
|
\twocolitem{\windowstyle{wxHF\_DIALOG}}{Specifies that the help controller should create a dialog containing the help window.}
|
|
\twocolitem{\windowstyle{wxHF\_FRAME}}{Specifies that the help controller should create a frame containing the help window. This is the default if neither wxHF\_DIALOG nor wxHF\_EMBEDDED is specified.}
|
|
\twocolitem{\windowstyle{wxHF\_MODAL}}{Specifies that the help controller should create a modal dialog containing the help window (used with the wxHF\_DIALOG style).}
|
|
\twocolitem{\windowstyle{wxHF\_DEFAULT\_STYLE}}{{\tt wxHF\_TOOLBAR | wxHF\_CONTENTS
|
|
| wxHF\_INDEX | wxHF\_SEARCH | wxHF\_BOOKMARKS | wxHF\_PRINT}}
|
|
\end{twocollist}
|
|
|
|
{\it parentWindow} is an optional window to be used as the parent for the help window.
|
|
|
|
\membersection{wxHtmlHelpController::AddBook}\label{wxhtmlhelpcontrolleraddbook}
|
|
|
|
\func{bool}{AddBook}{\param{const wxFileName\& }{bookFile}, \param{bool }{showWaitMsg}}
|
|
|
|
\func{bool}{AddBook}{\param{const wxString\& }{bookUrl}, \param{bool }{showWaitMsg}}
|
|
|
|
Adds book (\helpref{.hhp file}{helpformat} - HTML Help Workshop project file) into the list of loaded books.
|
|
This must be called at least once before displaying any help.
|
|
|
|
{\it bookFile} or {\it bookUrl} may be either .hhp file or ZIP archive
|
|
that contains arbitrary number of .hhp files in
|
|
top-level directory. This ZIP archive must have .zip or .htb extension
|
|
(the latter stands for "HTML book"). In other words, {\tt AddBook(wxFileName("help.zip"))}
|
|
is possible and is the recommended way.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{showWaitMsg}{If true then a decoration-less window with progress message is displayed.}
|
|
\docparam{bookFile}{Help book filename. It is recommended to use this prototype
|
|
instead of the one taking URL, because it is less error-prone.}
|
|
\docparam{bookUrl}{Help book URL (note that syntax of filename and URL is
|
|
different on most platforms)}
|
|
|
|
\wxheading{Note}
|
|
|
|
Don't forget to install wxFileSystem ZIP handler with
|
|
{\tt wxFileSystem::AddHandler(new wxZipFSHandler);} before calling this method
|
|
on a .zip or .htb file!
|
|
|
|
\membersection{wxHtmlHelpController::CreateHelpDialog}\label{wxhtmlhelpcontrollercreatehelpdialog}
|
|
|
|
\func{virtual wxHtmlHelpDialog*}{CreateHelpDialog}{\param{wxHtmlHelpData * }{data}}
|
|
|
|
This protected virtual method may be overridden so that when specifying the wxHF\_DIALOG style, the controller
|
|
uses a different dialog.
|
|
|
|
\membersection{wxHtmlHelpController::CreateHelpFrame}\label{wxhtmlhelpcontrollercreatehelpframe}
|
|
|
|
\func{virtual wxHtmlHelpFrame*}{CreateHelpFrame}{\param{wxHtmlHelpData * }{data}}
|
|
|
|
This protected virtual method may be overridden so that the controller
|
|
uses a different frame.
|
|
|
|
\membersection{wxHtmlHelpController::Display}\label{wxhtmlhelpcontrollerdisplay}
|
|
|
|
\func{void}{Display}{\param{const wxString\& }{x}}
|
|
|
|
Displays page {\it x}. This is THE important function - it is used to display
|
|
the help in application.
|
|
|
|
You can specify the page in many ways:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item as direct filename of HTML document
|
|
\item as chapter name (from contents) or as a book name
|
|
\item as some word from index
|
|
\item even as any word (will be searched)
|
|
\end{itemize}
|
|
|
|
Looking for the page runs in these steps:
|
|
|
|
\begin{enumerate}\itemsep=0pt
|
|
\item try to locate file named x (if x is for example "doc/howto.htm")
|
|
\item try to open starting page of book named x
|
|
\item try to find x in contents (if x is for example "How To ...")
|
|
\item try to find x in index (if x is for example "How To ...")
|
|
\item switch to Search panel and start searching
|
|
\end{enumerate}
|
|
|
|
\func{void}{Display}{\param{const int }{id}}
|
|
|
|
This alternative form is used to search help contents by numeric IDs.
|
|
|
|
\pythonnote{The second form of this method is named DisplayId in
|
|
wxPython.}
|
|
|
|
\membersection{wxHtmlHelpController::DisplayContents}\label{wxhtmlhelpcontrollerdisplaycontents}
|
|
|
|
\func{void}{DisplayContents}{\void}
|
|
|
|
Displays help window and focuses contents panel.
|
|
|
|
\membersection{wxHtmlHelpController::DisplayIndex}\label{wxhtmlhelpcontrollerdisplayindex}
|
|
|
|
\func{void}{DisplayIndex}{\void}
|
|
|
|
Displays help window and focuses index panel.
|
|
|
|
\membersection{wxHtmlHelpController::KeywordSearch}\label{wxhtmlhelpcontrollerkeywordsearch}
|
|
|
|
\func{bool}{KeywordSearch}{\param{const wxString\& }{keyword}, \param{wxHelpSearchMode }{mode = wxHELP\_SEARCH\_ALL}}
|
|
|
|
Displays help window, focuses search panel and starts searching. Returns true
|
|
if the keyword was found. Optionally it searches through the index (mode =
|
|
wxHELP\_SEARCH\_INDEX), default the content (mode = wxHELP\_SEARCH\_ALL).
|
|
|
|
{\bf Important:} KeywordSearch searches only pages listed in .hhc file(s).
|
|
You should list all pages in the contents file.
|
|
|
|
\membersection{wxHtmlHelpController::ReadCustomization}\label{wxhtmlhelpcontrollerreadcustomization}
|
|
|
|
\func{void}{ReadCustomization}{\param{wxConfigBase* }{cfg}, \param{wxString }{path = wxEmptyString}}
|
|
|
|
Reads the controller's setting (position of window, etc.)
|
|
|
|
\membersection{wxHtmlHelpController::SetTempDir}\label{wxhtmlhelpcontrollersettempdir}
|
|
|
|
\func{void}{SetTempDir}{\param{const wxString\& }{path}}
|
|
|
|
Sets the path for storing temporary files - cached binary versions of index and contents files. These binary
|
|
forms are much faster to read. Default value is empty string (empty string means
|
|
that no cached data are stored). Note that these files are {\it not}
|
|
deleted when program exits.
|
|
|
|
Once created these cached files will be used in all subsequent executions
|
|
of your application. If cached files become older than corresponding .hhp
|
|
file (e.g. if you regenerate documentation) it will be refreshed.
|
|
|
|
\membersection{wxHtmlHelpController::SetTitleFormat}\label{wxhtmlhelpcontrollersettitleformat}
|
|
|
|
\func{void}{SetTitleFormat}{\param{const wxString\& }{format}}
|
|
|
|
Sets format of title of the frame. Must contain exactly one "\%s"
|
|
(for title of displayed HTML page).
|
|
|
|
\membersection{wxHtmlHelpController::UseConfig}\label{wxhtmlhelpcontrolleruseconfig}
|
|
|
|
\func{void}{UseConfig}{\param{wxConfigBase* }{config}, \param{const wxString\& }{rootpath = wxEmptyString}}
|
|
|
|
Associates {\it config} object with the controller.
|
|
|
|
If there is associated config object, wxHtmlHelpController automatically
|
|
reads and writes settings (including wxHtmlWindow's settings) when needed.
|
|
|
|
The only thing you must do is create wxConfig object and call UseConfig.
|
|
|
|
If you do not use {\it UseConfig}, wxHtmlHelpController will use
|
|
default wxConfig object if available (for details see
|
|
\helpref{wxConfigBase::Get}{wxconfigbaseget} and
|
|
\helpref{wxConfigBase::Set}{wxconfigbaseset}).
|
|
|
|
\membersection{wxHtmlHelpController::WriteCustomization}\label{wxhtmlhelpcontrollerwritecustomization}
|
|
|
|
\func{void}{WriteCustomization}{\param{wxConfigBase* }{cfg}, \param{wxString }{path = wxEmptyString}}
|
|
|
|
Stores controllers setting (position of window etc.)
|
|
|