| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: html/helpctrl.h |
| 3 | // Purpose: interface of wxHtmlHelpController |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | @class wxHtmlHelpController |
| 11 | |
| 12 | This help controller provides an easy way of displaying HTML help in your |
| 13 | application (see @sample{html}, test example). |
| 14 | |
| 15 | The help system is based on @b books (see wxHtmlHelpController::AddBook). |
| 16 | A book is a logical section of documentation (for example "User's Guide" or |
| 17 | "Programmer's Guide" or "C++ Reference" or "wxWidgets Reference"). |
| 18 | The help controller can handle as many books as you want. |
| 19 | |
| 20 | Although this class has an API compatible with other wxWidgets help controllers |
| 21 | as documented by wxHelpController, it is recommended that you use the enhanced |
| 22 | capabilities of wxHtmlHelpController's API. |
| 23 | |
| 24 | wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as |
| 25 | its native format. The file format is described in @ref overview_html_helpformats. |
| 26 | The directory @c helpfiles in the @sample{html} contains sample project files. |
| 27 | |
| 28 | Note that the Microsoft's HTML Help Workshop |
| 29 | (http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc) |
| 30 | also runs on other platforms using WINE (http://www.winehq.org/) and it can |
| 31 | be used to create the .hpp, .hhk and .hhc files through a friendly GUI. |
| 32 | The commercial tool HelpBlocks (http://www.helpblocks.com) can also create these files. |
| 33 | |
| 34 | @library{wxhtml} |
| 35 | @category{help,html} |
| 36 | |
| 37 | @see wxBestHelpController, wxHtmlHelpFrame, wxHtmlHelpDialog, |
| 38 | wxHtmlHelpWindow, wxHtmlModalHelp |
| 39 | */ |
| 40 | class wxHtmlHelpController : public wxHelpControllerBase |
| 41 | { |
| 42 | public: |
| 43 | /** |
| 44 | Constructor. |
| 45 | |
| 46 | @param style |
| 47 | This is a combination of these flags: |
| 48 | - wxHF_TOOLBAR: The help window has a toolbar. |
| 49 | - wxHF_FLAT_TOOLBAR: The help window has a toolbar with flat buttons (aka coolbar). |
| 50 | - wxHF_CONTENTS: The help window has a contents panel. |
| 51 | - wxHF_INDEX: The help window has an index panel. |
| 52 | - wxHF_SEARCH: The help window has a search panel. |
| 53 | - wxHF_BOOKMARKS: The help window has bookmarks controls. |
| 54 | - wxHF_OPEN_FILES: Allows user to open arbitrary HTML document. |
| 55 | - wxHF_PRINT: The toolbar contains "print" button. |
| 56 | - wxHF_MERGE_BOOKS: The contents pane does not show book nodes. |
| 57 | All books are merged together and appear as single book to the user. |
| 58 | - wxHF_ICONS_BOOK: All nodes in contents pane have a book icon. |
| 59 | This is how Microsoft's HTML help viewer behaves. |
| 60 | - wxHF_ICONS_FOLDER: Book nodes in contents pane have a book icon, book's |
| 61 | sections have a folder icon. This is the default. |
| 62 | - wxHF_ICONS_BOOK_CHAPTER: Both book nodes and nodes of top-level |
| 63 | sections of a book (i.e. chapters) have a book icon, all other sections |
| 64 | (sections, subsections, ...) have a folder icon. |
| 65 | - wxHF_EMBEDDED: Specifies that the help controller controls an embedded |
| 66 | window of class wxHtmlHelpWindow that should not be destroyed when |
| 67 | the controller is destroyed. |
| 68 | - wxHF_DIALOG: Specifies that the help controller should create a |
| 69 | dialog containing the help window. |
| 70 | - wxHF_FRAME: Specifies that the help controller should create a frame |
| 71 | containing the help window. |
| 72 | This is the default if neither wxHF_DIALOG nor wxHF_EMBEDDED is specified. |
| 73 | - wxHF_MODAL: Specifies that the help controller should create a modal |
| 74 | dialog containing the help window (used with the wxHF_DIALOG style). |
| 75 | - wxHF_DEFAULT_STYLE: wxHF_TOOLBAR | wxHF_CONTENTS | wxHF_INDEX | |
| 76 | wxHF_SEARCH | wxHF_BOOKMARKS | wxHF_PRINT |
| 77 | @param parentWindow |
| 78 | This is an optional window to be used as the parent for the help window. |
| 79 | */ |
| 80 | wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE, |
| 81 | wxWindow* parentWindow = NULL); |
| 82 | wxHtmlHelpController(wxWindow* parentWindow, int style = wxHF_DEFAULT_STYLE); |
| 83 | |
| 84 | |
| 85 | /** |
| 86 | Adds a book (i.e. a @ref overview_html_helpformats ".hhp file"; an HTML Help |
| 87 | Workshop project file) into the list of loaded books. |
| 88 | |
| 89 | This must be called at least once before displaying any help. |
| 90 | @a bookFile or @a bookUrl may be either @c ".hhp" file or a ZIP archive |
| 91 | that contains an arbitrary number of @c ".hhp" files in its top-level |
| 92 | directory. |
| 93 | This ZIP archive must have @c ".zip" or @c ".htb" extension (the latter |
| 94 | stands for "HTML book"). In other words, |
| 95 | @code |
| 96 | AddBook(wxFileName("help.zip")) |
| 97 | @endcode |
| 98 | is possible and is the recommended way. |
| 99 | |
| 100 | @param bookFile |
| 101 | Help book filename. It is recommended to use this prototype |
| 102 | instead of the one taking URL, because it is less error-prone. |
| 103 | @param showWaitMsg |
| 104 | If @true then a decoration-less window with progress message is displayed. |
| 105 | */ |
| 106 | bool AddBook(const wxFileName& bookFile, bool showWaitMsg = false); |
| 107 | |
| 108 | /** |
| 109 | Adds a book (i.e. a @ref overview_html_helpformats ".hhp file"; an HTML Help |
| 110 | Workshop project file) into the list of loaded books. |
| 111 | |
| 112 | See the other overload for additional info. |
| 113 | |
| 114 | @param bookUrl |
| 115 | Help book URL (note that syntax of filename and URL is |
| 116 | different on most platforms). |
| 117 | @param showWaitMsg |
| 118 | If @true then a decoration-less window with progress message is displayed. |
| 119 | */ |
| 120 | bool AddBook(const wxString& bookUrl, bool showWaitMsg = false); |
| 121 | |
| 122 | /** |
| 123 | Displays page @a x. |
| 124 | This is THE important function - it is used to display the help in application. |
| 125 | You can specify the page in many ways: |
| 126 | - as direct filename of HTML document |
| 127 | - as chapter name (from contents) or as a book name |
| 128 | - as some word from index |
| 129 | - even as any word (will be searched) |
| 130 | |
| 131 | Looking for the page runs in these steps: |
| 132 | -# try to locate file named x (if x is for example "doc/howto.htm") |
| 133 | -# try to open starting page of book named x |
| 134 | -# try to find x in contents (if x is for example "How To ...") |
| 135 | -# try to find x in index (if x is for example "How To ...") |
| 136 | -# switch to Search panel and start searching |
| 137 | */ |
| 138 | bool Display(const wxString& x); |
| 139 | |
| 140 | /** |
| 141 | @overload |
| 142 | |
| 143 | This alternative form is used to search help contents by numeric IDs. |
| 144 | */ |
| 145 | bool Display(int id); |
| 146 | |
| 147 | /** |
| 148 | Displays help window and focuses contents panel. |
| 149 | */ |
| 150 | virtual bool DisplayContents(); |
| 151 | |
| 152 | /** |
| 153 | Displays help window and focuses index panel. |
| 154 | */ |
| 155 | bool DisplayIndex(); |
| 156 | |
| 157 | /** |
| 158 | Displays the help window, focuses search panel and starts searching. |
| 159 | Returns @true if the keyword was found. Optionally it searches through the |
| 160 | index (mode = @c wxHELP_SEARCH_INDEX), default the content |
| 161 | (mode = @c wxHELP_SEARCH_ALL). |
| 162 | |
| 163 | @note |
| 164 | KeywordSearch() searches only pages listed in @c ".hhc" file(s). |
| 165 | You should list all pages in the contents file. |
| 166 | */ |
| 167 | virtual bool KeywordSearch(const wxString& keyword, |
| 168 | wxHelpSearchMode mode = wxHELP_SEARCH_ALL); |
| 169 | |
| 170 | /** |
| 171 | Reads the controller's setting (position of window, etc.) |
| 172 | */ |
| 173 | virtual void ReadCustomization(wxConfigBase* cfg, |
| 174 | const wxString& path = wxEmptyString); |
| 175 | |
| 176 | /** |
| 177 | Sets whether the help frame should prevent application from exiting |
| 178 | if it's the only remaining top level window. |
| 179 | |
| 180 | @enable |
| 181 | If @true, the application will not quit unless the help frame is |
| 182 | closed. Default is @false, i.e. the application does exit if only |
| 183 | the help window remains opened. |
| 184 | |
| 185 | @see wxApp::SetExitOnFrameDelete() |
| 186 | |
| 187 | @since 2.9.2 |
| 188 | */ |
| 189 | void SetShouldPreventAppExit(bool enable); |
| 190 | |
| 191 | /** |
| 192 | Sets the path for storing temporary files - cached binary versions of index and |
| 193 | contents files. |
| 194 | |
| 195 | These binary forms are much faster to read. Default value is empty string |
| 196 | (empty string means that no cached data are stored). Note that these files |
| 197 | are @e not deleted when program exits. |
| 198 | |
| 199 | Once created these cached files will be used in all subsequent executions |
| 200 | of your application. If cached files become older than corresponding @c ".hhp" |
| 201 | file (e.g. if you regenerate documentation) it will be refreshed. |
| 202 | */ |
| 203 | void SetTempDir(const wxString& path); |
| 204 | |
| 205 | /** |
| 206 | Sets format of title of the frame. |
| 207 | Must contain exactly one "%s" (for title of displayed HTML page). |
| 208 | */ |
| 209 | void SetTitleFormat(const wxString& format); |
| 210 | |
| 211 | /** |
| 212 | Associates the @a config object with the controller. |
| 213 | |
| 214 | If there is associated config object, wxHtmlHelpController automatically |
| 215 | reads and writes settings (including wxHtmlWindow's settings) when needed. |
| 216 | The only thing you must do is create wxConfig object and call UseConfig(). |
| 217 | |
| 218 | If you do not use UseConfig(), wxHtmlHelpController will use the default |
| 219 | wxConfig object if available (for details see wxConfigBase::Get and |
| 220 | wxConfigBase::Set). |
| 221 | */ |
| 222 | void UseConfig(wxConfigBase* config, |
| 223 | const wxString& rootpath = wxEmptyString); |
| 224 | |
| 225 | /** |
| 226 | Stores controllers setting (position of window etc.) |
| 227 | */ |
| 228 | virtual void WriteCustomization(wxConfigBase* cfg, |
| 229 | const wxString& path = wxEmptyString); |
| 230 | |
| 231 | protected: |
| 232 | |
| 233 | /** |
| 234 | This protected virtual method may be overridden so that when specifying the |
| 235 | @c wxHF_DIALOG style, the controller uses a different dialog. |
| 236 | */ |
| 237 | virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData* data); |
| 238 | |
| 239 | /** |
| 240 | This protected virtual method may be overridden so that the controller |
| 241 | uses a different frame. |
| 242 | */ |
| 243 | virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData* data); |
| 244 | }; |
| 245 | |
| 246 | |
| 247 | |
| 248 | /** |
| 249 | @class wxHtmlModalHelp |
| 250 | |
| 251 | This class uses wxHtmlHelpController to display help in a modal dialog. |
| 252 | This is useful on platforms such as wxMac where if you display help from a |
| 253 | modal dialog, the help window must itself be a modal dialog. |
| 254 | |
| 255 | Create objects of this class on the stack, for example: |
| 256 | |
| 257 | @code |
| 258 | // The help can be browsed during the lifetime of this object; when the |
| 259 | // user quits the help, program execution will continue. |
| 260 | wxHtmlModalHelp help(parent, "help", "My topic"); |
| 261 | @endcode |
| 262 | |
| 263 | @library{wxhtml} |
| 264 | @category{help,html} |
| 265 | */ |
| 266 | class wxHtmlModalHelp |
| 267 | { |
| 268 | public: |
| 269 | /** |
| 270 | The ctor. |
| 271 | |
| 272 | @param parent |
| 273 | is the parent of the dialog. |
| 274 | @param helpFile |
| 275 | is the HTML help file to show. |
| 276 | @param topic |
| 277 | is an optional topic. If this is empty, the help contents will be shown. |
| 278 | @param style |
| 279 | is a combination of the flags described in the wxHtmlHelpController |
| 280 | documentation. |
| 281 | */ |
| 282 | wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, |
| 283 | const wxString& topic = wxEmptyString, |
| 284 | int style = wxHF_DEFAULT_STYLE | wxHF_DIALOG | wxHF_MODAL); |
| 285 | }; |
| 286 | |