Added missing rejigged IPC Latex files
[wxWidgets.git] / docs / latex / wx / helpinst.tex
0 / 253 (  0%)
CommitLineData
1\section{\class{wxHelpController}}\label{wxhelpcontroller}
2
3This is a family of classes by which
4applications may invoke a help viewer to provide on-line help.
5
6A help controller allows an application to display help, at the contents
7or at a particular topic, and shut the help program down on termination.
8This avoids proliferation of many instances of the help viewer whenever the
9user requests a different topic via the application's menus or buttons.
10
11Typically, an application will create a help controller instance
12when it starts, and immediately call {\bf Initialize}\rtfsp
13to associate a filename with it. The help viewer will only get run, however,
14just before the first call to display something.
15
16Most help controller classes actually derive from wxHelpControllerBase and have
17names of the form wxXXXHelpController or wxHelpControllerXXX. An
18appropriate class is aliased to the name wxHelpController for each platform, as follows:
19
20\begin{itemize}\itemsep=0pt
21\item On Windows, wxWinHelpController is used.
22\item On all other platforms, wxHtmlHelpController is used if wxHTML is
23compiled into wxWindows; otherwise wxExtHelpController is used (for invoking an external
24browser).
25\end{itemize}
26
27The remaining help controller classes need to be named
28explicitly by an application that wishes to make use of them.
29
30There are currently the following help controller classes defined:
31
32\begin{itemize}\itemsep=0pt
33\item wxWinHelpController, for controlling Windows Help.
34\item wxCHMHelpController, for controlling MS HTML Help. To use this, you need to set wxUSE\_MS\_HTML\_HELP
35to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you don't need
36VC++ specific htmlhelp.lib because wxWindows loads necessary DLL at runtime and so it
37works with all compilers).
38\item wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime is
39not available, \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}. You need to provide
40{\bf both} CHM and HTB versions of the help file. For 32bit Windows only.
41\item wxExtHelpController, for controlling external browsers under Unix.
42The default browser is Netscape Navigator. The 'help' sample shows its use.
43\item \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, a sophisticated help controller using \helpref{wxHTML}{wxhtml}, in
44a similar style to the Microsoft HTML Help viewer and using some of the same files.
45Although it has an API compatible with other help controllers, it has more advanced features, so it is
46recommended that you use the specific API for this class instead. Note that you
47must add this line to your application initialization: \verb$wxFileSystem::AddHandler(new wxZipFSHandler);$
48or nothing will be shown in your help window.
49\end{itemize}
50
51\wxheading{Derived from}
52
53wxHelpControllerBase\\
54\helpref{wxObject}{wxobject}
55
56\wxheading{Include files}
57
58<wx/help.h> (wxWindows chooses the appropriate help controller class)\\
59<wx/helpbase.h> (wxHelpControllerBase class)\\
60<wx/helpwin.h> (Windows Help controller)\\
61<wx/msw/helpchm.h> (MS HTML Help controller)\\
62<wx/generic/helpext.h> (external HTML browser controller)\\
63<wx/html/helpctrl.h> (wxHTML based help controller: wxHtmlHelpController)
64
65\wxheading{See also}
66
67\helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, \helpref{wxHTML}{wxhtml}
68
69\latexignore{\rtfignore{\wxheading{Members}}}
70
71\membersection{wxHelpController::wxHelpController}
72
73\func{}{wxHelpController}{\void}
74
75Constructs a help instance object, but does not invoke the help viewer.
76
77\membersection{wxHelpController::\destruct{wxHelpController}}
78
79\func{}{\destruct{wxHelpController}}{\void}
80
81Destroys the help instance, closing down the viewer if it is running.
82
83\membersection{wxHelpController::Initialize}\label{wxhelpcontrollerinitialize}
84
85\func{virtual void}{Initialize}{\param{const wxString\& }{file}}
86
87\func{virtual void}{Initialize}{\param{const wxString\& }{file}, \param{int}{ server}}
88
89Initializes the help instance with a help filename, and optionally a server socket
90number if using wxHelp (now obsolete). Does not invoke the help viewer.
91This must be called directly after the help instance object is created and before
92any attempts to communicate with the viewer.
93
94You may omit the file extension and a suitable one will be chosen. For
95wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for
96a suitable file. For WinHelp, the hlp extension is appended.
97
98\membersection{wxHelpController::DisplayBlock}\label{wxhelpcontrollerdisplayblock}
99
100\func{virtual bool}{DisplayBlock}{\param{long}{ blockNo}}
101
102If the help viewer is not running, runs it and displays the file at the given block number.
103
104{\it WinHelp:} Refers to the context number.
105
106{\it MS HTML Help:} Refers to the context number.
107
108{\it External HTML help:} the same as for \helpref{wxHelpController::DisplaySection}{wxhelpcontrollerdisplaysection}.
109
110{\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
111
112This function is for backward compatibility only, and applications should use \helpref{wxHelpController}{wxhelpcontrollerdisplaysection} instead.
113
114\membersection{wxHelpController::DisplayContents}\label{wxhelpcontrollerdisplaycontents}
115
116\func{virtual bool}{DisplayContents}{\void}
117
118If the help viewer is not running, runs it and displays the
119contents.
120
121\membersection{wxHelpController::DisplayContextPopup}\label{wxhelpcontrollerdisplaycontextpopup}
122
123\func{virtual bool}{DisplayContextPopup}{\param{int }{contextId}}
124
125Displays the section as a popup window using a context id.
126
127Returns FALSE if unsuccessful or not implemented.
128
129\membersection{wxHelpController::DisplaySection}\label{wxhelpcontrollerdisplaysection}
130
131\func{virtual bool}{DisplaySection}{\param{const wxString\&}{ section}}
132
133If the help viewer is not running, runs it and displays the given section.
134
135The interpretation of {\it section} differs between help viewers. For most viewers,
136this call is equivalent to KeywordSearch. For MS HTML Help, wxHTML help and external HTML help,
137if {\it section} has a .htm
138or .html extension, that HTML file will be displayed; otherwise
139a keyword search is done.
140
141\func{virtual bool}{DisplaySection}{\param{int}{ sectionNo}}
142
143If the help viewer is not running, runs it and displays the given section.
144
145{\it WinHelp, MS HTML Help} {\it sectionNo} is a context id.
146
147{\it External HTML help:} wxExtHelpController implements {\it sectionNo} as an id in a map file, which is of the form:
148
149\begin{verbatim}
1500 wx.html ; Index
1511 wx34.html#classref ; Class reference
1522 wx204.html ; Function reference
153\end{verbatim}
154
155{\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
156
157See also the help sample for notes on how to specify section numbers for various help file formats.
158
159\membersection{wxHelpController::DisplayTextPopup}\label{wxhelpcontrollerdisplaytextpopup}
160
161\func{virtual bool}{DisplayTextPopup}{\param{const wxString\&}{ text}, \param{const wxPoint\& }{pos}}
162
163Displays the text in a popup window, if possible.
164
165Returns FALSE if unsuccessful or not implemented.
166
167\membersection{wxHelpController::GetFrameParameters}\label{wxhelpcontrollergetframeparameters}
168
169\func{virtual wxFrame *}{GetFrameParameters}{\param{const wxSize * }{size = NULL}, \param{const wxPoint * }{pos = NULL},
170 \param{bool *}{newFrameEachTime = NULL}}
171
172wxHtmlHelpController returns the frame, size and position.
173
174For all other help controllers, this function does nothing
175and just returns NULL.
176
177\wxheading{Parameters}
178
179\docparam{viewer}{This defaults to "netscape" for wxExtHelpController.}
180
181\docparam{flags}{This defaults to wxHELP\_NETSCAPE for wxExtHelpController, indicating
182that the viewer is a variant of Netscape Navigator.}
183
184\membersection{wxHelpController::KeywordSearch}\label{wxhelpcontrollerkeywordsearch}
185
186\func{virtual bool}{KeywordSearch}{\param{const wxString\& }{keyWord}}
187
188If the help viewer is not running, runs it, and searches for sections matching the given keyword. If one
189match is found, the file is displayed at this section.
190
191{\it WinHelp, MS HTML Help:} If more than one match is found,
192the first topic is displayed.
193
194{\it External HTML help, simple wxHTML help:} If more than one match is found,
195a choice of topics is displayed.
196
197{\it wxHtmlHelpController:} see \helpref{wxHtmlHelpController::KeywordSearch}{wxhtmlhelpcontrollerkeywordsearch}.
198
199\membersection{wxHelpController::LoadFile}\label{wxhelpcontrollerloadfile}
200
201\func{virtual bool}{LoadFile}{\param{const wxString\& }{file = ""}}
202
203If the help viewer is not running, runs it and loads the given file.
204If the filename is not supplied or is
205empty, the file specified in {\bf Initialize} is used. If the viewer is
206already displaying the specified file, it will not be reloaded. This
207member function may be used before each display call in case the user
208has opened another file.
209
210wxHtmlHelpController ignores this call.
211
212\membersection{wxHelpController::OnQuit}\label{wxhelpcontrolleronquit}
213
214\func{virtual bool}{OnQuit}{\void}
215
216Overridable member called when this application's viewer is quit by the user.
217
218This does not work for all help controllers.
219
220\membersection{wxHelpController::SetFrameParameters}\label{wxhelpcontrollersetframeparameters}
221
222\func{virtual void}{SetFrameParameters}{\param{const wxString \& }{title},
223 \param{const wxSize \& }{size}, \param{const wxPoint \& }{pos = wxDefaultPosition},
224 \param{bool }{newFrameEachTime = FALSE}}
225
226For wxHtmlHelpController, the title is set (again with \%s indicating the
227page title) and also the size and position of the frame if the frame is already
228open. {\it newFrameEachTime} is ignored.
229
230For all other help controllers this function has no effect.
231
232\membersection{wxHelpController::SetViewer}\label{wxhelpcontrollersetviewer}
233
234\func{virtual void}{SetViewer}{\param{const wxString\& }{viewer}, \param{long}{ flags}}
235
236Sets detailed viewer information. So far this is only relevant to wxExtHelpController.
237
238Some examples of usage:
239
240\begin{verbatim}
241 m_help.SetViewer("kdehelp");
242 m_help.SetViewer("gnome-help-browser");
243 m_help.SetViewer("netscape", wxHELP_NETSCAPE);
244\end{verbatim}
245
246\membersection{wxHelpController::Quit}\label{wxhelpcontrollerquit}
247
248\func{virtual bool}{Quit}{\void}
249
250If the viewer is running, quits it by disconnecting.
251
252For Windows Help, the viewer will only close if no other application is using it.
253