]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: src/generic/helpext.cpp | |
3 | // Purpose: an external help controller for wxWidgets | |
4 | // Author: Karsten Ballueder | |
5 | // Modified by: | |
6 | // Created: 04/01/98 | |
7 | // RCS-ID: $Id$ | |
8 | // Copyright: (c) Karsten Ballueder | |
9 | // Licence: wxWindows licence | |
10 | ///////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | #include "wx/wxprec.h" | |
13 | ||
14 | #ifdef __BORLANDC__ | |
15 | #pragma hdrstop | |
16 | #endif | |
17 | ||
18 | #if wxUSE_HELP && !defined(__WXWINCE__) | |
19 | ||
20 | #ifndef WX_PRECOMP | |
21 | #include "wx/list.h" | |
22 | #include "wx/string.h" | |
23 | #include "wx/utils.h" | |
24 | #include "wx/intl.h" | |
25 | #include "wx/msgdlg.h" | |
26 | #include "wx/choicdlg.h" | |
27 | #include "wx/log.h" | |
28 | #endif | |
29 | ||
30 | #include "wx/filename.h" | |
31 | #include "wx/textfile.h" | |
32 | #include "wx/generic/helpext.h" | |
33 | ||
34 | #include <stdio.h> | |
35 | #include <ctype.h> | |
36 | #include <sys/stat.h> | |
37 | ||
38 | #if !defined(__WINDOWS__) && !defined(__OS2__) | |
39 | #include <unistd.h> | |
40 | #endif | |
41 | ||
42 | #ifdef __WINDOWS__ | |
43 | #include "wx/msw/mslu.h" | |
44 | #endif | |
45 | ||
46 | #ifdef __WXMSW__ | |
47 | #include <windows.h> | |
48 | #include "wx/msw/winundef.h" | |
49 | #endif | |
50 | ||
51 | // ---------------------------------------------------------------------------- | |
52 | // constants | |
53 | // ---------------------------------------------------------------------------- | |
54 | ||
55 | /// Name for map file. | |
56 | #define WXEXTHELP_MAPFILE _T("wxhelp.map") | |
57 | ||
58 | /// Character introducing comments/documentation field in map file. | |
59 | #define WXEXTHELP_COMMENTCHAR ';' | |
60 | ||
61 | #define CONTENTS_ID 0 | |
62 | ||
63 | IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase) | |
64 | ||
65 | /// Name of environment variable to set help browser. | |
66 | #define WXEXTHELP_ENVVAR_BROWSER wxT("WX_HELPBROWSER") | |
67 | /// Is browser a netscape browser? | |
68 | #define WXEXTHELP_ENVVAR_BROWSERISNETSCAPE wxT("WX_HELPBROWSER_NS") | |
69 | ||
70 | /** | |
71 | This class implements help via an external browser. | |
72 | It requires the name of a directory containing the documentation | |
73 | and a file mapping numerical Section numbers to relative URLS. | |
74 | */ | |
75 | ||
76 | wxExtHelpController::wxExtHelpController(wxWindow* parentWindow) | |
77 | : wxHelpControllerBase(parentWindow) | |
78 | { | |
79 | m_MapList = NULL; | |
80 | m_NumOfEntries = 0; | |
81 | m_BrowserIsNetscape = false; | |
82 | ||
83 | wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER); | |
84 | if (browser) | |
85 | { | |
86 | m_BrowserName = browser; | |
87 | browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE); | |
88 | m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0); | |
89 | } | |
90 | } | |
91 | ||
92 | wxExtHelpController::~wxExtHelpController() | |
93 | { | |
94 | DeleteList(); | |
95 | } | |
96 | ||
97 | void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscape) | |
98 | { | |
99 | m_BrowserName = browsername; | |
100 | m_BrowserIsNetscape = isNetscape; | |
101 | } | |
102 | ||
103 | // Set viewer: new, generic name for SetBrowser | |
104 | void wxExtHelpController::SetViewer(const wxString& viewer, long flags) | |
105 | { | |
106 | SetBrowser(viewer, (flags & wxHELP_NETSCAPE) != 0); | |
107 | } | |
108 | ||
109 | bool wxExtHelpController::DisplayHelp(const wxString &relativeURL) | |
110 | { | |
111 | // construct hte URL to open -- it's just a file | |
112 | wxString url(_T("file://") + m_helpDir); | |
113 | url << wxFILE_SEP_PATH << relativeURL; | |
114 | ||
115 | // use the explicit browser program if specified | |
116 | if ( !m_BrowserName.empty() ) | |
117 | { | |
118 | if ( m_BrowserIsNetscape ) | |
119 | { | |
120 | wxString command; | |
121 | command << m_BrowserName | |
122 | << wxT(" -remote openURL(") << url << wxT(')'); | |
123 | if ( wxExecute(command, wxEXEC_SYNC) != -1 ) | |
124 | return true; | |
125 | } | |
126 | ||
127 | if ( wxExecute(m_BrowserName + _T(' ') + url, wxEXEC_SYNC) != -1 ) | |
128 | return true; | |
129 | } | |
130 | //else: either no browser explicitly specified or we failed to open it | |
131 | ||
132 | // just use default browser | |
133 | return wxLaunchDefaultBrowser(url); | |
134 | } | |
135 | ||
136 | class wxExtHelpMapEntry : public wxObject | |
137 | { | |
138 | public: | |
139 | int id; | |
140 | wxString url; | |
141 | wxString doc; | |
142 | wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc) | |
143 | { id = iid; url = iurl; doc = idoc; } | |
144 | }; | |
145 | ||
146 | void wxExtHelpController::DeleteList() | |
147 | { | |
148 | if (m_MapList) | |
149 | { | |
150 | wxList::compatibility_iterator node = m_MapList->GetFirst(); | |
151 | while (node) | |
152 | { | |
153 | delete (wxExtHelpMapEntry *)node->GetData(); | |
154 | m_MapList->Erase(node); | |
155 | node = m_MapList->GetFirst(); | |
156 | } | |
157 | ||
158 | delete m_MapList; | |
159 | m_MapList = (wxList*) NULL; | |
160 | } | |
161 | } | |
162 | ||
163 | // This must be called to tell the controller where to find the documentation. | |
164 | // @param file - NOT a filename, but a directory name. | |
165 | // @return true on success | |
166 | bool wxExtHelpController::Initialize(const wxString& file) | |
167 | { | |
168 | return LoadFile(file); | |
169 | } | |
170 | ||
171 | bool wxExtHelpController::ParseMapFileLine(const wxString& line) | |
172 | { | |
173 | const wxChar *p = line.c_str(); | |
174 | ||
175 | // skip whitespace | |
176 | while ( isascii(*p) && isspace(*p) ) | |
177 | p++; | |
178 | ||
179 | // skip empty lines and comments | |
180 | if ( *p == _T('\0') || *p == WXEXTHELP_COMMENTCHAR ) | |
181 | return true; | |
182 | ||
183 | // the line is of the form "num url" so we must have an integer now | |
184 | wxChar *end; | |
185 | const unsigned long id = wxStrtoul(p, &end, 0); | |
186 | ||
187 | if ( end == p ) | |
188 | return false; | |
189 | ||
190 | p = end; | |
191 | while ( isascii(*p) && isspace(*p) ) | |
192 | p++; | |
193 | ||
194 | // next should be the URL | |
195 | wxString url; | |
196 | url.reserve(line.length()); | |
197 | while ( isascii(*p) && !isspace(*p) ) | |
198 | url += *p++; | |
199 | ||
200 | while ( isascii(*p) && isspace(*p) ) | |
201 | p++; | |
202 | ||
203 | // and finally the optional description of the entry after comment | |
204 | wxString doc; | |
205 | if ( *p == WXEXTHELP_COMMENTCHAR ) | |
206 | { | |
207 | p++; | |
208 | while ( isascii(*p) && isspace(*p) ) | |
209 | p++; | |
210 | doc = p; | |
211 | } | |
212 | ||
213 | m_MapList->Append(new wxExtHelpMapEntry(id, url, doc)); | |
214 | m_NumOfEntries++; | |
215 | ||
216 | return true; | |
217 | } | |
218 | ||
219 | // file is a misnomer as it's the name of the base help directory | |
220 | bool wxExtHelpController::LoadFile(const wxString& file) | |
221 | { | |
222 | wxFileName helpDir(wxFileName::DirName(file)); | |
223 | helpDir.MakeAbsolute(); | |
224 | ||
225 | bool dirExists = false; | |
226 | ||
227 | #if wxUSE_INTL | |
228 | // If a locale is set, look in file/localename, i.e. If passed | |
229 | // "/usr/local/myapp/help" and the current wxLocale is set to be "de", then | |
230 | // look in "/usr/local/myapp/help/de/" first and fall back to | |
231 | // "/usr/local/myapp/help" if that doesn't exist. | |
232 | const wxLocale * const loc = wxGetLocale(); | |
233 | if ( loc ) | |
234 | { | |
235 | wxString locName = loc->GetName(); | |
236 | ||
237 | // the locale is in general of the form xx_YY.zzzz, try the full firm | |
238 | // first and then also more general ones | |
239 | wxFileName helpDirLoc(helpDir); | |
240 | helpDirLoc.AppendDir(locName); | |
241 | dirExists = helpDirLoc.DirExists(); | |
242 | ||
243 | if ( ! dirExists ) | |
244 | { | |
245 | // try without encoding | |
246 | const wxString locNameWithoutEncoding = locName.BeforeLast(_T('.')); | |
247 | if ( !locNameWithoutEncoding.empty() ) | |
248 | { | |
249 | helpDirLoc = helpDir; | |
250 | helpDirLoc.AppendDir(locNameWithoutEncoding); | |
251 | dirExists = helpDirLoc.DirExists(); | |
252 | } | |
253 | } | |
254 | ||
255 | if ( !dirExists ) | |
256 | { | |
257 | // try without country part | |
258 | wxString locNameWithoutCountry = locName.BeforeLast(_T('_')); | |
259 | if ( !locNameWithoutCountry.empty() ) | |
260 | { | |
261 | helpDirLoc = helpDir; | |
262 | helpDirLoc.AppendDir(locNameWithoutCountry); | |
263 | dirExists = helpDirLoc.DirExists(); | |
264 | } | |
265 | } | |
266 | ||
267 | if ( dirExists ) | |
268 | helpDir = helpDirLoc; | |
269 | } | |
270 | #endif // wxUSE_INTL | |
271 | ||
272 | if ( ! dirExists && !helpDir.DirExists() ) | |
273 | { | |
274 | wxLogError(_("Help directory \"%s\" not found."), | |
275 | helpDir.GetFullPath().c_str()); | |
276 | return false; | |
277 | } | |
278 | ||
279 | const wxFileName mapFile(helpDir.GetFullPath(), WXEXTHELP_MAPFILE); | |
280 | if ( ! mapFile.FileExists() ) | |
281 | { | |
282 | wxLogError(_("Help file \"%s\" not found."), | |
283 | mapFile.GetFullPath().c_str()); | |
284 | return false; | |
285 | } | |
286 | ||
287 | DeleteList(); | |
288 | m_MapList = new wxList; | |
289 | m_NumOfEntries = 0; | |
290 | ||
291 | wxTextFile input; | |
292 | if ( !input.Open(mapFile.GetFullPath()) ) | |
293 | return false; | |
294 | ||
295 | for ( wxString& line = input.GetFirstLine(); | |
296 | !input.Eof(); | |
297 | line = input.GetNextLine() ) | |
298 | { | |
299 | if ( !ParseMapFileLine(line) ) | |
300 | { | |
301 | wxLogWarning(_("Line %lu of map file \"%s\" has invalid syntax, skipped."), | |
302 | (unsigned long)input.GetCurrentLine(), | |
303 | mapFile.GetFullPath().c_str()); | |
304 | } | |
305 | } | |
306 | ||
307 | if ( !m_NumOfEntries ) | |
308 | { | |
309 | wxLogError(_("No valid mappings found in the file \"%s\"."), | |
310 | mapFile.GetFullPath().c_str()); | |
311 | return false; | |
312 | } | |
313 | ||
314 | m_helpDir = helpDir.GetFullPath(); // now it's valid | |
315 | return true; | |
316 | } | |
317 | ||
318 | ||
319 | bool wxExtHelpController::DisplayContents() | |
320 | { | |
321 | if (! m_NumOfEntries) | |
322 | return false; | |
323 | ||
324 | wxString contents; | |
325 | wxList::compatibility_iterator node = m_MapList->GetFirst(); | |
326 | wxExtHelpMapEntry *entry; | |
327 | while (node) | |
328 | { | |
329 | entry = (wxExtHelpMapEntry *)node->GetData(); | |
330 | if (entry->id == CONTENTS_ID) | |
331 | { | |
332 | contents = entry->url; | |
333 | break; | |
334 | } | |
335 | ||
336 | node = node->GetNext(); | |
337 | } | |
338 | ||
339 | bool rc = false; | |
340 | wxString file; | |
341 | file << m_helpDir << wxFILE_SEP_PATH << contents; | |
342 | if (file.Contains(wxT('#'))) | |
343 | file = file.BeforeLast(wxT('#')); | |
344 | if (contents.length() && wxFileExists(file)) | |
345 | rc = DisplaySection(CONTENTS_ID); | |
346 | ||
347 | // if not found, open homemade toc: | |
348 | return rc ? true : KeywordSearch(wxEmptyString); | |
349 | } | |
350 | ||
351 | bool wxExtHelpController::DisplaySection(int sectionNo) | |
352 | { | |
353 | if (! m_NumOfEntries) | |
354 | return false; | |
355 | ||
356 | wxBusyCursor b; // display a busy cursor | |
357 | wxList::compatibility_iterator node = m_MapList->GetFirst(); | |
358 | wxExtHelpMapEntry *entry; | |
359 | while (node) | |
360 | { | |
361 | entry = (wxExtHelpMapEntry *)node->GetData(); | |
362 | if (entry->id == sectionNo) | |
363 | return DisplayHelp(entry->url); | |
364 | node = node->GetNext(); | |
365 | } | |
366 | ||
367 | return false; | |
368 | } | |
369 | ||
370 | bool wxExtHelpController::DisplaySection(const wxString& section) | |
371 | { | |
372 | bool isFilename = (section.Find(wxT(".htm")) != -1); | |
373 | ||
374 | if (isFilename) | |
375 | return DisplayHelp(section); | |
376 | else | |
377 | return KeywordSearch(section); | |
378 | } | |
379 | ||
380 | bool wxExtHelpController::DisplayBlock(long blockNo) | |
381 | { | |
382 | return DisplaySection((int)blockNo); | |
383 | } | |
384 | ||
385 | bool wxExtHelpController::KeywordSearch(const wxString& k, | |
386 | wxHelpSearchMode WXUNUSED(mode)) | |
387 | { | |
388 | if (! m_NumOfEntries) | |
389 | return false; | |
390 | ||
391 | wxString *choices = new wxString[m_NumOfEntries]; | |
392 | wxString *urls = new wxString[m_NumOfEntries]; | |
393 | ||
394 | int idx = 0; | |
395 | bool rc = false; | |
396 | bool showAll = k.empty(); | |
397 | ||
398 | wxList::compatibility_iterator node = m_MapList->GetFirst(); | |
399 | ||
400 | { | |
401 | // display a busy cursor | |
402 | wxBusyCursor b; | |
403 | wxString compA, compB; | |
404 | wxExtHelpMapEntry *entry; | |
405 | ||
406 | // we compare case insensitive | |
407 | if (! showAll) | |
408 | { | |
409 | compA = k; | |
410 | compA.LowerCase(); | |
411 | } | |
412 | ||
413 | while (node) | |
414 | { | |
415 | entry = (wxExtHelpMapEntry *)node->GetData(); | |
416 | compB = entry->doc; | |
417 | ||
418 | bool testTarget = ! compB.empty(); | |
419 | if (testTarget && ! showAll) | |
420 | { | |
421 | compB.LowerCase(); | |
422 | testTarget = compB.Contains(compA); | |
423 | } | |
424 | ||
425 | if (testTarget) | |
426 | { | |
427 | urls[idx] = entry->url; | |
428 | // doesn't work: | |
429 | // choices[idx] = (**i).doc.Contains((**i).doc.Before(WXEXTHELP_COMMENTCHAR)); | |
430 | //if (choices[idx].empty()) // didn't contain the ';' | |
431 | // choices[idx] = (**i).doc; | |
432 | choices[idx] = wxEmptyString; | |
433 | for (int j=0; ; j++) | |
434 | { | |
435 | wxChar targetChar = entry->doc.c_str()[j]; | |
436 | if ((targetChar == 0) || (targetChar == WXEXTHELP_COMMENTCHAR)) | |
437 | break; | |
438 | ||
439 | choices[idx] << targetChar; | |
440 | } | |
441 | ||
442 | idx++; | |
443 | } | |
444 | ||
445 | node = node->GetNext(); | |
446 | } | |
447 | } | |
448 | ||
449 | switch (idx) | |
450 | { | |
451 | case 0: | |
452 | wxMessageBox(_("No entries found.")); | |
453 | break; | |
454 | ||
455 | case 1: | |
456 | rc = DisplayHelp(urls[0]); | |
457 | break; | |
458 | ||
459 | default: | |
460 | if (showAll) | |
461 | idx = wxGetSingleChoiceIndex(_("Help Index"), | |
462 | _("Help Index"), | |
463 | idx, choices); | |
464 | else | |
465 | idx = wxGetSingleChoiceIndex(_("Relevant entries:"), | |
466 | _("Entries found"), | |
467 | idx, choices); | |
468 | ||
469 | if (idx >= 0) | |
470 | rc = DisplayHelp(urls[idx]); | |
471 | break; | |
472 | } | |
473 | ||
474 | delete [] urls; | |
475 | delete [] choices; | |
476 | ||
477 | return rc; | |
478 | } | |
479 | ||
480 | ||
481 | bool wxExtHelpController::Quit() | |
482 | { | |
483 | return true; | |
484 | } | |
485 | ||
486 | void wxExtHelpController::OnQuit() | |
487 | { | |
488 | } | |
489 | ||
490 | #endif // wxUSE_HELP |