interface/wx/generic/helpext.h

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