X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9704b2509ac4fd7b9fccd5299e0b377accb2b59e..50c538600e7586c256fe0145ac8054f045be6fbb:/docs/latex/wx/hthelpct.tex diff --git a/docs/latex/wx/hthelpct.tex b/docs/latex/wx/hthelpct.tex index be95b150ac..87eadfb919 100644 --- a/docs/latex/wx/hthelpct.tex +++ b/docs/latex/wx/hthelpct.tex @@ -5,14 +5,15 @@ \section{\class{wxHtmlHelpController}}\label{wxhtmlhelpcontroller} -{\bf WARNING! This help controller has an API incompatible with wxWindows -wxHelpController!} +{\bf WARNING!} 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. 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} +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 "wxWindows Reference"). The help controller can handle as +"C++ Reference" or "wxWidgets Reference"). The help controller can handle as many books as you want. wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as its @@ -22,36 +23,32 @@ 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. -In order to use the controller in your application under Windows you must -have the following line in your .rc file: - -\begin{verbatim} -#include "wx/html/msw/wxhtml.rc" -\end{verbatim} - \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 +\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} +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} + \wxheading{Derived from} -\helpref{wxEvtHandler}{wxevthandler} +wxHelpControllerBase \wxheading{Include files} - \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxHtmlHelpController::wxHtmlHelpController}\label{wxhtmlhelpcontrollerwxhtmlhelpcontroller} -\func{}{wxHtmlHelpController}{\param{int }{style = wxHF\_DEFAULTSTYLE}} +\func{}{wxHtmlHelpController}{\param{int }{style = wxHF\_DEFAULT\_STYLE}} Constructor. @@ -59,31 +56,66 @@ Constructor. {\it style} is combination of these flags: -\begin{twocollist} +\begin{twocollist}\itemsep=0pt \twocolitem{\windowstyle{wxHF\_TOOLBAR}}{Help frame has toolbar.} +\twocolitem{\windowstyle{wxHF\_FLAT\_TOOLBAR}}{Help frame has toolbar with flat buttons (aka coolbar).} \twocolitem{\windowstyle{wxHF\_CONTENTS}}{Help frame has contents panel.} \twocolitem{\windowstyle{wxHF\_INDEX}}{Help frame has index panel.} \twocolitem{\windowstyle{wxHF\_SEARCH}}{Help frame has search panel.} \twocolitem{\windowstyle{wxHF\_BOOKMARKS}}{Help frame has bookmarks controls.} -\twocolitem{\windowstyle{wxHF\_OPENFILES}}{Allow user to open arbitrary HTML document.} +\twocolitem{\windowstyle{wxHF\_OPEN\_FILES}}{Allow user to open arbitrary HTML document.} \twocolitem{\windowstyle{wxHF\_PRINT}}{Toolbar contains "print" button.} +\twocolitem{\windowstyle{wxHF\_MERGE\_BOOKS}}{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\_DEFAULT\_STYLE}}{{\tt wxHF\_TOOLBAR | wxHF\_CONTENTS +| wxHF\_INDEX | wxHF\_SEARCH | wxHF\_BOOKMARKS | wxHF\_PRINT}} \end{twocollist} -Default value: everything but wxHF\_OPENFILES enabled. - \membersection{wxHtmlHelpController::AddBook}\label{wxhtmlhelpcontrolleraddbook} -\func{bool}{AddBook}{\param{const wxString\& }{book}, \param{bool }{show\_wait\_msg}} +\func{bool}{AddBook}{\param{const wxFileName\& }{book\_file}, \param{bool }{show\_wait\_msg}} + +\func{bool}{AddBook}{\param{const wxString\& }{book\_url}, \param{bool }{show\_wait\_msg}} 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 book} may be either .hhp file or ZIP archive that contains arbitrary number of .hhp files in +{\it book\_file} or {\it book\_url} 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("help.zip")} is possible and, in fact, -recommended way. +(the latter stands for "HTML book"). In other words, +{\tt AddBook(wxFileName("help.zip"))} +is possible and, in fact, recommended way. -If {\it show\_wait\_msg} is TRUE then a decorationless window with progress message is displayed. +\wxheading{Parameters} + +\docparam{show\_wait\_msg}{If true then a decoration-less window with progress message is displayed.} +\docparam{book\_file}{Help book filename. It is recommended to use this prototype +instead of the one taking URL, because it is less error-prone.} +\docparam{book\_url}{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::CreateHelpFrame}\label{wxhtmlhelpcontrollercreatehelpframe} + +\func{virtual wxHtmlHelpFrame*}{CreateHelpFrame}{\param{wxHtmlHelpData * }{data}} + +This protected virtual method may be overridden so that the controller +uses slightly different frame. See {\it samples/html/helpview} sample for +an example. \membersection{wxHtmlHelpController::Display}\label{wxhtmlhelpcontrollerdisplay} @@ -132,12 +164,13 @@ 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. +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 .htc file(s). +{\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} @@ -152,7 +185,7 @@ Reads the controller's setting (position of window, etc.) 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} +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 @@ -188,12 +221,3 @@ default wxConfig object if available (for details see Stores controllers setting (position of window etc.) -\membersection{wxHtmlHelpController::CreateHelpFrame}\label{wxhtmlhelpcontrollercreatehelpframe} - -\func{virtual wxHtmlHelpFrame*}{CreateHelpFrame}{\param{wxHtmlHelpData * }{data}} - -This protected virtual method may be overriden so that the controller -uses slightly different frame. See {\it samples/html/helpview} sample for -an example. - -