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