]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: help.h | |
3 | // Purpose: interface of wxHelpController | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | ||
10 | #define wxHELP_NETSCAPE 1 | |
11 | ||
12 | ||
13 | /** | |
14 | Help search modes for wxHelpController::KeywordSearch(). | |
15 | */ | |
16 | enum wxHelpSearchMode | |
17 | { | |
18 | wxHELP_SEARCH_INDEX, ///< Search the index only. | |
19 | wxHELP_SEARCH_ALL ///< Search all entries. | |
20 | }; | |
21 | ||
22 | /** | |
23 | @class wxHelpControllerBase | |
24 | ||
25 | This is the abstract base class a family of classes by which applications | |
26 | may invoke a help viewer to provide on-line help. | |
27 | ||
28 | A help controller allows an application to display help, at the contents | |
29 | or at a particular topic, and shut the help program down on termination. | |
30 | This avoids proliferation of many instances of the help viewer whenever the | |
31 | user requests a different topic via the application's menus or buttons. | |
32 | ||
33 | Typically, an application will create a help controller instance when it starts, | |
34 | and immediately call wxHelpController::Initialize to associate a filename with it. | |
35 | The help viewer will only get run, however, just before the first call to | |
36 | display something. | |
37 | ||
38 | @library{wxcore} | |
39 | @category{help} | |
40 | ||
41 | @see wxHelpController, wxHtmlHelpController, @ref overview_html | |
42 | */ | |
43 | class wxHelpControllerBase : public wxObject | |
44 | { | |
45 | public: | |
46 | /** | |
47 | Constructs a help instance object, but does not invoke the help viewer. | |
48 | ||
49 | If you provide a window, it will be used by some help controller classes, such as | |
50 | wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the | |
51 | parent for the help window instead of the value of wxApp::GetTopWindow. | |
52 | ||
53 | You can also change the parent window later with SetParentWindow(). | |
54 | */ | |
55 | wxHelpControllerBase(wxWindow* parentWindow = NULL); | |
56 | ||
57 | /** | |
58 | Destroys the help instance, closing down the viewer if it is running. | |
59 | */ | |
60 | ~wxHelpControllerBase(); | |
61 | ||
62 | /** | |
63 | If the help viewer is not running, runs it and displays the file at the given | |
64 | block number. | |
65 | ||
66 | - @e WinHelp: Refers to the context number. | |
67 | - @e MS HTML Help: Refers to the context number. | |
68 | - @e External HTML help: the same as for DisplaySection(). | |
69 | - @e wxHtmlHelpController: @e sectionNo is an identifier as specified in | |
70 | the @c .hhc file. See @ref overview_html_helpformats. | |
71 | ||
72 | @deprecated | |
73 | This function is for backward compatibility only, and applications | |
74 | should use DisplaySection() instead. | |
75 | */ | |
76 | virtual bool DisplayBlock(long blockNo) = 0; | |
77 | ||
78 | /** | |
79 | If the help viewer is not running, runs it and displays the contents. | |
80 | */ | |
81 | virtual bool DisplayContents() = 0; | |
82 | ||
83 | /** | |
84 | Displays the section as a popup window using a context id. | |
85 | Returns @false if unsuccessful or not implemented. | |
86 | */ | |
87 | virtual bool DisplayContextPopup(int contextId); | |
88 | ||
89 | /** | |
90 | If the help viewer is not running, runs it and displays the given section. | |
91 | ||
92 | The interpretation of section differs between help viewers. | |
93 | For most viewers, this call is equivalent to KeywordSearch. | |
94 | For MS HTML Help, wxHTML help and external HTML help, if section has a | |
95 | .htm or .html extension, that HTML file will be displayed; otherwise a | |
96 | keyword search is done. | |
97 | */ | |
98 | virtual bool DisplaySection(const wxString& section); | |
99 | ||
100 | /** | |
101 | If the help viewer is not running, runs it and displays the given section. | |
102 | ||
103 | - @e WinHelp, MS HTML Help @a sectionNo is a context id. | |
104 | - @e External HTML help: wxExtHelpController implements @a sectionNo as | |
105 | an id in a map file, which is of the form: | |
106 | - @e wxHtmlHelpController: @a sectionNo is an identifier as specified in | |
107 | the @c .hhc file. See @ref overview_html_helpformats. | |
108 | See also the help sample for notes on how to specify section numbers for | |
109 | various help file formats. | |
110 | */ | |
111 | virtual bool DisplaySection(int sectionNo) = 0;; | |
112 | ||
113 | /** | |
114 | Displays the text in a popup window, if possible. | |
115 | ||
116 | Returns @false if unsuccessful or not implemented. | |
117 | */ | |
118 | virtual bool DisplayTextPopup(const wxString& text, | |
119 | const wxPoint& pos); | |
120 | ||
121 | /** | |
122 | For wxHtmlHelpController, returns the latest frame size and position | |
123 | settings and whether a new frame is drawn with each invocation. | |
124 | For all other help controllers, this function does nothing and just returns @NULL. | |
125 | ||
126 | @param size | |
127 | The most recent frame size. | |
128 | @param pos | |
129 | The most recent frame position. | |
130 | @param newFrameEachTime | |
131 | @true if a new frame is drawn with each invocation. | |
132 | */ | |
133 | virtual wxFrame* GetFrameParameters(wxSize* size = NULL, | |
134 | wxPoint* pos = NULL, | |
135 | bool* newFrameEachTime = NULL); | |
136 | ||
137 | /** | |
138 | Returns the window to be used as the parent for the help window. | |
139 | This window is used by wxCHMHelpController, wxWinHelpController and | |
140 | wxHtmlHelpController. | |
141 | */ | |
142 | virtual wxWindow* GetParentWindow() const; | |
143 | ||
144 | //@{ | |
145 | /** | |
146 | Initializes the help instance with a help filename, and optionally a server | |
147 | socket number if using wxHelp (now obsolete). Does not invoke the help viewer. | |
148 | This must be called directly after the help instance object is created and | |
149 | before any attempts to communicate with the viewer. | |
150 | ||
151 | You may omit the file extension and a suitable one will be chosen. | |
152 | For wxHtmlHelpController, the extensions zip, htb and hhp will be appended | |
153 | while searching for a suitable file. For WinHelp, the hlp extension is appended. | |
154 | */ | |
155 | virtual bool Initialize(const wxString& file); | |
156 | virtual bool Initialize(const wxString& file, int server); | |
157 | //@} | |
158 | ||
159 | /** | |
160 | If the help viewer is not running, runs it, and searches for sections matching | |
161 | the given keyword. If one match is found, the file is displayed at this section. | |
162 | The optional parameter allows to search the index (wxHELP_SEARCH_INDEX) | |
163 | but this currently is only supported by the wxHtmlHelpController. | |
164 | ||
165 | - @e WinHelp, MS HTML Help: | |
166 | If more than one match is found, the first topic is displayed. | |
167 | - @e External HTML help, simple wxHTML help: | |
168 | If more than one match is found, a choice of topics is displayed. | |
169 | - @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. | |
170 | */ | |
171 | virtual bool KeywordSearch(const wxString& keyWord, | |
172 | wxHelpSearchMode mode = wxHELP_SEARCH_ALL) = 0; | |
173 | ||
174 | /** | |
175 | If the help viewer is not running, runs it and loads the given file. | |
176 | If the filename is not supplied or is empty, the file specified in | |
177 | Initialize() is used. | |
178 | ||
179 | If the viewer is already displaying the specified file, it will not be | |
180 | reloaded. This member function may be used before each display call in | |
181 | case the user has opened another file. | |
182 | ||
183 | wxHtmlHelpController ignores this call. | |
184 | */ | |
185 | virtual bool LoadFile(const wxString& file = wxEmptyString) = 0; | |
186 | ||
187 | /** | |
188 | Overridable member called when this application's viewer is quit by the user. | |
189 | This does not work for all help controllers. | |
190 | */ | |
191 | virtual void OnQuit(); | |
192 | ||
193 | /** | |
194 | If the viewer is running, quits it by disconnecting. | |
195 | For Windows Help, the viewer will only close if no other application is using it. | |
196 | */ | |
197 | virtual bool Quit() = 0; | |
198 | ||
199 | /** | |
200 | For wxHtmlHelpController, the title is set (with %s indicating the | |
201 | page title) and also the size and position of the frame if the frame is | |
202 | already open. @a newFrameEachTime is ignored. | |
203 | ||
204 | For all other help controllers this function has no effect. | |
205 | */ | |
206 | virtual void SetFrameParameters(const wxString& title, | |
207 | const wxSize& size, | |
208 | const wxPoint& pos = wxDefaultPosition, | |
209 | bool newFrameEachTime = false); | |
210 | ||
211 | /** | |
212 | Sets the window to be used as the parent for the help window. This is used | |
213 | by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. | |
214 | */ | |
215 | virtual void SetParentWindow(wxWindow* parentWindow); | |
216 | ||
217 | /** | |
218 | Sets detailed viewer information. | |
219 | So far this is only relevant to wxExtHelpController. | |
220 | Some examples of usage: | |
221 | ||
222 | @code | |
223 | m_help.SetViewer("kdehelp"); | |
224 | m_help.SetViewer("gnome-help-browser"); | |
225 | m_help.SetViewer("netscape", wxHELP_NETSCAPE); | |
226 | @endcode | |
227 | ||
228 | @param viewer | |
229 | This defaults to "netscape" for wxExtHelpController. | |
230 | @param flags | |
231 | This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating | |
232 | that the viewer is a variant of Netscape Navigator. | |
233 | ||
234 | @todo modernize this function with ::wxLaunchDefaultBrowser | |
235 | */ | |
236 | virtual void SetViewer(const wxString& viewer, long flags=wxHELP_NETSCAPE); | |
237 | }; | |
238 | ||
239 | ||
240 | ||
241 | ||
242 | ||
243 | ||
244 | /** | |
245 | @class wxHelpController | |
246 | ||
247 | This is an alias for one of a family of help controller classes which is | |
248 | most appropriate for the current platform. | |
249 | ||
250 | A help controller allows an application to display help, at the contents | |
251 | or at a particular topic, and shut the help program down on termination. | |
252 | This avoids proliferation of many instances of the help viewer whenever the | |
253 | user requests a different topic via the application's menus or buttons. | |
254 | ||
255 | Typically, an application will create a help controller instance when it starts, | |
256 | and immediately call wxHelpController::Initialize to associate a filename with it. | |
257 | The help viewer will only get run, however, just before the first call to | |
258 | display something. | |
259 | ||
260 | Most help controller classes actually derive from wxHelpControllerBase and have | |
261 | names of the form wxXXXHelpController or wxHelpControllerXXX. | |
262 | An appropriate class is aliased to the name wxHelpController for each platform, as | |
263 | follows: | |
264 | - On desktop Windows, wxCHMHelpController is used (MS HTML Help). | |
265 | - On Windows CE, wxWinceHelpController is used. | |
266 | - On all other platforms, wxHtmlHelpController is used if wxHTML is compiled | |
267 | into wxWidgets; otherwise wxExtHelpController is used (for invoking an | |
268 | external browser). | |
269 | ||
270 | The remaining help controller classes need to be named explicitly by an | |
271 | application that wishes to make use of them. | |
272 | ||
273 | The following help controller classes are defined: | |
274 | - wxWinHelpController, for controlling Windows Help. | |
275 | - wxCHMHelpController, for controlling MS HTML Help. To use this, you need to | |
276 | set wxUSE_MS_HTML_HELP to 1 in setup.h and have the htmlhelp.h header from | |
277 | Microsoft's HTML Help kit. (You don't need the VC++-specific htmlhelp.lib | |
278 | because wxWidgets loads necessary DLL at runtime and so it works with all | |
279 | compilers.) | |
280 | - wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime | |
281 | is not available, wxHtmlHelpController. You need to provide @b both CHM and | |
282 | HTB versions of the help file. For wxMSW only. | |
283 | - wxExtHelpController, for controlling external browsers under Unix. | |
284 | The default browser is Netscape Navigator. The 'help' sample shows its use. | |
285 | - wxWinceHelpController, for controlling a simple @c .htm help controller for | |
286 | Windows CE applications. | |
287 | - wxHtmlHelpController, a sophisticated help controller using wxHTML, in a | |
288 | similar style to the Microsoft HTML Help viewer and using some of the same | |
289 | files. Although it has an API compatible with other help controllers, it has | |
290 | more advanced features, so it is recommended that you use the specific API | |
291 | for this class instead. Note that if you use .zip or .htb formats for your | |
292 | books, you must add this line to your application initialization: | |
293 | @code wxFileSystem::AddHandler(new wxArchiveFSHandler); @endcode | |
294 | or nothing will be shown in your help window. | |
295 | ||
296 | @library{wxcore} | |
297 | @category{help} | |
298 | ||
299 | @see wxHtmlHelpController, @ref overview_html | |
300 | */ | |
301 | class wxHelpController : public wxHelpControllerBase | |
302 | { | |
303 | public: | |
304 | /** | |
305 | Constructs a help instance object, but does not invoke the help viewer. | |
306 | ||
307 | If you provide a window, it will be used by some help controller classes, such as | |
308 | wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the | |
309 | parent for the help window instead of the value of wxApp::GetTopWindow. | |
310 | ||
311 | You can also change the parent window later with SetParentWindow(). | |
312 | */ | |
313 | wxHelpController(wxWindow* parentWindow = NULL); | |
314 | }; | |
315 | ||
316 |