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 dir
  65             directory name where to fine the help files
  66
  67         @return @true on success
  68     */
  69     virtual bool Initialize(const wxString& dir);
  70
  71     /**
  72         If file is "", reloads file given in Initialize.
  73
  74         @param file
  75             Name of help directory.
  76
  77         @return @true on success
  78     */
  79     virtual bool LoadFile(const wxString& file = wxEmptyString);
  80
  81     /**
  82         Display list of all help entries.
  83
  84         @return @true on success
  85     */
  86     virtual bool DisplayContents(void);
  87
  88     /**
  89         Display help for id sectionNo.
  90
  91         @return @true on success
  92     */
  93     virtual bool DisplaySection(int sectionNo);
  94
  95     /**
  96         Display help for id sectionNo -- identical with DisplaySection().
  97
  98         @return @true on success
  99     */
 100     virtual bool DisplaySection(const wxString& section);
 101
 102     /**
 103         Display help for URL (using DisplayHelp) or keyword (using KeywordSearch)
 104
 105         @return @true on success
 106     */
 107     virtual bool DisplayBlock(long blockNo);
 108
 109     /**
 110         Search comment/documentation fields in map file and present a
 111         list to chose from.
 112
 113         @param k
 114             string to search for, empty string will list all entries
 115
 116         @param mode
 117             optional parameter allows the search the index (wxHELP_SEARCH_INDEX)
 118             but this currently only supported by the wxHtmlHelpController.
 119
 120         @return @true on success
 121     */
 122     virtual bool KeywordSearch(const wxString& k,
 123                                 wxHelpSearchMode mode = wxHELP_SEARCH_ALL);
 124
 125     /**
 126         Does nothing.
 127     */
 128     virtual bool Quit();
 129
 130     /**
 131         Does nothing.
 132     */
 133     virtual void OnQuit();
 134
 135     /**
 136         Call the browser using a relative URL.
 137     */
 138     virtual bool DisplayHelp(const wxString &) ;
 139
 140     /**
 141         Allows one to override the default settings for the help frame.
 142     */
 143     virtual void SetFrameParameters(const wxString& title,
 144                                     const wxSize& size,
 145                                     const wxPoint& pos = wxDefaultPosition,
 146                                     bool newFrameEachTime = false);
 147
 148     /**
 149         Obtains the latest settings used by the help frame and the help frame.
 150     */
 151     virtual wxFrame *GetFrameParameters(wxSize *size = NULL,
 152                                         wxPoint *pos = NULL,
 153                                         bool *newFrameEachTime = NULL);
 154 };
 155