include/wx/generic/helpext.h

   1 /*-*- c++ -*-********************************************************
   2  * exthlp.h - an external help controller for wxWindows             *
   3  *                                                                  *
   4  * (C) 1998 by Karsten Ballüder (Ballueder@usa.net)                 *
   5  *                                                                  *
   6  * $Id$
   7  *******************************************************************/
   8 #ifndef WXXHELP_H
   9 #define WXXHELP_H
  10
  11 #if wxUSE_HELP
  12
  13 #ifdef __GNUG__
  14 #   pragma interface "wxexthlp.h"
  15 #endif
  16
  17 #include "wx/helpbase.h"
  18
  19 /// Name for map file.
  20 #define WXEXTHELP_MAPFILE   "wxhelp.map"
  21 /// Path separator.
  22 #define WXEXTHELP_SEPARATOR '/'
  23 #ifndef WXEXTHELP_DEFAULTBROWSER
  24 /// Default browser name.
  25 #   define WXEXTHELP_DEFAULTBROWSER "netscape"
  26 /// Is default browse a variant of netscape?
  27 #   define WXEXTHELP_DEFAULTBROWSER_IS_NETSCAPE TRUE
  28 #endif
  29 /// Name of environment variable to set help browser.
  30 #define   WXEXTHELP_ENVVAR_BROWSER   "WX_HELPBROWSER"
  31 /// Is browser a netscape browser?
  32 #define   WXEXTHELP_ENVVAR_BROWSERISNETSCAPE "WX_HELPBROWSER_NS"
  33 /// Maximum line length in map file.
  34 #define WXEXTHELP_BUFLEN 512
  35 /// Character introducing comments/documentation field in map file.
  36 #define WXEXTHELP_COMMENTCHAR   ';'
  37
  38 class wxExtHelpMapList;
  39
  40
  41 /**
  42    This class implements help via an external browser.
  43    It requires the name of a directory containing the documentation
  44    and a file mapping numerical Section numbers to relative URLS.
  45
  46    The map file contains two or three fields per line:
  47    numeric_id  relative_URL  [; comment/documentation]
  48
  49    The numeric_id is the id used to look up the entry in
  50    DisplaySection()/DisplayBlock(). The relative_URL is a filename of
  51    an html file, relative to the help directory. The optional
  52    comment/documentation field (after a ';') is used for keyword
  53    searches, so some meaningful text here does not hurt.
  54    If the documentation itself contains a ';', only the part before
  55    that will be displayed in the listbox, but all of it used for search.
  56
  57    Lines starting with ';' will be ignored.
  58 */
  59
  60 class wxExtHelpController : public wxHelpControllerBase
  61 {
  62 DECLARE_CLASS(wxExtHelpController)
  63    public:
  64    wxExtHelpController(void);
  65    virtual ~wxExtHelpController(void);
  66
  67    /** This must be called to tell the controller where to find the
  68        documentation.
  69        @param file - NOT a filename, but a directory name.
  70        @return true on success
  71    */
  72    virtual bool Initialize(const wxString& file, int WXUNUSED(server))
  73       { return Initialize(file); }
  74
  75    /** This must be called to tell the controller where to find the
  76        documentation.
  77        @param file - NOT a filename, but a directory name.
  78        @return true on success
  79    */
  80    virtual bool Initialize(const wxString& file);
  81
  82    /** If file is "", reloads file given in Initialize.
  83        @file Name of help directory.
  84        @return true on success
  85    */
  86    virtual bool LoadFile(const wxString& file = "");
  87
  88    /** Display list of all help entries.
  89        @return true on success
  90    */
  91    virtual bool DisplayContents(void);
  92    /** Display help for id sectionNo.
  93        @return true on success
  94    */
  95    virtual bool DisplaySection(int sectionNo);
  96    /** Display help for id sectionNo -- identical with DisplaySection().
  97        @return true on success
  98    */
  99    virtual bool DisplayBlock(long blockNo);
 100    /** Search comment/documentation fields in map file and present a
 101        list to chose from.
 102        @key k string to search for, empty string will list all entries
 103        @return true on success
 104    */
 105    virtual bool KeywordSearch(const wxString& k);
 106
 107    /// does nothing
 108    virtual bool Quit(void);
 109    /// does nothing
 110    virtual void OnQuit(void);
 111
 112    /** Tell it which browser to use.
 113        The Netscape support will check whether Netscape is already
 114        running (by looking at the .netscape/lock file in the user's
 115        home directory) and tell it to load the page into the existing
 116        window.
 117        @param browsername The command to call a browser/html viewer.
 118        @param isNetscape Set this to TRUE if the browser is some variant of Netscape.
 119    */
 120    void SetBrowser(wxString const & browsername = WXEXTHELP_DEFAULTBROWSER,
 121                    bool isNetscape = WXEXTHELP_DEFAULTBROWSER_IS_NETSCAPE);
 122  private:
 123    /// Filename of currently active map file.
 124    wxString         m_MapFile;
 125    /// How many entries do we have in the map file?
 126    int              m_NumOfEntries;
 127    /// A list containing all id,url,documentation triples.
 128    wxList          *m_MapList;
 129    /// How to call the html viewer.
 130    wxString         m_BrowserName;
 131    /// Is the viewer a variant of netscape?
 132    bool             m_BrowserIsNetscape;
 133    /// Call the browser using a relative URL.
 134    bool CallBrowser(wxString const &);
 135    /// Deletes the list and all objects.
 136    void DeleteList(void);
 137 };
 138
 139 #endif
 140 #endif