]> git.saurik.com Git - wxWidgets.git/blame - interface/html/helpctrl.h
adjusted indentation with astyle; added Id keyword
[wxWidgets.git] / interface / html / helpctrl.h
CommitLineData
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 42class wxHtmlHelpController
23324ae1
FM
43{
44public:
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 192class wxHtmlModalHelp
23324ae1
FM
193{
194public:
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};