1 /////////////////////////////////////////////////////////////////////////////
2 // Name: src/generic/helpext.cpp
3 // Purpose: an external help controller for wxWidgets
4 // Author: Karsten Ballueder
8 // Copyright: (c) Karsten Ballueder
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #include "wx/wxprec.h"
18 #if wxUSE_HELP && !defined(__WXWINCE__) && (!defined(__WXMAC__) || defined(__WXMAC_OSX__))
21 #include "wx/string.h"
25 #include "wx/msgdlg.h"
26 #include "wx/choicdlg.h"
30 #include "wx/filename.h"
31 #include "wx/textfile.h"
32 #include "wx/generic/helpext.h"
38 #if !defined(__WINDOWS__) && !defined(__OS2__)
43 #include "wx/msw/mslu.h"
48 #include "wx/msw/winundef.h"
51 // ----------------------------------------------------------------------------
53 // ----------------------------------------------------------------------------
55 /// Name for map file.
56 #define WXEXTHELP_MAPFILE _T("wxhelp.map")
58 /// Character introducing comments/documentation field in map file.
59 #define WXEXTHELP_COMMENTCHAR ';'
63 IMPLEMENT_CLASS(wxExtHelpController
, wxHelpControllerBase
)
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")
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.
76 wxExtHelpController::wxExtHelpController(wxWindow
* parentWindow
)
77 : wxHelpControllerBase(parentWindow
)
81 m_BrowserIsNetscape
= false;
83 wxChar
*browser
= wxGetenv(WXEXTHELP_ENVVAR_BROWSER
);
86 m_BrowserName
= browser
;
87 browser
= wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE
);
88 m_BrowserIsNetscape
= browser
&& (wxAtoi(browser
) != 0);
92 wxExtHelpController::~wxExtHelpController()
97 void wxExtHelpController::SetBrowser(const wxString
& browsername
, bool isNetscape
)
99 m_BrowserName
= browsername
;
100 m_BrowserIsNetscape
= isNetscape
;
103 // Set viewer: new, generic name for SetBrowser
104 void wxExtHelpController::SetViewer(const wxString
& viewer
, long flags
)
106 SetBrowser(viewer
, (flags
& wxHELP_NETSCAPE
) != 0);
109 bool wxExtHelpController::DisplayHelp(const wxString
&relativeURL
)
111 // construct hte URL to open -- it's just a file
112 wxString
url(_T("file://") + m_helpDir
);
113 url
<< wxFILE_SEP_PATH
<< relativeURL
;
115 // use the explicit browser program if specified
116 if ( !m_BrowserName
.empty() )
118 if ( m_BrowserIsNetscape
)
121 command
<< m_BrowserName
122 << wxT(" -remote openURL(") << url
<< wxT(')');
123 if ( wxExecute(command
, wxEXEC_SYNC
) != -1 )
127 if ( wxExecute(m_BrowserName
+ _T(' ') + url
, wxEXEC_SYNC
) != -1 )
130 //else: either no browser explicitly specified or we failed to open it
132 // just use default browser
133 return wxLaunchDefaultBrowser(url
);
136 class wxExtHelpMapEntry
: public wxObject
142 wxExtHelpMapEntry(int iid
, wxString
const &iurl
, wxString
const &idoc
)
143 { id
= iid
; url
= iurl
; doc
= idoc
; }
146 void wxExtHelpController::DeleteList()
150 wxList::compatibility_iterator node
= m_MapList
->GetFirst();
153 delete (wxExtHelpMapEntry
*)node
->GetData();
154 m_MapList
->Erase(node
);
155 node
= m_MapList
->GetFirst();
159 m_MapList
= (wxList
*) NULL
;
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
)
168 return LoadFile(file
);
171 bool wxExtHelpController::ParseMapFileLine(const wxString
& line
)
173 const wxChar
*p
= line
.c_str();
176 while ( isascii(*p
) && isspace(*p
) )
179 // skip empty lines and comments
180 if ( *p
== _T('\0') || *p
== WXEXTHELP_COMMENTCHAR
)
183 // the line is of the form "num url" so we must have an integer now
185 const unsigned long id
= wxStrtoul(p
, &end
, 0);
191 while ( isascii(*p
) && isspace(*p
) )
194 // next should be the URL
196 url
.reserve(line
.length());
197 while ( isascii(*p
) && !isspace(*p
) )
200 while ( isascii(*p
) && isspace(*p
) )
203 // and finally the optional description of the entry after comment
205 if ( *p
== WXEXTHELP_COMMENTCHAR
)
208 while ( isascii(*p
) && isspace(*p
) )
213 m_MapList
->Append(new wxExtHelpMapEntry(id
, url
, doc
));
219 // file is a misnomer as it's the name of the base help directory
220 bool wxExtHelpController::LoadFile(const wxString
& file
)
222 wxFileName
helpDir(wxFileName::DirName(file
));
223 helpDir
.MakeAbsolute();
225 bool dirExists
= false;
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();
235 wxString locName
= loc
->GetName();
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();
245 // try without encoding
246 const wxString locNameWithoutEncoding
= locName
.BeforeLast(_T('.'));
247 if ( !locNameWithoutEncoding
.empty() )
249 helpDirLoc
= helpDir
;
250 helpDirLoc
.AppendDir(locNameWithoutEncoding
);
251 dirExists
= helpDirLoc
.DirExists();
257 // try without country part
258 wxString locNameWithoutCountry
= locName
.BeforeLast(_T('_'));
259 if ( !locNameWithoutCountry
.empty() )
261 helpDirLoc
= helpDir
;
262 helpDirLoc
.AppendDir(locNameWithoutCountry
);
263 dirExists
= helpDirLoc
.DirExists();
268 helpDir
= helpDirLoc
;
272 if ( ! dirExists
&& !helpDir
.DirExists() )
274 wxLogError(_("Help directory \"%s\" not found."),
275 helpDir
.GetFullPath().c_str());
279 const wxFileName
mapFile(helpDir
.GetFullPath(), WXEXTHELP_MAPFILE
);
280 if ( ! mapFile
.FileExists() )
282 wxLogError(_("Help file \"%s\" not found."),
283 mapFile
.GetFullPath().c_str());
288 m_MapList
= new wxList
;
292 if ( !input
.Open(mapFile
.GetFullPath()) )
295 for ( wxString
& line
= input
.GetFirstLine();
297 line
= input
.GetNextLine() )
299 if ( !ParseMapFileLine(line
) )
301 wxLogWarning(_("Line %lu of map file \"%s\" has invalid syntax, skipped."),
302 (unsigned long)input
.GetCurrentLine(),
303 mapFile
.GetFullPath().c_str());
307 if ( !m_NumOfEntries
)
309 wxLogError(_("No valid mappings found in the file \"%s\"."),
310 mapFile
.GetFullPath().c_str());
314 m_helpDir
= helpDir
.GetFullPath(); // now it's valid
319 bool wxExtHelpController::DisplayContents()
321 if (! m_NumOfEntries
)
325 wxList::compatibility_iterator node
= m_MapList
->GetFirst();
326 wxExtHelpMapEntry
*entry
;
329 entry
= (wxExtHelpMapEntry
*)node
->GetData();
330 if (entry
->id
== CONTENTS_ID
)
332 contents
= entry
->url
;
336 node
= node
->GetNext();
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
);
347 // if not found, open homemade toc:
348 return rc
? true : KeywordSearch(wxEmptyString
);
351 bool wxExtHelpController::DisplaySection(int sectionNo
)
353 if (! m_NumOfEntries
)
356 wxBusyCursor b
; // display a busy cursor
357 wxList::compatibility_iterator node
= m_MapList
->GetFirst();
358 wxExtHelpMapEntry
*entry
;
361 entry
= (wxExtHelpMapEntry
*)node
->GetData();
362 if (entry
->id
== sectionNo
)
363 return DisplayHelp(entry
->url
);
364 node
= node
->GetNext();
370 bool wxExtHelpController::DisplaySection(const wxString
& section
)
372 bool isFilename
= (section
.Find(wxT(".htm")) != -1);
375 return DisplayHelp(section
);
377 return KeywordSearch(section
);
380 bool wxExtHelpController::DisplayBlock(long blockNo
)
382 return DisplaySection((int)blockNo
);
385 bool wxExtHelpController::KeywordSearch(const wxString
& k
,
386 wxHelpSearchMode
WXUNUSED(mode
))
388 if (! m_NumOfEntries
)
391 wxString
*choices
= new wxString
[m_NumOfEntries
];
392 wxString
*urls
= new wxString
[m_NumOfEntries
];
396 bool showAll
= k
.empty();
398 wxList::compatibility_iterator node
= m_MapList
->GetFirst();
401 // display a busy cursor
403 wxString compA
, compB
;
404 wxExtHelpMapEntry
*entry
;
406 // we compare case insensitive
415 entry
= (wxExtHelpMapEntry
*)node
->GetData();
418 bool testTarget
= ! compB
.empty();
419 if (testTarget
&& ! showAll
)
422 testTarget
= compB
.Contains(compA
);
427 urls
[idx
] = entry
->url
;
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
;
435 wxChar targetChar
= entry
->doc
.c_str()[j
];
436 if ((targetChar
== 0) || (targetChar
== WXEXTHELP_COMMENTCHAR
))
439 choices
[idx
] << targetChar
;
445 node
= node
->GetNext();
452 wxMessageBox(_("No entries found."));
456 rc
= DisplayHelp(urls
[0]);
460 idx
= wxGetSingleChoiceIndex(
461 showAll
? _("Help Index") : _("Relevant entries:"),
462 showAll
? _("Help Index") : _("Entries found"),
465 rc
= DisplayHelp(urls
[idx
]);
476 bool wxExtHelpController::Quit()
481 void wxExtHelpController::OnQuit()