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