]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/helpinst.tex
GetPath() now has wxPATH_GET_COLUME by default
[wxWidgets.git] / docs / latex / wx / helpinst.tex
... / ...
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 if you
47use .zip or .htb formats for your books, you
48must add this line to your application initialization: {\tt wxFileSystem::AddHandler(new wxZipFSHandler);}
49or nothing will be shown in your help window.
50\end{itemize}
51
52\wxheading{Derived from}
53
54wxHelpControllerBase\\
55\helpref{wxObject}{wxobject}
56
57\wxheading{Include files}
58
59<wx/help.h> (wxWindows chooses the appropriate help controller class)\\
60<wx/helpbase.h> (wxHelpControllerBase class)\\
61<wx/helpwin.h> (Windows Help controller)\\
62<wx/msw/helpchm.h> (MS HTML Help controller)\\
63<wx/generic/helpext.h> (external HTML browser controller)\\
64<wx/html/helpctrl.h> (wxHTML based help controller: wxHtmlHelpController)
65
66\wxheading{See also}
67
68\helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, \helpref{wxHTML}{wxhtml}
69
70\latexignore{\rtfignore{\wxheading{Members}}}
71
72\membersection{wxHelpController::wxHelpController}
73
74\func{}{wxHelpController}{\void}
75
76Constructs a help instance object, but does not invoke the help viewer.
77
78\membersection{wxHelpController::\destruct{wxHelpController}}
79
80\func{}{\destruct{wxHelpController}}{\void}
81
82Destroys the help instance, closing down the viewer if it is running.
83
84\membersection{wxHelpController::Initialize}\label{wxhelpcontrollerinitialize}
85
86\func{virtual void}{Initialize}{\param{const wxString\& }{file}}
87
88\func{virtual void}{Initialize}{\param{const wxString\& }{file}, \param{int}{ server}}
89
90Initializes the help instance with a help filename, and optionally a server socket
91number if using wxHelp (now obsolete). Does not invoke the help viewer.
92This must be called directly after the help instance object is created and before
93any attempts to communicate with the viewer.
94
95You may omit the file extension and a suitable one will be chosen. For
96wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for
97a suitable file. For WinHelp, the hlp extension is appended.
98
99\membersection{wxHelpController::DisplayBlock}\label{wxhelpcontrollerdisplayblock}
100
101\func{virtual bool}{DisplayBlock}{\param{long}{ blockNo}}
102
103If the help viewer is not running, runs it and displays the file at the given block number.
104
105{\it WinHelp:} Refers to the context number.
106
107{\it MS HTML Help:} Refers to the context number.
108
109{\it External HTML help:} the same as for \helpref{wxHelpController::DisplaySection}{wxhelpcontrollerdisplaysection}.
110
111{\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
112
113This function is for backward compatibility only, and applications should use \helpref{wxHelpController}{wxhelpcontrollerdisplaysection} instead.
114
115\membersection{wxHelpController::DisplayContents}\label{wxhelpcontrollerdisplaycontents}
116
117\func{virtual bool}{DisplayContents}{\void}
118
119If the help viewer is not running, runs it and displays the
120contents.
121
122\membersection{wxHelpController::DisplayContextPopup}\label{wxhelpcontrollerdisplaycontextpopup}
123
124\func{virtual bool}{DisplayContextPopup}{\param{int }{contextId}}
125
126Displays the section as a popup window using a context id.
127
128Returns false if unsuccessful or not implemented.
129
130\membersection{wxHelpController::DisplaySection}\label{wxhelpcontrollerdisplaysection}
131
132\func{virtual bool}{DisplaySection}{\param{const wxString\&}{ section}}
133
134If the help viewer is not running, runs it and displays the given section.
135
136The interpretation of {\it section} differs between help viewers. For most viewers,
137this call is equivalent to KeywordSearch. For MS HTML Help, wxHTML help and external HTML help,
138if {\it section} has a .htm
139or .html extension, that HTML file will be displayed; otherwise
140a keyword search is done.
141
142\func{virtual bool}{DisplaySection}{\param{int}{ sectionNo}}
143
144If the help viewer is not running, runs it and displays the given section.
145
146{\it WinHelp, MS HTML Help} {\it sectionNo} is a context id.
147
148{\it External HTML help:} wxExtHelpController implements {\it sectionNo} as an id in a map file, which is of the form:
149
150\begin{verbatim}
1510 wx.html ; Index
1521 wx34.html#classref ; Class reference
1532 wx204.html ; Function reference
154\end{verbatim}
155
156{\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}.
157
158See also the help sample for notes on how to specify section numbers for various help file formats.
159
160\membersection{wxHelpController::DisplayTextPopup}\label{wxhelpcontrollerdisplaytextpopup}
161
162\func{virtual bool}{DisplayTextPopup}{\param{const wxString\&}{ text}, \param{const wxPoint\& }{pos}}
163
164Displays the text in a popup window, if possible.
165
166Returns false if unsuccessful or not implemented.
167
168\membersection{wxHelpController::GetFrameParameters}\label{wxhelpcontrollergetframeparameters}
169
170\func{virtual wxFrame *}{GetFrameParameters}{\param{const wxSize * }{size = NULL}, \param{const wxPoint * }{pos = NULL},
171 \param{bool *}{newFrameEachTime = NULL}}
172
173wxHtmlHelpController returns the frame, size and position.
174
175For all other help controllers, this function does nothing
176and just returns NULL.
177
178\wxheading{Parameters}
179
180\docparam{viewer}{This defaults to "netscape" for wxExtHelpController.}
181
182\docparam{flags}{This defaults to wxHELP\_NETSCAPE for wxExtHelpController, indicating
183that the viewer is a variant of Netscape Navigator.}
184
185\membersection{wxHelpController::KeywordSearch}\label{wxhelpcontrollerkeywordsearch}
186
187\func{virtual bool}{KeywordSearch}{\param{const wxString\& }{keyWord}}
188
189If the help viewer is not running, runs it, and searches for sections matching the given keyword. If one
190match is found, the file is displayed at this section.
191
192{\it WinHelp, MS HTML Help:} If more than one match is found,
193the first topic is displayed.
194
195{\it External HTML help, simple wxHTML help:} If more than one match is found,
196a choice of topics is displayed.
197
198{\it wxHtmlHelpController:} see \helpref{wxHtmlHelpController::KeywordSearch}{wxhtmlhelpcontrollerkeywordsearch}.
199
200\membersection{wxHelpController::LoadFile}\label{wxhelpcontrollerloadfile}
201
202\func{virtual bool}{LoadFile}{\param{const wxString\& }{file = ""}}
203
204If the help viewer is not running, runs it and loads the given file.
205If the filename is not supplied or is
206empty, the file specified in {\bf Initialize} is used. If the viewer is
207already displaying the specified file, it will not be reloaded. This
208member function may be used before each display call in case the user
209has opened another file.
210
211wxHtmlHelpController ignores this call.
212
213\membersection{wxHelpController::OnQuit}\label{wxhelpcontrolleronquit}
214
215\func{virtual bool}{OnQuit}{\void}
216
217Overridable member called when this application's viewer is quit by the user.
218
219This does not work for all help controllers.
220
221\membersection{wxHelpController::SetFrameParameters}\label{wxhelpcontrollersetframeparameters}
222
223\func{virtual void}{SetFrameParameters}{\param{const wxString \& }{title},
224 \param{const wxSize \& }{size}, \param{const wxPoint \& }{pos = wxDefaultPosition},
225 \param{bool }{newFrameEachTime = false}}
226
227For wxHtmlHelpController, the title is set (again with \%s indicating the
228page title) and also the size and position of the frame if the frame is already
229open. {\it newFrameEachTime} is ignored.
230
231For all other help controllers this function has no effect.
232
233\membersection{wxHelpController::SetViewer}\label{wxhelpcontrollersetviewer}
234
235\func{virtual void}{SetViewer}{\param{const wxString\& }{viewer}, \param{long}{ flags}}
236
237Sets detailed viewer information. So far this is only relevant to wxExtHelpController.
238
239Some examples of usage:
240
241\begin{verbatim}
242 m_help.SetViewer("kdehelp");
243 m_help.SetViewer("gnome-help-browser");
244 m_help.SetViewer("netscape", wxHELP_NETSCAPE);
245\end{verbatim}
246
247\membersection{wxHelpController::Quit}\label{wxhelpcontrollerquit}
248
249\func{virtual bool}{Quit}{\void}
250
251If the viewer is running, quits it by disconnecting.
252
253For Windows Help, the viewer will only close if no other application is using it.
254