]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: html/helpctrl.h | |
3 | // Purpose: documentation for wxHtmlHelpController class | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxHtmlHelpController | |
11 | @headerfile helpctrl.h wx/html/helpctrl.h | |
7c913512 | 12 | |
23324ae1 | 13 | This help controller provides an easy way of displaying HTML help in your |
7c913512 | 14 | application (see @e test sample). The help system is based on @b books |
23324ae1 FM |
15 | (see wxHtmlHelpController::AddBook). A book is a logical |
16 | section of documentation (for example "User's Guide" or "Programmer's Guide" or | |
17 | "C++ Reference" or "wxWidgets Reference"). The help controller can handle as | |
18 | many books as you want. | |
7c913512 | 19 | |
23324ae1 FM |
20 | Although this class has an API compatible with other wxWidgets |
21 | help controllers as documented by wxHelpController, it | |
22 | is recommended that you use the enhanced capabilities of wxHtmlHelpController's | |
23 | API. | |
7c913512 | 24 | |
23324ae1 FM |
25 | wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as |
26 | its | |
27 | native format. The file format is described here. | |
28 | Have a look at docs/html/ directory where sample project files are stored. | |
7c913512 | 29 | |
23324ae1 FM |
30 | You can use Tex2RTF to produce these files when generating HTML, if you set @b |
31 | htmlWorkshopFiles to @b @true in | |
32 | your tex2rtf.ini file. The commercial tool HelpBlocks (www.helpblocks.com) can | |
33 | also create these files. | |
7c913512 | 34 | |
23324ae1 FM |
35 | @library{wxhtml} |
36 | @category{help} | |
7c913512 | 37 | |
23324ae1 FM |
38 | @seealso |
39 | @ref overview_wxhelpcontroller "Information about wxBestHelpController", | |
40 | wxHtmlHelpFrame, wxHtmlHelpDialog, wxHtmlHelpWindow, wxHtmlModalHelp | |
41 | */ | |
7c913512 | 42 | class wxHtmlHelpController |
23324ae1 FM |
43 | { |
44 | public: | |
45 | /** | |
46 | Constructor. | |
47 | */ | |
48 | wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE, | |
49 | wxWindow* parentWindow = @NULL); | |
50 | ||
51 | //@{ | |
52 | /** | |
53 | Adds book (@ref overview_helpformat ".hhp file" - HTML Help Workshop project | |
54 | file) into the list of loaded books. | |
55 | This must be called at least once before displaying any help. | |
56 | ||
57 | @e bookFile or @e bookUrl may be either .hhp file or ZIP archive | |
7c913512 | 58 | that contains arbitrary number of .hhp files in |
23324ae1 FM |
59 | top-level directory. This ZIP archive must have .zip or .htb extension |
60 | (the latter stands for "HTML book"). In other words, @c | |
7c913512 | 61 | AddBook(wxFileName("help.zip")) |
23324ae1 FM |
62 | is possible and is the recommended way. |
63 | ||
7c913512 | 64 | @param showWaitMsg |
23324ae1 FM |
65 | If @true then a decoration-less window with progress message is displayed. |
66 | ||
7c913512 | 67 | @param bookFile |
23324ae1 FM |
68 | Help book filename. It is recommended to use this prototype |
69 | instead of the one taking URL, because it is less error-prone. | |
70 | ||
7c913512 FM |
71 | @param bookUrl |
72 | Help book URL (note that syntax of filename and URL is | |
23324ae1 FM |
73 | different on most platforms) |
74 | */ | |
75 | bool AddBook(const wxFileName& bookFile, bool showWaitMsg); | |
7c913512 | 76 | bool AddBook(const wxString& bookUrl, bool showWaitMsg); |
23324ae1 FM |
77 | //@} |
78 | ||
79 | /** | |
80 | This protected virtual method may be overridden so that when specifying the | |
81 | wxHF_DIALOG style, the controller | |
82 | uses a different dialog. | |
83 | */ | |
84 | virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData * data); | |
85 | ||
86 | /** | |
87 | This protected virtual method may be overridden so that the controller | |
88 | uses a different frame. | |
89 | */ | |
90 | virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData * data); | |
91 | ||
92 | //@{ | |
93 | /** | |
94 | This alternative form is used to search help contents by numeric IDs. | |
95 | */ | |
96 | void Display(const wxString& x); | |
7c913512 | 97 | void Display(const int id); |
23324ae1 FM |
98 | //@} |
99 | ||
100 | /** | |
101 | Displays help window and focuses contents panel. | |
102 | */ | |
103 | void DisplayContents(); | |
104 | ||
105 | /** | |
106 | Displays help window and focuses index panel. | |
107 | */ | |
108 | void DisplayIndex(); | |
109 | ||
110 | /** | |
111 | Displays help window, focuses search panel and starts searching. Returns @true | |
112 | if the keyword was found. Optionally it searches through the index (mode = | |
113 | wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). | |
114 | ||
115 | @b Important: KeywordSearch searches only pages listed in .hhc file(s). | |
116 | You should list all pages in the contents file. | |
117 | */ | |
118 | bool KeywordSearch(const wxString& keyword, | |
119 | wxHelpSearchMode mode = wxHELP_SEARCH_ALL); | |
120 | ||
121 | /** | |
122 | Reads the controller's setting (position of window, etc.) | |
123 | */ | |
124 | void ReadCustomization(wxConfigBase* cfg, | |
125 | wxString path = wxEmptyString); | |
126 | ||
127 | /** | |
128 | Sets the path for storing temporary files - cached binary versions of index and | |
129 | contents files. These binary | |
130 | forms are much faster to read. Default value is empty string (empty string means | |
7c913512 | 131 | that no cached data are stored). Note that these files are @e not |
23324ae1 FM |
132 | deleted when program exits. |
133 | ||
7c913512 | 134 | Once created these cached files will be used in all subsequent executions |
23324ae1 FM |
135 | of your application. If cached files become older than corresponding .hhp |
136 | file (e.g. if you regenerate documentation) it will be refreshed. | |
137 | */ | |
138 | void SetTempDir(const wxString& path); | |
139 | ||
140 | /** | |
141 | Sets format of title of the frame. Must contain exactly one "%s" | |
142 | (for title of displayed HTML page). | |
143 | */ | |
144 | void SetTitleFormat(const wxString& format); | |
145 | ||
146 | /** | |
147 | Associates @e config object with the controller. | |
148 | ||
149 | If there is associated config object, wxHtmlHelpController automatically | |
150 | reads and writes settings (including wxHtmlWindow's settings) when needed. | |
151 | ||
152 | The only thing you must do is create wxConfig object and call UseConfig. | |
153 | ||
7c913512 FM |
154 | If you do not use @e UseConfig, wxHtmlHelpController will use |
155 | default wxConfig object if available (for details see | |
156 | wxConfigBase::Get and | |
23324ae1 FM |
157 | wxConfigBase::Set). |
158 | */ | |
159 | void UseConfig(wxConfigBase* config, | |
160 | const wxString& rootpath = wxEmptyString); | |
161 | ||
162 | /** | |
163 | Stores controllers setting (position of window etc.) | |
164 | */ | |
165 | void WriteCustomization(wxConfigBase* cfg, | |
166 | wxString path = wxEmptyString); | |
167 | }; | |
168 | ||
169 | ||
170 | /** | |
171 | @class wxHtmlModalHelp | |
172 | @headerfile helpctrl.h wx/html/helpctrl.h | |
7c913512 FM |
173 | |
174 | This class uses wxHtmlHelpController | |
23324ae1 FM |
175 | to display help in a modal dialog. This is useful on platforms such as wxMac |
176 | where if you display help from a modal dialog, the help window must itself be a | |
177 | modal | |
178 | dialog. | |
7c913512 | 179 | |
23324ae1 | 180 | Create objects of this class on the stack, for example: |
7c913512 | 181 | |
23324ae1 FM |
182 | @code |
183 | // The help can be browsed during the lifetime of this object; when the user | |
184 | quits | |
185 | // the help, program execution will continue. | |
186 | wxHtmlModalHelp help(parent, wxT("help"), wxT("My topic")); | |
187 | @endcode | |
7c913512 | 188 | |
23324ae1 FM |
189 | @library{wxhtml} |
190 | @category{FIXME} | |
191 | */ | |
7c913512 | 192 | class wxHtmlModalHelp |
23324ae1 FM |
193 | { |
194 | public: | |
195 | /** | |
7c913512 | 196 | @param parent |
23324ae1 FM |
197 | is the parent of the dialog. |
198 | ||
7c913512 | 199 | @param helpFile |
23324ae1 FM |
200 | is the HTML help file to show. |
201 | ||
7c913512 | 202 | @param topic |
23324ae1 FM |
203 | is an optional topic. If this is empty, the help contents will be shown. |
204 | ||
7c913512 | 205 | @param style |
23324ae1 FM |
206 | is a combination of the flags described in the wxHtmlHelpController |
207 | documentation. | |
208 | */ | |
209 | wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, | |
210 | const wxString& topic = wxEmptyString, | |
211 | int style = wxHF_DEFAULT_STYLE | wxHF_DIALOG | wxHF_MODAL); | |
212 | }; |