src/generic/helpext.cpp

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        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/setup.h"
  22     #include "wx/string.h"
  23     #include "wx/utils.h"
  24     #include "wx/list.h"
  25     #include "wx/intl.h"
  26     #include "wx/msgdlg.h"
  27     #include "wx/choicdlg.h"
  28     #include "wx/log.h"
  29 #endif
  30
  31 #include "wx/helpbase.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 __WXMSW__
  43 #include <windows.h>
  44 #include "wx/msw/winundef.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
 123    return true;
 124 #elif  defined(__WXPM__)
 125
 126    wxString url;
 127    url << m_MapFile << '\\' << relativeURL.BeforeFirst('#');
 128 //   will have to fix for OS/2, later.....DW
 129 //   bool bOk = (int)ShellExecute(NULL, "open", url,
 130 //                                NULL, NULL, SW_SHOWNORMAL ) > 32;
 131 //   if ( !bOk )
 132 //   {
 133 //      wxLogSysError(_("Cannot open URL '%s'"), relativeURL.c_str());
 134 //      return false;
 135 //   }
 136 //   else
 137       return true;
 138
 139 #elif defined(__DOS__)
 140
 141    wxString command;
 142    command = m_BrowserName;
 143    command << wxT(" file://")
 144            << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL;
 145    return wxExecute(command) != 0;
 146
 147 #else // UNIX
 148    wxString command;
 149
 150 #ifndef __EMX__
 151    if(m_BrowserIsNetscape) // try re-loading first
 152    {
 153       wxString lockfile;
 154       wxGetHomeDir(&lockfile);
 155 #ifdef __VMS__
 156       lockfile << WXEXTHELP_SEPARATOR << wxT(".netscape]lock.");
 157       struct stat statbuf;
 158       if(stat(lockfile.fn_str(), &statbuf) == 0)
 159 #else
 160       lockfile << WXEXTHELP_SEPARATOR << wxT(".netscape/lock");
 161       struct stat statbuf;
 162       if(lstat(lockfile.fn_str(), &statbuf) == 0)
 163       // cannot use wxFileExists, because it's a link pointing to a
 164       // non-existing location      if(wxFileExists(lockfile))
 165 #endif
 166       {
 167          long success;
 168          command << m_BrowserName << wxT(" -remote openURL(")
 169                  << wxT("file://") << m_MapFile
 170                  << WXEXTHELP_SEPARATOR << relativeURL << wxT(")");
 171          success = wxExecute(command);
 172          if(success != 0 ) // returns PID on success
 173             return true;
 174       }
 175    }
 176 #endif
 177    command = m_BrowserName;
 178    command << wxT(" file://")
 179            << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL;
 180    return wxExecute(command) != 0;
 181 #endif
 182 }
 183
 184 class wxExtHelpMapEntry : public wxObject
 185 {
 186 public:
 187    int      id;
 188    wxString url;
 189    wxString doc;
 190    wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
 191       { id = iid; url = iurl; doc = idoc; }
 192 };
 193
 194 void wxExtHelpController::DeleteList()
 195 {
 196    if(m_MapList)
 197    {
 198       wxList::compatibility_iterator node = m_MapList->GetFirst();
 199       while (node)
 200       {
 201          delete (wxExtHelpMapEntry *)node->GetData();
 202          m_MapList->Erase(node);
 203          node = m_MapList->GetFirst();
 204       }
 205       delete m_MapList;
 206       m_MapList = (wxList*) NULL;
 207    }
 208 }
 209
 210 /** This must be called to tell the controller where to find the
 211     documentation.
 212     @param file - NOT a filename, but a directory name.
 213     @return true on success
 214 */
 215 bool
 216 wxExtHelpController::Initialize(const wxString& file)
 217 {
 218    return LoadFile(file);
 219 }
 220
 221
 222 // ifile is the name of the base help directory
 223 bool wxExtHelpController::LoadFile(const wxString& ifile)
 224 {
 225    wxString mapFile, file, url, doc;
 226    int id,i,len;
 227    char buffer[WXEXTHELP_BUFLEN];
 228
 229    wxBusyCursor b; // display a busy cursor
 230
 231    if(! ifile.empty())
 232    {
 233       file = ifile;
 234       if(! wxIsAbsolutePath(file))
 235       {
 236          wxChar* f = wxGetWorkingDirectory();
 237          file = f;
 238          delete[] f; // wxGetWorkingDirectory returns new memory
 239 #ifdef __WXMAC__
 240          file << ifile;
 241 #else
 242          file << WXEXTHELP_SEPARATOR << ifile;
 243 #endif
 244       }
 245       else
 246          file = ifile;
 247
 248 #if wxUSE_INTL
 249       // If a locale is set, look in file/localename, i.e.
 250       // If passed "/usr/local/myapp/help" and the current wxLocale is
 251       // set to be "de", then look in "/usr/local/myapp/help/de/"
 252       // first and fall back to "/usr/local/myapp/help" if that
 253       // doesn't exist.
 254       if(wxGetLocale() && !wxGetLocale()->GetName().empty())
 255       {
 256          wxString newfile;
 257          newfile << WXEXTHELP_SEPARATOR << wxGetLocale()->GetName();
 258          if(wxDirExists(newfile))
 259             file = newfile;
 260          else
 261          {
 262             newfile = WXEXTHELP_SEPARATOR;
 263             const wxChar *cptr = wxGetLocale()->GetName().c_str();
 264             while(*cptr && *cptr != wxT('_'))
 265                newfile << *(cptr++);
 266             if(wxDirExists(newfile))
 267                file = newfile;
 268          }
 269       }
 270 #endif
 271
 272       if(! wxDirExists(file))
 273          return false;
 274
 275       mapFile << file << WXEXTHELP_SEPARATOR << WXEXTHELP_MAPFILE;
 276    }
 277    else // try to reload old file
 278       mapFile = m_MapFile;
 279
 280    if(! wxFileExists(mapFile))
 281       return false;
 282
 283    DeleteList();
 284    m_MapList = new wxList;
 285    m_NumOfEntries = 0;
 286
 287    FILE *input = wxFopen(mapFile,wxT("rt"));
 288    if(! input)
 289       return false;
 290    do
 291    {
 292       if(fgets(buffer,WXEXTHELP_BUFLEN,input) && *buffer != WXEXTHELP_COMMENTCHAR)
 293       {
 294          len = strlen(buffer);
 295          if(buffer[len-1] == '\n')
 296             buffer[len-1] = '\0'; // cut of trailing newline
 297          if(sscanf(buffer,"%d", &id) != 1)
 298             break; // error
 299          for(i=0; isdigit(buffer[i])||isspace(buffer[i])||buffer[i]=='-'; i++)
 300             ; // find begin of URL
 301          url = wxEmptyString;
 302          while(buffer[i] && ! isspace(buffer[i]) && buffer[i] !=
 303                WXEXTHELP_COMMENTCHAR)
 304             url << (wxChar) buffer[i++];
 305          while(buffer[i] && buffer[i] != WXEXTHELP_COMMENTCHAR)
 306             i++;
 307          doc = wxEmptyString;
 308          if(buffer[i])
 309             doc = wxString::FromAscii( (buffer + i + 1) ); // skip the comment character
 310          m_MapList->Append(new wxExtHelpMapEntry(id,url,doc));
 311          m_NumOfEntries++;
 312       }
 313    }while(! feof(input));
 314    fclose(input);
 315
 316    m_MapFile = file; // now it's valid
 317    return true;
 318 }
 319
 320
 321 bool
 322 wxExtHelpController::DisplayContents()
 323 {
 324    if(! m_NumOfEntries)
 325       return false;
 326
 327    wxString contents;
 328    wxList::compatibility_iterator node = m_MapList->GetFirst();
 329    wxExtHelpMapEntry *entry;
 330    while(node)
 331    {
 332       entry = (wxExtHelpMapEntry *)node->GetData();
 333       if(entry->id == CONTENTS_ID)
 334       {
 335          contents = entry->url;
 336          break;
 337       }
 338       node = node->GetNext();
 339    }
 340
 341    bool rc = false;
 342    wxString file;
 343    file << m_MapFile << WXEXTHELP_SEPARATOR << contents;
 344    if(file.Contains(wxT('#')))
 345       file = file.BeforeLast(wxT('#'));
 346    if(contents.Length() && wxFileExists(file))
 347       rc = DisplaySection(CONTENTS_ID);
 348
 349    // if not found, open homemade toc:
 350    return rc ? true : KeywordSearch(wxEmptyString);
 351 }
 352
 353 bool
 354 wxExtHelpController::DisplaySection(int sectionNo)
 355 {
 356    if(! m_NumOfEntries)
 357       return false;
 358
 359    wxBusyCursor b; // display a busy cursor
 360    wxList::compatibility_iterator node = m_MapList->GetFirst();
 361    wxExtHelpMapEntry *entry;
 362    while(node)
 363    {
 364       entry = (wxExtHelpMapEntry *)node->GetData();
 365       if(entry->id == sectionNo)
 366          return DisplayHelp(entry->url);
 367       node = node->GetNext();
 368    }
 369    return false;
 370 }
 371
 372 bool wxExtHelpController::DisplaySection(const wxString& section)
 373 {
 374     bool isFilename = (section.Find(wxT(".htm")) != -1);
 375
 376     if (isFilename)
 377         return DisplayHelp(section);
 378     else
 379         return KeywordSearch(section);
 380 }
 381
 382 bool
 383 wxExtHelpController::DisplayBlock(long blockNo)
 384 {
 385    return DisplaySection((int)blockNo);
 386 }
 387
 388 bool
 389 wxExtHelpController::KeywordSearch(const wxString& k,
 390                                    wxHelpSearchMode WXUNUSED(mode))
 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.empty();
 402    wxList::compatibility_iterator 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.empty())
 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].empty()) // didn't contain the ';'
 418             //   choices[idx] = (**i).doc;
 419             choices[idx] = wxEmptyString;
 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