Doc tweaks

[wxWidgets.git] / src / generic / helpext.cpp

diff --git a/src/generic/helpext.cpp b/src/generic/helpext.cpp
index a785361d421b481afcd2cae3ded002e5b77ec33c..30e80e68507ec626297abbf26b310ed06f3ec2b8 100644 (file)
--- a/src/generic/helpext.cpp
+++ b/src/generic/helpext.cpp
@@ -1,95 +1,213 @@
-/*-*- c++ -*-********************************************************
- * wxexthlp.cpp - an external help controller for wxWindows         *
- *                                                                  *
- * (C) 1998 by Karsten Ballüder (Ballueder@usa.net)                 *
- *                                                                  *
- * $Id$
- *******************************************************************/
-#ifdef __GNUG__
+/////////////////////////////////////////////////////////////////////////////
+// Name:        helpext.cpp
+// Purpose:     an external help controller for wxWidgets
+// Author:      Karsten Ballueder
+// Modified by:
+// Created:     04/01/98
+// RCS-ID:      $Id$
+// Copyright:   (c) Karsten Ballueder
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)

 #   pragma implementation "wxexthlp.h"
 #endif
 
 #   pragma implementation "wxexthlp.h"
 #endif
 

-#include   "wx/setup.h"
-#include   "wx/helpbase.h"
-#include   "wx/generic/helpext.h"
-#include   "wx/string.h"
-#include   "wx/utils.h"
-#include   "wx/list.h"
-#include   <stdio.h>
-#include   <ctype.h>
-#include   <sys/stat.h>
-#include   <unistd.h>
+#include "wx/wxprec.h"

 
 

+#ifdef __BORLANDC__
+    #pragma hdrstop
+#endif

 
 

+#if wxUSE_HELP && !defined(__WXWINCE__)

 
 

-class wxExtHelpMapEntry : public wxObject
-{
-public:
-   int      id;
-   wxString url;
-   wxString doc;
-   wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
-      { id = iid; url = iurl; doc = idoc; }
-};
+#ifndef WX_PRECOMP
+    #include "wx/setup.h"
+    #include "wx/string.h"
+    #include "wx/utils.h"
+    #include "wx/list.h"
+    #include "wx/intl.h"
+    #include "wx/msgdlg.h"
+    #include "wx/choicdlg.h"
+    #include "wx/log.h"
+#endif

 
 

+#include "wx/helpbase.h"
+#include "wx/generic/helpext.h"

 
 

-struct wxBusyCursor
-{
-   wxBusyCursor() { wxBeginBusyCursor(); }
-   ~wxBusyCursor() { wxEndBusyCursor(); }
-};
+#include <stdio.h>
+#include <ctype.h>
+#include <sys/stat.h>
+
+#if !defined(__WINDOWS__) && !defined(__OS2__)
+    #include   <unistd.h>
+#endif
+
+#ifdef __WXMSW__
+#include <windows.h>
+#endif
+
+// ----------------------------------------------------------------------------
+// constants
+// ----------------------------------------------------------------------------
+
+/// Name for map file.
+#define WXEXTHELP_MAPFILE   _T("wxhelp.map")
+/// Maximum line length in map file.
+#define WXEXTHELP_BUFLEN 512
+/// Character introducing comments/documentation field in map file.
+#define WXEXTHELP_COMMENTCHAR   ';'
+
+#define CONTENTS_ID   0

 
 IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase)
 
 IMPLEMENT_CLASS(wxExtHelpController, wxHelpControllerBase)

-   
+
+/// Name of environment variable to set help browser.
+#define   WXEXTHELP_ENVVAR_BROWSER   wxT("WX_HELPBROWSER")
+/// Is browser a netscape browser?
+#define   WXEXTHELP_ENVVAR_BROWSERISNETSCAPE wxT("WX_HELPBROWSER_NS")
+

 /**
    This class implements help via an external browser.
    It requires the name of a directory containing the documentation
    and a file mapping numerical Section numbers to relative URLS.
 */
 
 /**
    This class implements help via an external browser.
    It requires the name of a directory containing the documentation
    and a file mapping numerical Section numbers to relative URLS.
 */
 

