src/generic/helpext.cpp

   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__) && (!defined(__WXMAC__) || defined(__WXMAC_OSX__))
  19
  20 #ifndef WX_PRECOMP
  21     #include "wx/string.h"
  22     #include "wx/utils.h"
  23     #include "wx/list.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
 110 wxExtHelpController::DisplayHelp(const wxString &relativeURL)
 111 {
 112     // construct hte URL to open -- it's just a file
 113     wxString url(_T("file://") + m_helpDir);
 114     url << wxFILE_SEP_PATH << relativeURL;
 115
 116     // use the explicit browser program if specified
 117     if ( !m_BrowserName.empty() )
 118     {
 119         if ( m_BrowserIsNetscape )
 120         {
 121             wxString command;
 122             command << m_BrowserName
 123                     << wxT(" -remote openURL(") << url << wxT(')');
 124             if ( wxExecute(command, wxEXEC_SYNC) != -1 )
 125                 return true;
 126         }
 127
 128         if ( wxExecute(m_BrowserName + _T(' ') + url, wxEXEC_SYNC) != -1 )
 129             return true;
 130     }
 131     //else: either no browser explicitly specified or we failed to open it
 132
 133     // just use default browser
 134     return wxLaunchDefaultBrowser(url);
 135 }
 136
 137 class wxExtHelpMapEntry : public wxObject
 138 {
 139 public:
 140    int      id;
 141    wxString url;
 142    wxString doc;
 143    wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
 144       { id = iid; url = iurl; doc = idoc; }
 145 };
 146
 147 void wxExtHelpController::DeleteList()
 148 {
 149    if(m_MapList)
 150    {
 151       wxList::compatibility_iterator node = m_MapList->GetFirst();
 152       while (node)
 153       {
 154          delete (wxExtHelpMapEntry *)node->GetData();
 155          m_MapList->Erase(node);
 156          node = m_MapList->GetFirst();
 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
 164     documentation.
 165     @param file - NOT a filename, but a directory name.
 166     @return true on success
 167 */
 168 bool
 169 wxExtHelpController::Initialize(const wxString& file)
 170 {
 171    return LoadFile(file);
 172 }
 173
 174
 175 bool wxExtHelpController::ParseMapFileLine(const wxString& line)
 176 {
 177     const wxChar *p = line.c_str();
 178
 179     // skip whitespace
 180     while ( isascii(*p) && isspace(*p) )
 181         p++;
 182
 183     // skip empty lines and comments
 184     if ( *p == _T('\0') || *p == WXEXTHELP_COMMENTCHAR )
 185         return true;
 186
 187     // the line is of the form "num url" so we must have an integer now
 188     wxChar *end;
 189     const unsigned long id = wxStrtoul(p, &end, 0);
 190
 191     if ( end == p )
 192         return false;
 193
 194     p = end;
 195     while ( isascii(*p) && isspace(*p) )
 196         p++;
 197
 198     // next should be the URL
 199     wxString url;
 200     url.reserve(line.length());
 201     while ( isascii(*p) && !isspace(*p) )
 202         url += *p++;
 203
 204     while ( isascii(*p) && isspace(*p) )
 205         p++;
 206
 207     // and finally the optional description of the entry after comment
 208     wxString doc;
 209     if ( *p == WXEXTHELP_COMMENTCHAR )
 210     {
 211         p++;
 212         while ( isascii(*p) && isspace(*p) )
 213             p++;
 214         doc = p;
 215     }
 216
 217     m_MapList->Append(new wxExtHelpMapEntry(id, url, doc));
 218     m_NumOfEntries++;
 219
 220     return true;
 221 }
 222
 223 // file is a misnomer as it's the name of the base help directory
 224 bool wxExtHelpController::LoadFile(const wxString& file)
 225 {
 226     wxFileName helpDir(wxFileName::DirName(file));
 227     helpDir.MakeAbsolute();
 228
 229     bool dirExists = false;
 230
 231 #if wxUSE_INTL
 232     // If a locale is set, look in file/localename, i.e. If passed
 233     // "/usr/local/myapp/help" and the current wxLocale is set to be "de", then
 234     // look in "/usr/local/myapp/help/de/" first and fall back to
 235     // "/usr/local/myapp/help" if that doesn't exist.
 236     const wxLocale * const loc = wxGetLocale();
 237     if ( loc )
 238     {
 239         wxString locName = loc->GetName();
 240
 241         // the locale is in general of the form xx_YY.zzzz, try the full firm
 242         // first and then also more general ones
 243         wxFileName helpDirLoc(helpDir);
 244         helpDirLoc.AppendDir(locName);
 245         dirExists = helpDirLoc.DirExists();
 246
 247         if ( !dirExists )
 248         {
 249             // try without encoding
 250             const wxString locNameWithoutEncoding = locName.BeforeLast(_T('.'));
 251             if ( !locNameWithoutEncoding.empty() )
 252             {
 253                 helpDirLoc = helpDir;
 254                 helpDirLoc.AppendDir(locNameWithoutEncoding);
 255                 dirExists = helpDirLoc.DirExists();
 256             }
 257         }
 258
 259         if ( !dirExists )
 260         {
 261             // try without country part
 262             wxString locNameWithoutCountry = locName.BeforeLast(_T('_'));
 263             if ( !locNameWithoutCountry.empty() )
 264             {
 265                 helpDirLoc = helpDir;
 266                 helpDirLoc.AppendDir(locNameWithoutCountry);
 267                 dirExists = helpDirLoc.DirExists();
 268             }
 269         }
 270
 271         if ( dirExists )
 272             helpDir = helpDirLoc;
 273     }
 274 #endif // wxUSE_INTL
 275
 276     if ( !dirExists && !helpDir.DirExists() )
 277     {
 278         wxLogError(_("Help directory \"%s\" not found."),
 279                    helpDir.GetFullPath().c_str());
 280         return false;
 281     }
 282
 283     const wxFileName mapFile(helpDir.GetFullPath(), WXEXTHELP_MAPFILE);
 284     if ( !mapFile.FileExists() )
 285     {
 286         wxLogError(_("Help file \"%s\" not found."),
 287                    mapFile.GetFullPath().c_str());
 288         return false;
 289     }
 290
 291     DeleteList();
 292     m_MapList = new wxList;
 293     m_NumOfEntries = 0;
 294
 295     wxTextFile input;
 296     if ( !input.Open(mapFile.GetFullPath()) )
 297         return false;
 298
 299     for ( wxString& line = input.GetFirstLine();
 300           !input.Eof();
 301           line = input.GetNextLine() )
 302     {
 303         if ( !ParseMapFileLine(line) )
 304         {
 305             wxLogWarning(_("Line %lu of map file \"%s\" has invalid syntax, skipped."),
 306                          (unsigned long)input.GetCurrentLine(),
 307                          mapFile.GetFullPath().c_str());
 308         }
 309     }
 310
 311     if ( !m_NumOfEntries )
 312     {
 313         wxLogError(_("No valid mappings found in the file \"%s\"."),
 314                    mapFile.GetFullPath().c_str());
 315         return false;
 316     }
 317
 318     m_helpDir = helpDir.GetFullPath(); // now it's valid
 319     return true;
 320 }
 321
 322
 323 bool
 324 wxExtHelpController::DisplayContents()
 325 {
 326    if(! m_NumOfEntries)
 327       return false;
 328
 329    wxString contents;
 330    wxList::compatibility_iterator node = m_MapList->GetFirst();
 331    wxExtHelpMapEntry *entry;
 332    while(node)
 333    {
 334       entry = (wxExtHelpMapEntry *)node->GetData();
 335       if(entry->id == CONTENTS_ID)
 336       {
 337          contents = entry->url;
 338          break;
 339       }
 340       node = node->GetNext();
 341    }
 342
 343    bool rc = false;
 344    wxString file;
 345    file << m_helpDir << wxFILE_SEP_PATH << contents;
 346    if(file.Contains(wxT('#')))
 347       file = file.BeforeLast(wxT('#'));
 348    if(contents.length() && wxFileExists(file))
 349       rc = DisplaySection(CONTENTS_ID);
 350
 351    // if not found, open homemade toc:
 352    return rc ? true : KeywordSearch(wxEmptyString);
 353 }
 354
 355 bool
 356 wxExtHelpController::DisplaySection(int sectionNo)
 357 {
 358    if(! m_NumOfEntries)
 359       return false;
 360
 361    wxBusyCursor b; // display a busy cursor
 362    wxList::compatibility_iterator node = m_MapList->GetFirst();
 363    wxExtHelpMapEntry *entry;
 364    while(node)
 365    {
 366       entry = (wxExtHelpMapEntry *)node->GetData();
 367       if(entry->id == sectionNo)
 368          return DisplayHelp(entry->url);
 369       node = node->GetNext();
 370    }
 371    return false;
 372 }
 373
 374 bool wxExtHelpController::DisplaySection(const wxString& section)
 375 {
 376     bool isFilename = (section.Find(wxT(".htm")) != -1);
 377
 378     if (isFilename)
 379         return DisplayHelp(section);
 380     else
 381         return KeywordSearch(section);
 382 }
 383
 384 bool
 385 wxExtHelpController::DisplayBlock(long blockNo)
 386 {
 387    return DisplaySection((int)blockNo);
 388 }
 389
 390 bool
 391 wxExtHelpController::KeywordSearch(const wxString& k,
 392                                    wxHelpSearchMode WXUNUSED(mode))
 393 {
 394    if(! m_NumOfEntries)
 395       return false;
 396
 397    wxString     *choices = new wxString[m_NumOfEntries];
 398    wxString     *urls = new wxString[m_NumOfEntries];
 399    wxString compA, compB;
 400
 401    int          idx = 0, j;
 402    bool         rc;
 403    bool         showAll = k.empty();
 404    wxList::compatibility_iterator node = m_MapList->GetFirst();
 405    wxExtHelpMapEntry *entry;
 406
 407    {
 408       wxBusyCursor b; // display a busy cursor
 409       compA = k; compA.LowerCase(); // we compare case insensitive
 410       while(node)
 411       {
 412          entry = (wxExtHelpMapEntry *)node->GetData();
 413          compB = entry->doc; compB.LowerCase();
 414          if((showAll || compB.Contains(k)) && ! compB.empty())
 415          {
 416             urls[idx] = entry->url;
 417             // doesn't work:
 418             // choices[idx] = (**i).doc.Contains((**i).doc.Before(WXEXTHELP_COMMENTCHAR));
 419             //if(choices[idx].empty()) // didn't contain the ';'
 420             //   choices[idx] = (**i).doc;
 421             choices[idx] = wxEmptyString;
 422             for(j=0;entry->doc.c_str()[j]
 423                    && entry->doc.c_str()[j] != WXEXTHELP_COMMENTCHAR; j++)
 424                choices[idx] << entry->doc.c_str()[j];
 425             idx++;
 426          }
 427          node = node->GetNext();
 428       }
 429    }
 430
 431    if(idx == 1)
 432       rc = DisplayHelp(urls[0]);
 433    else if(idx == 0)
 434    {
 435       wxMessageBox(_("No entries found."));
 436       rc = false;
 437    }
 438    else
 439    {
 440       idx = wxGetSingleChoiceIndex(showAll ? _("Help Index") : _("Relevant entries:"),
 441                                    showAll ? _("Help Index") : _("Entries found"),
 442                                    idx,choices);
 443       if(idx != -1)
 444          rc = DisplayHelp(urls[idx]);
 445       else
 446          rc = false;
 447    }
 448    delete[] urls;
 449    delete[] choices;
 450
 451    return rc;
 452 }
 453
 454
 455 bool wxExtHelpController::Quit()
 456 {
 457    return true;
 458 }
 459
 460 void wxExtHelpController::OnQuit()
 461 {
 462 }
 463
 464
 465 #endif // wxUSE_HELP