]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/hthelpct.tex
added SetStatusText method (avoiding dc.Clear)
[wxWidgets.git] / docs / latex / wx / hthelpct.tex
CommitLineData
704a4b75
VS
1%
2% automatically generated by HelpGen from
3% htmlhelp.h at 02/May/99 19:58:53
4%
5
704a4b75
VS
6\section{\class{wxHtmlHelpController}}\label{wxhtmlhelpcontroller}
7
fa482912 8{\bf WARNING!} Although this class has an API compatible with other wxWindows
0d3a69ec 9help controllers as documented by \helpref{wxHelpController}{wxhelpcontroller}, it
fa482912 10is recommended that you use the enhanced capabilities of wxHtmlHelpController's API.
704a4b75 11
448af9a4 12This help controller provides an easy way of displaying HTML help in your
7b28757f 13application (see {\it test} sample). The help system is based on {\bf books}
448af9a4
JS
14(see \helpref{AddBook}{wxhtmlhelpcontrolleraddbook}). A book is a logical
15section of documentation (for example "User's Guide" or "Programmer's Guide" or
16"C++ Reference" or "wxWindows Reference"). The help controller can handle as
704a4b75
VS
17many books as you want.
18
19wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as its
20native format. The file format is described \helpref{here}{helpformat}.
21Have a look at docs/html/ directory where sample project files are stored.
22
36edded9
JS
23You can use Tex2RTF to produce these files when generating HTML, if you set {\bf htmlWorkshopFiles} to {\bf true} in
24your tex2rtf.ini file.
704a4b75
VS
25
26In order to use the controller in your application under Windows you must
448af9a4 27have the following line in your .rc file:
704a4b75
VS
28
29\begin{verbatim}
30#include "wx/html/msw/wxhtml.rc"
31\end{verbatim}
32
b854b7b8
VS
33\wxheading{Note}
34
35It is strongly recommended to use preprocessed {\bf .hhp.cached} version of
36projects. It can be either created on-the-fly (see
7b28757f 37\helpref{SetTempDir}{wxhtmlhelpcontrollersettempdir}) or you can use
b854b7b8 38{\bf hhp2cached} utility from {\it utils/hhp2cached} to create it and
7b28757f 39distribute the cached version together with helpfiles. See {\it samples/html/help}
b854b7b8
VS
40sample for demonstration of its use.
41
2049d9b5
VS
42\wxheading{See also}
43
44\helpref{Information about wxBestHelpController}{wxhelpcontroller}
45
704a4b75
VS
46\wxheading{Derived from}
47
0d3a69ec 48wxHelpControllerBase
704a4b75 49
9704b250
VS
50\wxheading{Include files}
51
52<wx/html/helpctrl.h>
53
704a4b75
VS
54\latexignore{\rtfignore{\wxheading{Members}}}
55
704a4b75
VS
56\membersection{wxHtmlHelpController::wxHtmlHelpController}\label{wxhtmlhelpcontrollerwxhtmlhelpcontroller}
57
576507e2 58\func{}{wxHtmlHelpController}{\param{int }{style = wxHF\_DEFAULT\_STYLE}}
704a4b75 59
704a4b75
VS
60Constructor.
61
09397bc6
VS
62\wxheading{Parameters}
63
64{\it style} is combination of these flags:
65
7b28757f 66\begin{twocollist}\itemsep=0pt
09397bc6 67\twocolitem{\windowstyle{wxHF\_TOOLBAR}}{Help frame has toolbar.}
576507e2 68\twocolitem{\windowstyle{wxHF\_FLAT\_TOOLBAR}}{Help frame has toolbar with flat buttons (aka coolbar).}
09397bc6
VS
69\twocolitem{\windowstyle{wxHF\_CONTENTS}}{Help frame has contents panel.}
70\twocolitem{\windowstyle{wxHF\_INDEX}}{Help frame has index panel.}
71\twocolitem{\windowstyle{wxHF\_SEARCH}}{Help frame has search panel.}
c914a1a2 72\twocolitem{\windowstyle{wxHF\_BOOKMARKS}}{Help frame has bookmarks controls.}
576507e2 73\twocolitem{\windowstyle{wxHF\_OPEN\_FILES}}{Allow user to open arbitrary HTML document.}
ecacdf8f 74\twocolitem{\windowstyle{wxHF\_PRINT}}{Toolbar contains "print" button.}
576507e2
VS
75\twocolitem{\windowstyle{wxHF\_MERGE\_BOOKS}}{Contents pane does not show
76book nodes. All books are merged together and appear as single book to the
77user.}
78\twocolitem{\windowstyle{wxHF\_ICONS\_BOOK}}{All nodes in contents pane
79have a book icon. This is how Microsoft's HTML help viewer behaves.}
80\twocolitem{\windowstyle{wxHF\_ICONS\_FOLDER}}{Book nodes in contents pane have
81a book icon, book's sections have a folder icon. This is the default.}
e7240349 82\twocolitem{\windowstyle{wxHF\_ICONS\_BOOK\_CHAPTER}}{Both book nodes and
576507e2
VS
83nodes of top-level sections of a book (i.e. chapters) have a book icon,
84all other sections (sections, subsections, ...) have a folder icon.}
85\twocolitem{\windowstyle{wxHF\_DEFAULT\_STYLE}}{{\tt wxHF\_TOOLBAR | wxHF\_CONTENTS
86| wxHF\_INDEX | wxHF\_SEARCH | wxHF\_BOOKMARKS | wxHF\_PRINT}}
09397bc6
VS
87\end{twocollist}
88
704a4b75
VS
89\membersection{wxHtmlHelpController::AddBook}\label{wxhtmlhelpcontrolleraddbook}
90
605d715d 91\func{bool}{AddBook}{\param{const wxString\& }{book}, \param{bool }{show\_wait\_msg}}
704a4b75
VS
92
93Adds book (\helpref{.hhp file}{helpformat} - HTML Help Workshop project file) into the list of loaded books.
94This must be called at least once before displaying any help.
95
3dabc03f
VS
96{\it book} may be either .hhp file or ZIP archive that contains arbitrary number of .hhp files in
97top-level directory. This ZIP archive must have .zip or .htb extension
98(the latter stands for "HTML book"). In other words, {\tt AddBook("help.zip")} is possible and, in fact,
99recommended way.
100
448af9a4 101If {\it show\_wait\_msg} is TRUE then a decorationless window with progress message is displayed.
704a4b75 102
7b28757f
JS
103\membersection{wxHtmlHelpController::CreateHelpFrame}\label{wxhtmlhelpcontrollercreatehelpframe}
104
105\func{virtual wxHtmlHelpFrame*}{CreateHelpFrame}{\param{wxHtmlHelpData * }{data}}
106
f6bcfd97 107This protected virtual method may be overridden so that the controller
7b28757f
JS
108uses slightly different frame. See {\it samples/html/helpview} sample for
109an example.
704a4b75
VS
110\membersection{wxHtmlHelpController::Display}\label{wxhtmlhelpcontrollerdisplay}
111
112\func{void}{Display}{\param{const wxString\& }{x}}
113
114Displays page {\it x}. This is THE important function - it is used to display
115the help in application.
116
117You can specify the page in many ways:
118
448af9a4 119\begin{itemize}\itemsep=0pt
704a4b75
VS
120\item as direct filename of HTML document
121\item as chapter name (from contents) or as a book name
122\item as some word from index
b32c6ff0 123\item even as any word (will be searched)
704a4b75
VS
124\end{itemize}
125
126Looking for the page runs in these steps:
127
448af9a4 128\begin{enumerate}\itemsep=0pt
704a4b75
VS
129\item try to locate file named x (if x is for example "doc/howto.htm")
130\item try to open starting page of book named x
131\item try to find x in contents (if x is for example "How To ...")
132\item try to find x in index (if x is for example "How To ...")
133\item switch to Search panel and start searching
134\end{enumerate}
135
136\func{void}{Display}{\param{const int }{id}}
137
138This alternative form is used to search help contents by numeric IDs.
139
b32c6ff0
RD
140\pythonnote{The second form of this method is named DisplayId in
141wxPython.}
142
704a4b75
VS
143\membersection{wxHtmlHelpController::DisplayContents}\label{wxhtmlhelpcontrollerdisplaycontents}
144
145\func{void}{DisplayContents}{\void}
146
147Displays help window and focuses contents panel.
148
149\membersection{wxHtmlHelpController::DisplayIndex}\label{wxhtmlhelpcontrollerdisplayindex}
150
151\func{void}{DisplayIndex}{\void}
152
153Displays help window and focuses index panel.
154
704a4b75
VS
155\membersection{wxHtmlHelpController::KeywordSearch}\label{wxhtmlhelpcontrollerkeywordsearch}
156
157\func{bool}{KeywordSearch}{\param{const wxString\& }{keyword}}
158
159Displays help window, focuses search panel and starts searching.
160Returns TRUE if the keyword was found.
161
f6bcfd97 162{\bf Important:} KeywordSearch searches only pages listed in .hhc file(s).
448af9a4 163You should list all pages in the contents file.
704a4b75 164
559fe022
VS
165\membersection{wxHtmlHelpController::ReadCustomization}\label{wxhtmlhelpcontrollerreadcustomization}
166
167\func{void}{ReadCustomization}{\param{wxConfigBase* }{cfg}, \param{wxString }{path = wxEmptyString}}
168
448af9a4 169Reads the controller's setting (position of window, etc.)
559fe022
VS
170
171\membersection{wxHtmlHelpController::SetTempDir}\label{wxhtmlhelpcontrollersettempdir}
172
173\func{void}{SetTempDir}{\param{const wxString\& }{path}}
174
448af9a4
JS
175Sets the path for storing temporary files - cached binary versions of index and contents files. These binary
176forms are much faster to read. Default value is empty string (empty string means
7b28757f 177that no cached data are stored). Note that these files are {\it not}
448af9a4 178deleted when program exits.
559fe022 179
b854b7b8
VS
180Once created these cached files will be used in all subsequent executions
181of your application. If cached files become older than corresponding .hhp
182file (e.g. if you regenerate documentation) it will be refreshed.
183
559fe022
VS
184\membersection{wxHtmlHelpController::SetTitleFormat}\label{wxhtmlhelpcontrollersettitleformat}
185
186\func{void}{SetTitleFormat}{\param{const wxString\& }{format}}
187
188Sets format of title of the frame. Must contain exactly one "\%s"
189(for title of displayed HTML page).
190
704a4b75
VS
191\membersection{wxHtmlHelpController::UseConfig}\label{wxhtmlhelpcontrolleruseconfig}
192
193\func{void}{UseConfig}{\param{wxConfigBase* }{config}, \param{const wxString\& }{rootpath = wxEmptyString}}
194
195Associates {\it config} object with the controller.
196
197If there is associated config object, wxHtmlHelpController automatically
198reads and writes settings (including wxHtmlWindow's settings) when needed.
199
b32c6ff0 200The only thing you must do is create wxConfig object and call UseConfig.
704a4b75 201
74accc50
VS
202If you do not use {\it UseConfig}, wxHtmlHelpController will use
203default wxConfig object if available (for details see
204\helpref{wxConfigBase::Get}{wxconfigbaseget} and
205\helpref{wxConfigBase::Set}{wxconfigbaseset}).
206
704a4b75
VS
207\membersection{wxHtmlHelpController::WriteCustomization}\label{wxhtmlhelpcontrollerwritecustomization}
208
209\func{void}{WriteCustomization}{\param{wxConfigBase* }{cfg}, \param{wxString }{path = wxEmptyString}}
210
211Stores controllers setting (position of window etc.)
212