]>
Commit | Line | Data |
---|---|---|
1 | \section{\class{wxHelpController}}\label{wxhelpcontroller} | |
2 | ||
3 | This is a family of classes by which | |
4 | applications may invoke a help viewer to provide on-line help. | |
5 | ||
6 | A help controller allows an application to display help, at the contents | |
7 | or at a particular topic, and shut the help program down on termination. | |
8 | This avoids proliferation of many instances of the help viewer whenever the | |
9 | user requests a different topic via the application's menus or buttons. | |
10 | ||
11 | Typically, an application will create a help controller instance | |
12 | when it starts, and immediately call {\bf Initialize}\rtfsp | |
13 | to associate a filename with it. The help viewer will only get run, however, | |
14 | just before the first call to display something. | |
15 | ||
16 | Most help controller classes actually derive from wxHelpControllerBase and have | |
17 | names of the form wxXXXHelpController or wxHelpControllerXXX. An | |
18 | appropriate 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 | |
23 | compiled into wxWindows; otherwise wxExtHelpController is used (for invoking an external | |
24 | browser). | |
25 | \end{itemize} | |
26 | ||
27 | The remaining help controller classes need to be named | |
28 | explicitly by an application that wishes to make use of them. | |
29 | ||
30 | There 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 | |
35 | to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you don't need | |
36 | VC++ specific htmlhelp.lib because wxWindows loads necessary DLL at runtime and so it | |
37 | works with all compilers). | |
38 | \item wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime is | |
39 | not 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. | |
42 | The 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 | |
44 | a similar style to the Microsoft HTML Help viewer and using some of the same files. | |
45 | Although it has an API compatible with other help controllers, it has more advanced features, so it is | |
46 | recommended that you use the specific API for this class instead. Note that if you | |
47 | use .zip or .htb formats for your books, you | |
48 | must add this line to your application initialization: {\tt wxFileSystem::AddHandler(new wxZipFSHandler);} | |
49 | or nothing will be shown in your help window. | |
50 | \end{itemize} | |
51 | ||
52 | \wxheading{Derived from} | |
53 | ||
54 | wxHelpControllerBase\\ | |
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 | ||
76 | Constructs a help instance object, but does not invoke the help viewer. | |
77 | ||
78 | \membersection{wxHelpController::\destruct{wxHelpController}} | |
79 | ||
80 | \func{}{\destruct{wxHelpController}}{\void} | |
81 | ||
82 | Destroys 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 | ||
90 | Initializes the help instance with a help filename, and optionally a server socket | |
91 | number if using wxHelp (now obsolete). Does not invoke the help viewer. | |
92 | This must be called directly after the help instance object is created and before | |
93 | any attempts to communicate with the viewer. | |
94 | ||
95 | You may omit the file extension and a suitable one will be chosen. For | |
96 | wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for | |
97 | a 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 | ||
103 | If 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 | ||
113 | This 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 | ||
119 | If the help viewer is not running, runs it and displays the | |
120 | contents. | |
121 | ||
122 | \membersection{wxHelpController::DisplayContextPopup}\label{wxhelpcontrollerdisplaycontextpopup} | |
123 | ||
124 | \func{virtual bool}{DisplayContextPopup}{\param{int }{contextId}} | |
125 | ||
126 | Displays the section as a popup window using a context id. | |
127 | ||
128 | Returns false if unsuccessful or not implemented. | |
129 | ||
130 | \membersection{wxHelpController::DisplaySection}\label{wxhelpcontrollerdisplaysection} | |
131 | ||
132 | \func{virtual bool}{DisplaySection}{\param{const wxString\&}{ section}} | |
133 | ||
134 | If the help viewer is not running, runs it and displays the given section. | |
135 | ||
136 | The interpretation of {\it section} differs between help viewers. For most viewers, | |
137 | this call is equivalent to KeywordSearch. For MS HTML Help, wxHTML help and external HTML help, | |
138 | if {\it section} has a .htm | |
139 | or .html extension, that HTML file will be displayed; otherwise | |
140 | a keyword search is done. | |
141 | ||
142 | \func{virtual bool}{DisplaySection}{\param{int}{ sectionNo}} | |
143 | ||
144 | If 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} | |
151 | 0 wx.html ; Index | |
152 | 1 wx34.html#classref ; Class reference | |
153 | 2 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 | ||
158 | See 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 | ||
164 | Displays the text in a popup window, if possible. | |
165 | ||
166 | Returns 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 | ||
173 | wxHtmlHelpController returns the frame, size and position. | |
174 | ||
175 | For all other help controllers, this function does nothing | |
176 | and 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 | |
183 | that 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 | ||
189 | If the help viewer is not running, runs it, and searches for sections matching the given keyword. If one | |
190 | match is found, the file is displayed at this section. | |
191 | ||
192 | {\it WinHelp, MS HTML Help:} If more than one match is found, | |
193 | the first topic is displayed. | |
194 | ||
195 | {\it External HTML help, simple wxHTML help:} If more than one match is found, | |
196 | a 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 | ||
204 | If the help viewer is not running, runs it and loads the given file. | |
205 | If the filename is not supplied or is | |
206 | empty, the file specified in {\bf Initialize} is used. If the viewer is | |
207 | already displaying the specified file, it will not be reloaded. This | |
208 | member function may be used before each display call in case the user | |
209 | has opened another file. | |
210 | ||
211 | wxHtmlHelpController ignores this call. | |
212 | ||
213 | \membersection{wxHelpController::OnQuit}\label{wxhelpcontrolleronquit} | |
214 | ||
215 | \func{virtual bool}{OnQuit}{\void} | |
216 | ||
217 | Overridable member called when this application's viewer is quit by the user. | |
218 | ||
219 | This 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 | ||
227 | For wxHtmlHelpController, the title is set (again with \%s indicating the | |
228 | page title) and also the size and position of the frame if the frame is already | |
229 | open. {\it newFrameEachTime} is ignored. | |
230 | ||
231 | For 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 | ||
237 | Sets detailed viewer information. So far this is only relevant to wxExtHelpController. | |
238 | ||
239 | Some 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 | ||
251 | If the viewer is running, quits it by disconnecting. | |
252 | ||
253 | For Windows Help, the viewer will only close if no other application is using it. | |
254 |