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