| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: helpext.h |
| 3 | // Purpose: interface of wxExtHelpController |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 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 | |