X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/22d6efa851642c6a69174278fc50f712f41e2271..d60156ac9d764d9ee6cf866a87084732d341abb9:/docs/latex/wx/hthelpct.tex diff --git a/docs/latex/wx/hthelpct.tex b/docs/latex/wx/hthelpct.tex index 6acbc42042..a4ea217f34 100644 --- a/docs/latex/wx/hthelpct.tex +++ b/docs/latex/wx/hthelpct.tex @@ -5,65 +5,133 @@ \section{\class{wxHtmlHelpController}}\label{wxhtmlhelpcontroller} -{\bf WARNING! This help controller has an API incompatible with wxWindows -wxHelpController!} - -This help controller provides easy way how to display HTML help in your -application (see {\it test} sample). Whole help system is based on {\bf books} -(see \helpref{AddBook}{wxhtmlhelpcontrolleraddbook}). A book is logical -part of documentation (for example "User's Guide" or "Programmer's Guide" or -"C++ Reference" or "wxWindows Reference"). Help controller can handle as +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 generate MHHW projects (see wxHTML homepage for details). +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. -In order to use the controller in your application under Windows you must -have following line in your .rc file: +\wxheading{See also} -\begin{verbatim} -#include "wx/html/msw/wxhtml.rc" -\end{verbatim} +\helpref{Information about wxBestHelpController}{wxhelpcontroller}, +\helpref{wxHtmlHelpFrame}{wxhtmlhelpframe}, +\helpref{wxHtmlHelpDialog}{wxhtmlhelpdialog}, +\helpref{wxHtmlHelpWindow}{wxhtmlhelpwindow}, +\helpref{wxHtmlModalHelp}{wxhtmlmodalhelp} \wxheading{Derived from} -wxEvtHandler +wxHelpControllerBase + +\wxheading{Include files} + + \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxHtmlHelpController::wxHtmlHelpController}\label{wxhtmlhelpcontrollerwxhtmlhelpcontroller} -\func{}{wxHtmlHelpController}{\void} +\func{}{wxHtmlHelpController}{\param{int }{style = wxHF\_DEFAULT\_STYLE}, \param{wxWindow* }{parentWindow = NULL}} Constructor. -\membersection{wxHtmlHelpController::SetTitleFormat}\label{wxhtmlhelpcontrollersettitleformat} +\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. -\func{void}{SetTitleFormat}{\param{const wxString\& }{format}} +\membersection{wxHtmlHelpController::AddBook}\label{wxhtmlhelpcontrolleraddbook} -Sets format of title of the frame. Must contain exactly one "\%s" -(for title of displayed HTML page). +\func{bool}{AddBook}{\param{const wxFileName\& }{bookFile}, \param{bool }{showWaitMsg}} -\membersection{wxHtmlHelpController::SetTempDir}\label{wxhtmlhelpcontrollersettempdir} +\func{bool}{AddBook}{\param{const wxString\& }{bookUrl}, \param{bool }{showWaitMsg}} -\func{void}{SetTempDir}{\param{const wxString\& }{path}} +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. -Sets 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 NOT -deleted when program exits! +{\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. -\membersection{wxHtmlHelpController::AddBook}\label{wxhtmlhelpcontrolleraddbook} +\wxheading{Parameters} -\func{bool}{AddBook}{\param{const wxString\& }{book}, \param{bool }{show_wait_msg}} +\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)} -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. +\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}} -If {\it show_wait_msg} is TRUE then a decorationless window with progress message is displayed. +This protected virtual method may be overridden so that the controller +uses a different frame. \membersection{wxHtmlHelpController::Display}\label{wxhtmlhelpcontrollerdisplay} @@ -74,16 +142,16 @@ the help in application. You can specify the page in many ways: -\begin{itemize} +\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) +\item even as any word (will be searched) \end{itemize} Looking for the page runs in these steps: -\begin{enumerate} +\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 ...") @@ -95,6 +163,9 @@ Looking for the page runs in these steps: 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} @@ -109,13 +180,40 @@ Displays help window and focuses index panel. \membersection{wxHtmlHelpController::KeywordSearch}\label{wxhtmlhelpcontrollerkeywordsearch} -\func{bool}{KeywordSearch}{\param{const wxString\& }{keyword}} +\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}} -Displays help window, focuses search panel and starts searching. -Returns TRUE if the keyword was found. +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. -IMPORTANT! KeywordSearch searches only pages listed in .htc file(s)! -(you should have all pages in contents file...) +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} @@ -126,13 +224,12 @@ 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. - -\membersection{wxHtmlHelpController::ReadCustomization}\label{wxhtmlhelpcontrollerreadcustomization} - -\func{void}{ReadCustomization}{\param{wxConfigBase* }{cfg}, \param{wxString }{path = wxEmptyString}} +The only thing you must do is create wxConfig object and call UseConfig. -Reads controllers setting (position of window etc.) +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}