interface/generic/helpext.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        helpext.h
   3 // Purpose:     interface of wxExtHelpController
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxExtHelpController
  12     @wxheader{help.h}
  13
  14     This class implements help via an external browser.
  15     It requires the name of a directory containing the documentation
  16     and a file mapping numerical Section numbers to relative URLS.
  17
  18     The map file contains two or three fields per line:
  19     numeric_id  relative_URL  [; comment/documentation]
  20
  21     The numeric_id is the id used to look up the entry in
  22     DisplaySection()/DisplayBlock(). The relative_URL is a filename of
  23     an html file, relative to the help directory. The optional
  24     comment/documentation field (after a ';') is used for keyword
  25     searches, so some meaningful text here does not hurt.
  26     If the documentation itself contains a ';', only the part before
  27     that will be displayed in the listbox, but all of it used for search.
  28
  29     Lines starting with ';' will be ignored.
  30
  31     @library{wxadv}
  32     @category{help}
  33
  34     @see wxHelpController
  35 */
  36 class wxExtHelpController : public wxHelpController
  37 {
  38 public:
  39     wxExtHelpController(wxWindow* parentWindow = NULL);
  40     virtual ~wxExtHelpController();
  41
  42     /**
  43         Tell it which browser to use.
  44         The Netscape support will check whether Netscape is already
  45         running (by looking at the .netscape/lock file in the user's
  46         home directory) and tell it to load the page into the existing window.
  47
  48         @param viewer
  49             The command to call a browser/html viewer.
  50         @param flags
  51             Set this to wxHELP_NETSCAPE if the browser is some variant of Netscape.
  52     */
  53     virtual void SetViewer(const wxString& viewer = wxEmptyString,
  54                            long flags = wxHELP_NETSCAPE);
  55
  56     /**
  57         This must be called to tell the controller where to find the
  58         documentation.
  59         If a locale is set, look in file/localename, i.e.
  60         If passed "/usr/local/myapp/help" and the current wxLocale is
  61         set to be "de", then look in "/usr/local/myapp/help/de/"
  62         first and fall back to "/usr/local/myapp/help" if that
  63         doesn't exist.
  64
  65         @param file
  66             NOT a filename, but a directory name.
  67
  68         @return @true on success
  69     */
  70     virtual bool Initialize(const wxString& dir, int server);
  71
  72     /**
  73         This must be called to tell the controller where to find the
  74         documentation.
  75         If a locale is set, look in file/localename, i.e.
  76         If passed "/usr/local/myapp/help" and the current wxLocale is
  77         set to be "de", then look in "/usr/local/myapp/help/de/"
  78         first and fall back to "/usr/local/myapp/help" if that
  79         doesn't exist.
  80
  81         @param dir
  82             directory name where to fine the help files
  83
  84         @return @true on success
  85     */
  86     virtual bool Initialize(const wxString& dir);
  87
  88     /**
  89         If file is "", reloads file given in Initialize.
  90
  91         @param file
  92             Name of help directory.
  93
  94         @return @true on success
  95     */
  96     virtual bool LoadFile(const wxString& file = wxEmptyString);
  97
  98     /**
  99         Display list of all help entries.
 100
 101         @return @true on success
 102     */
 103     virtual bool DisplayContents(void);
 104
 105     /**
 106         Display help for id sectionNo.
 107
 108         @return @true on success
 109     */
 110     virtual bool DisplaySection(int sectionNo);
 111
 112     /**
 113         Display help for id sectionNo -- identical with DisplaySection().
 114
 115         @return @true on success
 116     */
 117     virtual bool DisplaySection(const wxString& section);
 118
 119     /**
 120         Display help for URL (using DisplayHelp) or keyword (using KeywordSearch)
 121
 122         @return @true on success
 123     */
 124     virtual bool DisplayBlock(long blockNo);
 125
 126     /**
 127         Search comment/documentation fields in map file and present a
 128         list to chose from.
 129
 130         @param k
 131             string to search for, empty string will list all entries
 132
 133         @return @true on success
 134     */
 135     virtual bool KeywordSearch(const wxString& k,
 136                                 wxHelpSearchMode mode = wxHELP_SEARCH_ALL);
 137
 138     /**
 139         Does nothing.
 140     */
 141     virtual bool Quit();
 142
 143     /**
 144         Does nothing.
 145     */
 146     virtual void OnQuit();
 147
 148     /**
 149         Call the browser using a relative URL.
 150     */
 151     virtual bool DisplayHelp(const wxString &) ;
 152
 153     /**
 154         Allows one to override the default settings for the help frame.
 155     */
 156     virtual void SetFrameParameters(const wxString& title,
 157                                     const wxSize& size,
 158                                     const wxPoint& pos = wxDefaultPosition,
 159                                     bool newFrameEachTime = false);
 160
 161     /**
 162         Obtains the latest settings used by the help frame and the help frame.
 163     */
 164     virtual wxFrame *GetFrameParameters(wxSize *size = NULL,
 165                                         wxPoint *pos = NULL,
 166                                         bool *newFrameEachTime = NULL);
 167 };
 168