-wxExtHelpController::wxExtHelpController(void)
+wxExtHelpController::wxExtHelpController()

 {
 {

-   m_MapList = NULL;
+   m_MapList = (wxList*) NULL;
+   m_NumOfEntries = 0;

    m_BrowserName = WXEXTHELP_DEFAULTBROWSER;
    m_BrowserIsNetscape = WXEXTHELP_DEFAULTBROWSER_IS_NETSCAPE;
    m_BrowserName = WXEXTHELP_DEFAULTBROWSER;
    m_BrowserIsNetscape = WXEXTHELP_DEFAULTBROWSER_IS_NETSCAPE;

-   m_NumOfEntries = 0;

 
 

-   char *browser = getenv(WXEXTHELP_ENVVAR_BROWSER);
+   wxChar *browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSER);

    if(browser)
    {
       m_BrowserName = browser;
    if(browser)
    {
       m_BrowserName = browser;

-      browser = getenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE);
-      m_BrowserIsNetscape = browser && (atoi(browser) != 0);
+      browser = wxGetenv(WXEXTHELP_ENVVAR_BROWSERISNETSCAPE);
+      m_BrowserIsNetscape = browser && (wxAtoi(browser) != 0);

    }
 }
 
    }
 }
 

-void
-wxExtHelpController::DeleteList(void)
+wxExtHelpController::~wxExtHelpController()

 {
 {

-   if(m_MapList)
+   DeleteList();
+}
+
+void wxExtHelpController::SetBrowser(const wxString& browsername, bool isNetscape)
+{
+   m_BrowserName = browsername;
+   m_BrowserIsNetscape = isNetscape;
+}
+
+// Set viewer: new, generic name for SetBrowser
+void wxExtHelpController::SetViewer(const wxString& viewer, long flags)
+{
+    SetBrowser(viewer, ((flags & wxHELP_NETSCAPE) == wxHELP_NETSCAPE));
+}
+
+bool
+wxExtHelpController::DisplayHelp(const wxString &relativeURL)
+{
+   wxBusyCursor b; // display a busy cursor
+
+
+#if defined(__WXMSW__)
+   wxString url;
+   url << m_MapFile << '\\' << relativeURL.BeforeFirst('#');
+   bool bOk = (int)ShellExecute(NULL, wxT("open"), url.c_str(),
+                                NULL, NULL, SW_SHOWNORMAL ) > 32;
+   if ( !bOk )

    {
    {

-      wxNode *node = m_MapList->First();
-      while (node)
+      wxLogSysError(_("Cannot open URL '%s'"), relativeURL.c_str());
+      return false;
+   }
+
+   return true;
+#elif  defined(__WXPM__)
+
+   wxString url;
+   url << m_MapFile << '\\' << relativeURL.BeforeFirst('#');
+//   will have to fix for OS/2, later.....DW
+//   bool bOk = (int)ShellExecute(NULL, "open", url,
+//                                NULL, NULL, SW_SHOWNORMAL ) > 32;
+//   if ( !bOk )
+//   {
+//      wxLogSysError(_("Cannot open URL '%s'"), relativeURL.c_str());
+//      return false;
+//   }
+//   else
+      return true;
+
+#elif defined(__DOS__)
+
+   wxString command;
+   command = m_BrowserName;
+   command << wxT(" file://")
+           << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL;
+   return wxExecute(command) != 0;
+
+#else // UNIX
+   wxString command;
+
+#ifndef __EMX__
+   if(m_BrowserIsNetscape) // try re-loading first
+   {
+      wxString lockfile;
+      wxGetHomeDir(&lockfile);
+#ifdef __VMS__
+      lockfile << WXEXTHELP_SEPARATOR << wxT(".netscape]lock.");
+      struct stat statbuf;
+      if(stat(lockfile.fn_str(), &statbuf) == 0)
+#else
+      lockfile << WXEXTHELP_SEPARATOR << wxT(".netscape/lock");
+      struct stat statbuf;
+      if(lstat(lockfile.fn_str(), &statbuf) == 0)
+      // cannot use wxFileExists, because it's a link pointing to a
+      // non-existing location      if(wxFileExists(lockfile))
+#endif

       {
       {

-         delete (wxExtHelpMapEntry *)node->Data();
-         delete node;
-         node = m_MapList->First();
+         long success;
+         command << m_BrowserName << wxT(" -remote openURL(")
+                 << wxT("file://") << m_MapFile
+                 << WXEXTHELP_SEPARATOR << relativeURL << wxT(")");
+         success = wxExecute(command);
+         if(success != 0 ) // returns PID on success
+            return true;

       }
       }

-      delete m_MapList;
-      m_MapList = NULL;

    }
    }

+#endif
+   command = m_BrowserName;
+   command << wxT(" file://")
+           << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL;
+   return wxExecute(command) != 0;
+#endif

 }
 
 }
 

