include/wx/generic/helphtml.h

   1 /*-*- c++ -*-********************************************************
   2  * helphtml.h - base class for html based help controllers          *
   3  *                                                                  *
   4  * (C) 1999 by Karsten Ballüder (Ballueder@usa.net)                 *
   5  *                                                                  *
   6  * $Id$
   7  *******************************************************************/
   8
   9 #ifndef __WX_HELPHTML_H_
  10 #define __WX_HELPHTML_H_
  11
  12 #if wxUSE_HELP
  13
  14 #ifdef __GNUG__
  15 #   pragma interface "helphtml.h"
  16 #endif
  17
  18 #include "wx/helpbase.h"
  19 #include "wx/frame.h"
  20
  21 /// Name for map file.
  22 #define WXEXTHELP_MAPFILE   "wxhelp.map"
  23 /// Path separator.
  24 #ifdef __WXMSW__
  25 #define WXEXTHELP_SEPARATOR '\\'
  26 #else
  27 #define WXEXTHELP_SEPARATOR '/'
  28 #endif
  29 /// Maximum line length in map file.
  30 #define WXEXTHELP_BUFLEN 512
  31 /// Character introducing comments/documentation field in map file.
  32 #define WXEXTHELP_COMMENTCHAR   ';'
  33
  34 class WXDLLEXPORT wxExtHelpMapList;
  35
  36
  37 /**
  38    This class is the base class for all html help implementations.
  39    It requires the name of a directory containing the documentation
  40    and a file mapping numerical Section numbers to relative URLS.
  41
  42    The map file contains two or three fields per line:
  43    numeric_id  relative_URL  [; comment/documentation]
  44
  45    The numeric_id is the id used to look up the entry in
  46    DisplaySection()/DisplayBlock(). The relative_URL is a filename of
  47    an html file, relative to the help directory. The optional
  48    comment/documentation field (after a ';') is used for keyword
  49    searches, so some meaningful text here does not hurt.
  50    If the documentation itself contains a ';', only the part before
  51    that will be displayed in the listbox, but all of it used for search.
  52
  53    Lines starting with ';' will be ignored.
  54 */
  55
  56 class WXDLLEXPORT wxHTMLHelpControllerBase : public wxHelpControllerBase
  57 {
  58 DECLARE_ABSTRACT_CLASS(wxHTMLHelpControllerBase)
  59    public:
  60    wxHTMLHelpControllerBase(void);
  61    virtual ~wxHTMLHelpControllerBase(void);
  62
  63    /** This must be called to tell the controller where to find the
  64        documentation.
  65        If a locale is set, look in file/localename, i.e.
  66        If passed "/usr/local/myapp/help" and the current wxLocale is
  67        set to be "de", then look in "/usr/local/myapp/help/de/"
  68        first and fall back to "/usr/local/myapp/help" if that
  69        doesn't exist.
  70
  71        @param file - NOT a filename, but a directory name.
  72        @return true on success
  73    */
  74    virtual bool Initialize(const wxString& dir, int WXUNUSED(server))
  75       { return Initialize(dir); }
  76
  77    /** This must be called to tell the controller where to find the
  78        documentation.
  79        If a locale is set, look in file/localename, i.e.
  80        If passed "/usr/local/myapp/help" and the current wxLocale is
  81        set to be "de", then look in "/usr/local/myapp/help/de/"
  82        first and fall back to "/usr/local/myapp/help" if that
  83        doesn't exist.
  84        @param dir - directory name where to fine the help files
  85        @return true on success
  86    */
  87    virtual bool Initialize(const wxString& dir);
  88
  89    /** If file is "", reloads file given in Initialize.
  90        @file Name of help directory.
  91        @return true on success
  92    */
  93    virtual bool LoadFile(const wxString& file = "");
  94
  95    /** Display list of all help entries.
  96        @return true on success
  97    */
  98    virtual bool DisplayContents(void);
  99    /** Display help for id sectionNo.
 100        @return true on success
 101    */
 102    virtual bool DisplaySection(int sectionNo);
 103    /** Display help for id sectionNo -- identical with DisplaySection().
 104        @return true on success
 105    */
 106    virtual bool DisplaySection(const wxString& section);
 107    /** Display help for URL (using DisplayHelp) or keyword (using KeywordSearch)
 108        @return true on success
 109    */
 110    virtual bool DisplayBlock(long blockNo);
 111    /** Search comment/documentation fields in map file and present a
 112        list to chose from.
 113        @key k string to search for, empty string will list all entries
 114        @return true on success
 115    */
 116    virtual bool KeywordSearch(const wxString& k);
 117
 118    /// does nothing
 119    virtual bool Quit(void);
 120    /// does nothing
 121    virtual void OnQuit(void);
 122
 123    /// Call the browser using a relative URL.
 124    virtual bool DisplayHelp(const wxString &) = 0;
 125
 126    /// Allows one to override the default settings for the help frame.
 127    virtual void SetFrameParameters(const wxString& WXUNUSED(title),
 128                                    const wxSize& WXUNUSED(size),
 129                                    const wxPoint& WXUNUSED(pos) = wxDefaultPosition,
 130                                    bool WXUNUSED(newFrameEachTime) = FALSE)
 131       {
 132          // does nothing by default
 133       }
 134    /// Obtains the latest settings used by the help frame and the help
 135    /// frame.
 136    virtual wxFrame *GetFrameParameters(wxSize *WXUNUSED(size) = NULL,
 137                                    wxPoint *WXUNUSED(pos) = NULL,
 138                                    bool *WXUNUSED(newFrameEachTime) = NULL)
 139       {
 140          return (wxFrame*) NULL;// does nothing by default
 141       }
 142
 143  protected:
 144    /// Filename of currently active map file.
 145    wxString         m_MapFile;
 146    /// How many entries do we have in the map file?
 147    int              m_NumOfEntries;
 148    /// A list containing all id,url,documentation triples.
 149    wxList          *m_MapList;
 150    /// Deletes the list and all objects.
 151    void DeleteList(void);
 152 };
 153
 154 #endif // wxUSE_HELP
 155
 156 #endif // __WX_HELPHTML_H_