src/generic/helpext.cpp

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        helpext.cpp
   3 // Purpose:     an external help controller for wxWindows
   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 #ifdef __GNUG__
  13 #   pragma implementation "wxexthlp.h"
  14 #endif
  15
  16 #include "wx/wxprec.h"
  17
  18 #ifdef __BORLANDC__
  19     #pragma hdrstop
  20 #endif
  21
  22 #if wxUSE_HELP
  23
  24 #ifndef WX_PRECOMP
  25     #include "wx/setup.h"
  26     #include "wx/string.h"
  27     #include "wx/utils.h"
  28     #include "wx/list.h"
  29     #include "wx/intl.h"
  30 #endif
  31
  32 #include "wx/helpbase.h"
  33 #include "wx/generic/helpext.h"
  34
  35 #include <stdio.h>
  36 #include <ctype.h>
  37 #include <sys/stat.h>
  38
  39 #if !defined(__WINDOWS__) && !defined(__OS2__)
  40     #include   <unistd.h>
  41 #endif
  42
  43 #ifdef __WXMSW__
  44 #include <windows.h>
  45 #endif
  46
  47 // ----------------------------------------------------------------------------
  48 // constants
  49 // ----------------------------------------------------------------------------
  50
  51 /// Name for map file.
  52 #define WXEXTHELP_MAPFILE   _T("wxhelp.map")
  53 /// Maximum line length in map file.
  54 #define WXEXTHELP_BUFLEN 512
  55 /// Character introducing comments/documentation field in map file.
  56 #define WXEXTHELP_COMMENTCHAR   ';'
  57
  58 #define CONTENTS_ID   0
  59
  60 IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase)
  61
  62 /// Name of environment variable to set help browser.
  63 #define   WXEXTHELP_ENVVAR_BROWSER   wxT("WX_HELPBROWSER")
  64 /// Is browser a netscape browser?
  65 #define   WXEXTHELP_ENVVAR_BROWSERISNETSCAPE wxT("WX_HELPBROWSER_NS")
  66
  67 /**
  68    This class implements help via an external browser.
  69    It requires the name of a directory containing the documentation
  70    and a file mapping numerical Section numbers to relative URLS.
  71 */
  72
  73 wxExtHelpController::wxExtHelpController()
  74 {
  75    m_MapList = (wxList*) NULL;
  76    m_NumOfEntries = 0;
  77    m_BrowserName = WXEXTHELP_DEFAULTBROWSER;
  78    m_BrowserIsNetscape = WXEXTHELP_DEFAULTBROWSER_IS_NETSCAPE;
  79
  80    wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER);
  81    if(browser)
  82    {
  83       m_BrowserName = browser;
  84       browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE);
  85       m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0);
  86    }
  87 }
  88
  89 wxExtHelpController::~wxExtHelpController()
  90 {
  91    DeleteList();
  92 }
  93
  94 void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscape)
  95 {
  96    m_BrowserName = browsername;
  97    m_BrowserIsNetscape = isNetscape;
  98 }
  99
 100 // Set viewer: new, generic name for SetBrowser
 101 void wxExtHelpController::SetViewer(const wxString& viewer, long flags)
 102 {
 103     SetBrowser(viewer, ((flags & wxHELP_NETSCAPE) == wxHELP_NETSCAPE));
 104 }
 105
 106 bool
 107 wxExtHelpController::DisplayHelp(const wxString &relativeURL)
 108 {
 109    wxBusyCursor b; // display a busy cursor
 110
 111
 112 #if defined(__WXMSW__)
 113    wxString url;
 114    url << m_MapFile << '\\' << relativeURL.BeforeFirst('#');
 115    bool bOk = (int)ShellExecute(NULL, wxT("open"), url.c_str(),
 116                                 NULL, NULL, SW_SHOWNORMAL ) > 32;
 117    if ( !bOk )
 118    {
 119       wxLogSysError(_("Cannot open URL '%s'"), relativeURL.c_str());
 120       return false;
 121    }
 122    else
 123       return true;
 124
 125 #elif  defined(__WXPM__)
 126
 127    wxString url;
 128    url << m_MapFile << '\\' << relativeURL.BeforeFirst('#');
 129 //   will have to fix for OS/2, later.....DW
 130 //   bool bOk = (int)ShellExecute(NULL, "open", url,
 131 //                                NULL, NULL, SW_SHOWNORMAL ) > 32;
 132 //   if ( !bOk )
 133 //   {
 134 //      wxLogSysError(_("Cannot open URL '%s'"), relativeURL.c_str());
 135 //      return false;
 136 //   }
 137 //   else
 138       return TRUE;
 139
 140 #elif defined(__DOS__)
 141
 142    wxString command;
 143    command = m_BrowserName;
 144    command << wxT(" file://")
 145            << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL;
 146    return wxExecute(command) != 0;
 147
 148 #else // UNIX
 149    wxString command;
 150
 151 #ifndef __EMX__
 152    if(m_BrowserIsNetscape) // try re-loading first
 153    {
 154       wxString lockfile;
 155       wxGetHomeDir(&lockfile);
 156 #ifdef __VMS__
 157       lockfile << WXEXTHELP_SEPARATOR << wxT(".netscape]lock.");
 158       struct stat statbuf;
 159       if(stat(lockfile.fn_str(), &statbuf) == 0)
 160 #else
 161       lockfile << WXEXTHELP_SEPARATOR << wxT(".netscape/lock");
 162       struct stat statbuf;
 163       if(lstat(lockfile.fn_str(), &statbuf) == 0)
 164       // cannot use wxFileExists, because it's a link pointing to a
 165       // non-existing location      if(wxFileExists(lockfile))
 166 #endif
 167       {
 168          long success;
 169          command << m_BrowserName << wxT(" -remote openURL(")
 170                  << wxT("file://") << m_MapFile
 171                  << WXEXTHELP_SEPARATOR << relativeURL << wxT(")");
 172          success = wxExecute(command);
 173          if(success != 0 ) // returns PID on success
 174             return TRUE;
 175       }
 176    }
 177 #endif
 178    command = m_BrowserName;
 179    command << wxT(" file://")
 180            << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL;
 181    return wxExecute(command) != 0;
 182 #endif
 183 }
 184
 185 class wxExtHelpMapEntry : public wxObject
 186 {
 187 public:
 188    int      id;
 189    wxString url;
 190    wxString doc;
 191    wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
 192       { id = iid; url = iurl; doc = idoc; }
 193 };
 194
 195 void wxExtHelpController::DeleteList()
 196 {
 197    if(m_MapList)
 198    {
 199       wxNode *node = m_MapList->GetFirst();
 200       while (node)
 201       {
 202          delete (wxExtHelpMapEntry *)node->GetData();
 203          delete node;
 204          node = m_MapList->GetFirst();
 205       }
 206       delete m_MapList;
 207       m_MapList = (wxList*) NULL;
 208    }
 209 }
 210
 211 /** This must be called to tell the controller where to find the
 212     documentation.
 213     @param file - NOT a filename, but a directory name.
 214     @return true on success
 215 */
 216 bool
 217 wxExtHelpController::Initialize(const wxString& file)
 218 {
 219    return LoadFile(file);
 220 }
 221
 222
 223 // ifile is the name of the base help directory
 224 bool wxExtHelpController::LoadFile(const wxString& ifile)
 225 {
 226    wxString mapFile, file, url, doc;
 227    int id,i,len;
 228    char buffer[WXEXTHELP_BUFLEN];
 229
 230    wxBusyCursor b; // display a busy cursor
 231
 232    if(! ifile.IsEmpty())
 233    {
 234       file = ifile;
 235       if(! wxIsAbsolutePath(file))
 236       {
 237          wxChar* f = wxGetWorkingDirectory();
 238          file = f;
 239          delete[] f; // wxGetWorkingDirectory returns new memory
 240 #ifdef __WXMAC__
 241          file << ifile;
 242 #else
 243          file << WXEXTHELP_SEPARATOR << ifile;
 244 #endif
 245       }
 246       else
 247          file = ifile;
 248
 249 #if wxUSE_INTL
 250       // If a locale is set, look in file/localename, i.e.
 251       // If passed "/usr/local/myapp/help" and the current wxLocale is
 252       // set to be "de", then look in "/usr/local/myapp/help/de/"
 253       // first and fall back to "/usr/local/myapp/help" if that
 254       // doesn't exist.
 255       if(wxGetLocale() && !wxGetLocale()->GetName().IsEmpty())
 256       {
 257          wxString newfile;
 258          newfile << WXEXTHELP_SEPARATOR << wxGetLocale()->GetName();
 259          if(wxDirExists(newfile))
 260             file = newfile;
 261          else
 262          {
 263             newfile = WXEXTHELP_SEPARATOR;
 264             const wxChar *cptr = wxGetLocale()->GetName().c_str();
 265             while(*cptr && *cptr != wxT('_'))
 266                newfile << *(cptr++);
 267             if(wxDirExists(newfile))
 268                file = newfile;
 269          }
 270       }
 271 #endif
 272
 273       if(! wxDirExists(file))
 274          return FALSE;
 275
 276       mapFile << file << WXEXTHELP_SEPARATOR << WXEXTHELP_MAPFILE;
 277    }
 278    else // try to reload old file
 279       mapFile = m_MapFile;
 280
 281    if(! wxFileExists(mapFile))
 282       return FALSE;
 283
 284    DeleteList();
 285    m_MapList = new wxList;
 286    m_NumOfEntries = 0;
 287
 288    FILE *input = wxFopen(mapFile,wxT("rt"));
 289    if(! input)
 290       return FALSE;
 291    do
 292    {
 293       if(fgets(buffer,WXEXTHELP_BUFLEN,input) && *buffer != WXEXTHELP_COMMENTCHAR)
 294       {
 295          len = strlen(buffer);
 296          if(buffer[len-1] == '\n')
 297             buffer[len-1] = '\0'; // cut of trailing newline
 298          if(sscanf(buffer,"%d", &id) != 1)
 299             break; // error
 300          for(i=0; isdigit(buffer[i])||isspace(buffer[i])||buffer[i]=='-'; i++)
 301             ; // find begin of URL
 302          url = wxT("");
 303          while(buffer[i] && ! isspace(buffer[i]) && buffer[i] !=
 304                WXEXTHELP_COMMENTCHAR)
 305             url << (wxChar) buffer[i++];
 306          while(buffer[i] && buffer[i] != WXEXTHELP_COMMENTCHAR)
 307             i++;
 308          doc = wxT("");
 309          if(buffer[i])
 310             doc = wxString::FromAscii( (buffer + i + 1) ); // skip the comment character
 311          m_MapList->Append(new wxExtHelpMapEntry(id,url,doc));
 312          m_NumOfEntries++;
 313       }
 314    }while(! feof(input));
 315    fclose(input);
 316
 317    m_MapFile = file; // now it's valid
 318    return TRUE;
 319 }
 320
 321
 322 bool
 323 wxExtHelpController::DisplayContents()
 324 {
 325    if(! m_NumOfEntries)
 326       return FALSE;
 327
 328    wxString contents;
 329    wxNode *node = m_MapList->GetFirst();
 330    wxExtHelpMapEntry *entry;
 331    while(node)
 332    {
 333       entry = (wxExtHelpMapEntry *)node->GetData();
 334       if(entry->id == CONTENTS_ID)
 335       {
 336          contents = entry->url;
 337          break;
 338       }
 339       node = node->GetNext();
 340    }
 341
 342    bool rc = FALSE;
 343    wxString file;
 344    file << m_MapFile << WXEXTHELP_SEPARATOR << contents;
 345    if(file.Contains(wxT('#')))
 346       file = file.BeforeLast(wxT('#'));
 347    if(contents.Length() && wxFileExists(file))
 348       rc = DisplaySection(CONTENTS_ID);
 349
 350    // if not found, open homemade toc:
 351    return rc ? TRUE : KeywordSearch(wxT(""));
 352 }
 353
 354 bool
 355 wxExtHelpController::DisplaySection(int sectionNo)
 356 {
 357    if(! m_NumOfEntries)
 358       return FALSE;
 359
 360    wxBusyCursor b; // display a busy cursor
 361    wxNode *node = m_MapList->GetFirst();
 362    wxExtHelpMapEntry *entry;
 363    while(node)
 364    {
 365       entry = (wxExtHelpMapEntry *)node->GetData();
 366       if(entry->id == sectionNo)
 367          return DisplayHelp(entry->url);
 368       node = node->GetNext();
 369    }
 370    return FALSE;
 371 }
 372
 373 bool wxExtHelpController::DisplaySection(const wxString& section)
 374 {
 375     bool isFilename = (section.Find(wxT(".htm")) != -1);
 376
 377     if (isFilename)
 378         return DisplayHelp(section);
 379     else
 380         return KeywordSearch(section);
 381 }
 382
 383 bool
 384 wxExtHelpController::DisplayBlock(long blockNo)
 385 {
 386    return DisplaySection((int)blockNo);
 387 }
 388
 389 bool
 390 wxExtHelpController::KeywordSearch(const wxString& k)
 391 {
 392    if(! m_NumOfEntries)
 393       return FALSE;
 394
 395    wxString     *choices = new wxString[m_NumOfEntries];
 396    wxString     *urls = new wxString[m_NumOfEntries];
 397    wxString compA, compB;
 398
 399    int          idx = 0, j;
 400    bool         rc;
 401    bool         showAll = k.IsEmpty();
 402    wxNode       *node = m_MapList->GetFirst();
 403    wxExtHelpMapEntry *entry;
 404
 405    {
 406       wxBusyCursor b; // display a busy cursor
 407       compA = k; compA.LowerCase(); // we compare case insensitive
 408       while(node)
 409       {
 410          entry = (wxExtHelpMapEntry *)node->GetData();
 411          compB = entry->doc; compB.LowerCase();
 412          if((showAll || compB.Contains(k)) && ! compB.IsEmpty())
 413          {
 414             urls[idx] = entry->url;
 415             // doesn't work:
 416             // choices[idx] = (**i).doc.Contains((**i).doc.Before(WXEXTHELP_COMMENTCHAR));
 417             //if(choices[idx].IsEmpty()) // didn't contain the ';'
 418             //   choices[idx] = (**i).doc;
 419             choices[idx] = wxT("");
 420             for(j=0;entry->doc.c_str()[j]
 421                    && entry->doc.c_str()[j] != WXEXTHELP_COMMENTCHAR; j++)
 422                choices[idx] << entry->doc.c_str()[j];
 423             idx++;
 424          }
 425          node = node->GetNext();
 426       }
 427    }
 428
 429    if(idx == 1)
 430       rc = DisplayHelp(urls[0]);
 431    else if(idx == 0)
 432    {
 433       wxMessageBox(_("No entries found."));
 434       rc = FALSE;
 435    }
 436    else
 437    {
 438       idx = wxGetSingleChoiceIndex(showAll ? _("Help Index") : _("Relevant entries:"),
 439                                    showAll ? _("Help Index") : _("Entries found"),
 440                                    idx,choices);
 441       if(idx != -1)
 442          rc = DisplayHelp(urls[idx]);
 443       else
 444          rc = FALSE;
 445    }
 446    delete[] urls;
 447    delete[] choices;
 448
 449    return rc;
 450 }
 451
 452
 453 bool wxExtHelpController::Quit()
 454 {
 455    return TRUE;
 456 }
 457
 458 void wxExtHelpController::OnQuit()
 459 {
 460 }
 461
 462
 463 #endif // wxUSE_HELP
 464