-wxExtHelpController::~wxExtHelpController(void)
+class wxExtHelpMapEntry : public wxObject

 {
 {

-   DeleteList();
-}
+public:
+   int      id;
+   wxString url;
+   wxString doc;
+   wxExtHelpMapEntry(int iid, wxString const &iurl, wxString const &idoc)
+      { id = iid; url = iurl; doc = idoc; }
+};

 
 

-void
-wxExtHelpController::SetBrowser(wxString const & browsername, bool isNetscape)
+void wxExtHelpController::DeleteList()

 {
 {

-   m_BrowserName = browsername;
-   m_BrowserIsNetscape = isNetscape;
+   if(m_MapList)
+   {
+      wxList::compatibility_iterator node = m_MapList->GetFirst();
+      while (node)
+      {
+         delete (wxExtHelpMapEntry *)node->GetData();
+         m_MapList->Erase(node);
+         node = m_MapList->GetFirst();
+      }
+      delete m_MapList;
+      m_MapList = (wxList*) NULL;
+   }

 }
 
 /** This must be called to tell the controller where to find the
 }
 
 /** This must be called to tell the controller where to find the


@@ -103,32 +221,60 @@ wxExtHelpController::Initialize(const wxString& file)
    return LoadFile(file);
 }
 
    return LoadFile(file);
 }
 

-  
-bool
-wxExtHelpController::LoadFile(const wxString& ifile)
+
+// ifile is the name of the base help directory
+bool wxExtHelpController::LoadFile(const wxString& ifile)

 {
    wxString mapFile, file, url, doc;
    int id,i,len;
    char buffer[WXEXTHELP_BUFLEN];
 {
    wxString mapFile, file, url, doc;
    int id,i,len;
    char buffer[WXEXTHELP_BUFLEN];

-   
+

    wxBusyCursor b; // display a busy cursor
 
    wxBusyCursor b; // display a busy cursor
 

-   if(! ifile.IsEmpty())
+   if(! ifile.empty())

    {
       file = ifile;
       if(! wxIsAbsolutePath(file))
       {
    {
       file = ifile;
       if(! wxIsAbsolutePath(file))
       {

-         char* f = wxGetWorkingDirectory();
+         wxChar* f = wxGetWorkingDirectory();

          file = f;
          delete[] f; // wxGetWorkingDirectory returns new memory
          file = f;
          delete[] f; // wxGetWorkingDirectory returns new memory

+#ifdef __WXMAC__
+         file << ifile;
+#else

          file << WXEXTHELP_SEPARATOR << ifile;
          file << WXEXTHELP_SEPARATOR << ifile;

+#endif

       }
       else
          file = ifile;
       }
       else
          file = ifile;

-   
+
+#if wxUSE_INTL
+      // If a locale is set, look in file/localename, i.e.
+      // If passed "/usr/local/myapp/help" and the current wxLocale is
+      // set to be "de", then look in "/usr/local/myapp/help/de/"
+      // first and fall back to "/usr/local/myapp/help" if that
+      // doesn't exist.
+      if(wxGetLocale() && !wxGetLocale()->GetName().empty())
+      {
+         wxString newfile;
+         newfile << WXEXTHELP_SEPARATOR << wxGetLocale()->GetName();
+         if(wxDirExists(newfile))
+            file = newfile;
+         else
+         {
+            newfile = WXEXTHELP_SEPARATOR;
+            const wxChar *cptr = wxGetLocale()->GetName().c_str();
+            while(*cptr && *cptr != wxT('_'))
+               newfile << *(cptr++);
+            if(wxDirExists(newfile))
+               file = newfile;
+         }
+      }
+#endif
+

       if(! wxDirExists(file))
          return false;
       if(! wxDirExists(file))
          return false;

-      
+

       mapFile << file << WXEXTHELP_SEPARATOR << WXEXTHELP_MAPFILE;
    }
    else // try to reload old file
       mapFile << file << WXEXTHELP_SEPARATOR << WXEXTHELP_MAPFILE;
    }
    else // try to reload old file


@@ -140,8 +286,8 @@ wxExtHelpController::LoadFile(const wxString& ifile)
    DeleteList();
    m_MapList = new wxList;
    m_NumOfEntries = 0;
    DeleteList();
    m_MapList = new wxList;
    m_NumOfEntries = 0;

-   
-   FILE *input = fopen(mapFile.c_str(),"rt");
+
+   FILE *input = wxFopen(mapFile,wxT("rt"));

    if(! input)
       return false;
    do
    if(! input)
       return false;
    do


@@ -155,65 +301,58 @@ wxExtHelpController::LoadFile(const wxString& ifile)
             break; // error
          for(i=0; isdigit(buffer[i])||isspace(buffer[i])||buffer[i]=='-'; i++)
             ; // find begin of URL
             break; // error
          for(i=0; isdigit(buffer[i])||isspace(buffer[i])||buffer[i]=='-'; i++)
             ; // find begin of URL

-         url = "";
+         url = wxEmptyString;

          while(buffer[i] && ! isspace(buffer[i]) && buffer[i] !=
                WXEXTHELP_COMMENTCHAR)
          while(buffer[i] && ! isspace(buffer[i]) && buffer[i] !=
                WXEXTHELP_COMMENTCHAR)

-            url << buffer[i++];
+            url << (wxChar) buffer[i++];

          while(buffer[i] && buffer[i] != WXEXTHELP_COMMENTCHAR)
             i++;
          while(buffer[i] && buffer[i] != WXEXTHELP_COMMENTCHAR)
             i++;

-         doc = "";
+         doc = wxEmptyString;

          if(buffer[i])
          if(buffer[i])

-            doc = (buffer + i + 1); // skip the comment character
+            doc = wxString::FromAscii( (buffer + i + 1) ); // skip the comment character

          m_MapList->Append(new wxExtHelpMapEntry(id,url,doc));
          m_NumOfEntries++;
       }
    }while(! feof(input));
    fclose(input);
          m_MapList->Append(new wxExtHelpMapEntry(id,url,doc));
          m_NumOfEntries++;
       }
    }while(! feof(input));
    fclose(input);

-   
+

    m_MapFile = file; // now it's valid
    return true;
 }
 
    m_MapFile = file; // now it's valid
    return true;
 }
 

+

 bool
 bool

-wxExtHelpController::CallBrowser(wxString const &relativeURL)
+wxExtHelpController::DisplayContents()

 {
 {

-   wxBusyCursor b; // display a busy cursor
-   wxString command;
+   if(! m_NumOfEntries)
+      return false;

 
 

-   if(m_BrowserIsNetscape) // try re-loading first
+   wxString contents;
+   wxList::compatibility_iterator node = m_MapList->GetFirst();
+   wxExtHelpMapEntry *entry;
+   while(node)

    {
    {

-      wxString lockfile;
-      wxGetHomeDir(&lockfile);
-      lockfile << WXEXTHELP_SEPARATOR << ".netscape/lock";
-      struct stat statbuf;
-      if(lstat(lockfile.c_str(), &statbuf) == 0)
-      // cannot use wxFileExists, because it's a link pointing to a
-      // non-existing location      if(wxFileExists(lockfile))
+      entry = (wxExtHelpMapEntry *)node->GetData();
+      if(entry->id == CONTENTS_ID)

       {
       {

-         long success;
-         command << m_BrowserName << " -remote openURL("
-                 << "file://" << m_MapFile
-                 << WXEXTHELP_SEPARATOR << relativeURL << ")"; 
-         success = wxExecute(command);
-         if(success != 0 ) // returns PID on success
-            return true;
+         contents = entry->url;
+         break;

       }
       }

+      node = node->GetNext();

    }
    }

-   command = m_BrowserName;
-   command << " file://"
-           << m_MapFile << WXEXTHELP_SEPARATOR << relativeURL; 
-   return wxExecute(command) != 0; 
-}

 
 

-bool
-wxExtHelpController::DisplayContents(void)
-{
-   if(! m_NumOfEntries)
-      return false;
-   wxBusyCursor b; // display a busy cursor
-   return KeywordSearch("");
+   bool rc = false;
+   wxString file;
+   file << m_MapFile << WXEXTHELP_SEPARATOR << contents;
+   if(file.Contains(wxT('#')))
+      file = file.BeforeLast(wxT('#'));
+   if(contents.Length() && wxFileExists(file))
+      rc = DisplaySection(CONTENTS_ID);
+
+   // if not found, open homemade toc:
+   return rc ? true : KeywordSearch(wxEmptyString);

 }
 }

-      
+

 bool
 wxExtHelpController::DisplaySection(int sectionNo)
 {
 bool
 wxExtHelpController::DisplaySection(int sectionNo)
 {


@@ -221,18 +360,28 @@ wxExtHelpController::DisplaySection(int sectionNo)
       return false;
 
    wxBusyCursor b; // display a busy cursor
       return false;
 
    wxBusyCursor b; // display a busy cursor

-   wxNode *node = m_MapList->First();
+   wxList::compatibility_iterator node = m_MapList->GetFirst();

    wxExtHelpMapEntry *entry;
    while(node)
    {
    wxExtHelpMapEntry *entry;
    while(node)
    {

-      entry = (wxExtHelpMapEntry *)node->Data();
+      entry = (wxExtHelpMapEntry *)node->GetData();

       if(entry->id == sectionNo)
       if(entry->id == sectionNo)

-         return CallBrowser(entry->url);
-      node = node->Next();
+         return DisplayHelp(entry->url);
+      node = node->GetNext();

    }
    return false;
 }
 
    }
    return false;
 }
 

+bool wxExtHelpController::DisplaySection(const wxString& section)
+{
+    bool isFilename = (section.Find(wxT(".htm")) != -1);
+
+    if (isFilename)
+        return DisplayHelp(section);
+    else
+        return KeywordSearch(section);
+}
+

 bool
 wxExtHelpController::DisplayBlock(long blockNo)
 {
 bool
 wxExtHelpController::DisplayBlock(long blockNo)
 {


@@ -240,45 +389,48 @@ wxExtHelpController::DisplayBlock(long blockNo)
 }
 
 bool
 }
 
 bool

-wxExtHelpController::KeywordSearch(const wxString& k)
+wxExtHelpController::KeywordSearch(const wxString& k,
+                                   wxHelpSearchMode WXUNUSED(mode))

 {
    if(! m_NumOfEntries)
       return false;
 
 {
    if(! m_NumOfEntries)
       return false;
 

-   wxBusyCursor b; // display a busy cursor

    wxString     *choices = new wxString[m_NumOfEntries];
    wxString     *urls = new wxString[m_NumOfEntries];
    wxString compA, compB;
    wxString     *choices = new wxString[m_NumOfEntries];
    wxString     *urls = new wxString[m_NumOfEntries];
    wxString compA, compB;

-   
+

    int          idx = 0, j;
    bool         rc;
    int          idx = 0, j;
    bool         rc;

-   bool         showAll = k.IsEmpty();
-   wxNode       *node = m_MapList->First();
+   bool         showAll = k.empty();
+   wxList::compatibility_iterator node = m_MapList->GetFirst();

    wxExtHelpMapEntry *entry;
    wxExtHelpMapEntry *entry;

-   
-   compA = k; compA.LowerCase(); // we compare case insensitive
-   while(node)
+

    {
    {

-      entry = (wxExtHelpMapEntry *)node->Data();
-      compB = entry->doc; compB.LowerCase();
-      if((showAll || compB.Contains(k)) && ! compB.IsEmpty()) 
+      wxBusyCursor b; // display a busy cursor
+      compA = k; compA.LowerCase(); // we compare case insensitive
+      while(node)

       {
       {

-         urls[idx] = entry->url;
-         // doesn't work:
-         // choices[idx] = (**i).doc.Contains((**i).doc.Before(WXEXTHELP_COMMENTCHAR));
-         //if(choices[idx].IsEmpty()) // didn't contain the ';'
-         //   choices[idx] = (**i).doc;
-         choices[idx] = "";
-         for(j=0;entry->doc.c_str()[j]
-                && entry->doc.c_str()[j] != WXEXTHELP_COMMENTCHAR; j++)
-            choices[idx] << entry->doc.c_str()[j];
-         idx++;
+         entry = (wxExtHelpMapEntry *)node->GetData();
+         compB = entry->doc; compB.LowerCase();
+         if((showAll || compB.Contains(k)) && ! compB.empty())
+         {
+            urls[idx] = entry->url;
+            // doesn't work:
+            // choices[idx] = (**i).doc.Contains((**i).doc.Before(WXEXTHELP_COMMENTCHAR));
+            //if(choices[idx].empty()) // didn't contain the ';'
+            //   choices[idx] = (**i).doc;
+            choices[idx] = wxEmptyString;
+            for(j=0;entry->doc.c_str()[j]
+                   && entry->doc.c_str()[j] != WXEXTHELP_COMMENTCHAR; j++)
+               choices[idx] << entry->doc.c_str()[j];
+            idx++;
+         }
+         node = node->GetNext();

       }
       }

-      node = node->Next();

    }
 
    if(idx == 1)
    }
 
    if(idx == 1)

-      rc = CallBrowser(urls[0]);
+      rc = DisplayHelp(urls[0]);

    else if(idx == 0)
    {
       wxMessageBox(_("No entries found."));
    else if(idx == 0)
    {
       wxMessageBox(_("No entries found."));


@@ -290,25 +442,26 @@ wxExtHelpController::KeywordSearch(const wxString& k)
                                    showAll ? _("Help Index") : _("Entries found"),
                                    idx,choices);
       if(idx != -1)
                                    showAll ? _("Help Index") : _("Entries found"),
                                    idx,choices);
       if(idx != -1)

-         rc = CallBrowser(urls[idx]);
+         rc = DisplayHelp(urls[idx]);

       else
          rc = false;
    }
    delete[] urls;
    delete[] choices;
       else
          rc = false;
    }
    delete[] urls;
    delete[] choices;

-   
+

    return rc;
 }
 
 
    return rc;
 }
 
 

-bool
-wxExtHelpController::Quit(void)
+bool wxExtHelpController::Quit()

 {
    return true;
 }
 
 {
    return true;
 }
 

-void
-wxExtHelpController::OnQuit(void)
+void wxExtHelpController::OnQuit()

 {
 }
 
 {
 }
 

+
+#endif // wxUSE_HELP
+