]>
Commit | Line | Data |
---|---|---|
1 | \section{\class{wxHelpController}}\label{wxhelpcontroller} | |
2 | ||
3 | This is a family of classes by which | |
4 | applications may invoke a help viewer to provide on-line help. | |
5 | ||
6 | A help controller allows an application to display help, at the contents | |
7 | or at a particular topic, and shut the help program down on termination. | |
8 | This avoids proliferation of many instances of the help viewer whenever the | |
9 | user requests a different topic via the application's menus or buttons. | |
10 | ||
11 | Typically, an application will create a help controller instance | |
12 | when it starts, and immediately call {\bf Initialize}\rtfsp | |
13 | to associate a filename with it. The help viewer will only get run, however, | |
14 | just before the first call to display something. | |
15 | ||
16 | Most help controller classes actually derive from wxHelpControllerBase and have | |
17 | names of the form wxXXXHelpController or wxHelpControllerXXX. An | |
18 | appropriate class is aliased to the name wxHelpController for each platform, as follows: | |
19 | ||
20 | \begin{itemize}\itemsep=0pt | |
21 | \item On Windows, wxWinHelpController is used. | |
22 | \item On all other platforms, wxHtmlHelpController is used if wxHTML is | |
23 | compiled into wxWindows; otherwise wxExtHelpController is used (for invoking an external | |
24 | browser). | |
25 | \end{itemize} | |
26 | ||
27 | The remaining help controller classess need to be named | |
28 | explicitly by an application that wishes to make use of them. | |
29 | ||
30 | There are currently the following help controller classes defined: | |
31 | ||
32 | \begin{itemize}\itemsep=0pt | |
33 | \item wxWinHelpController, for controlling Windows Help. | |
34 | \item wxCHMHelpController, for controlling MS HTML Help. To use this, you need to set wxUSE\_MS\_HTML\_HELP | |
35 | to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you don't need | |
36 | VC++ specific htmlhelp.lib because wxWindows loads neccessary DLL at runtime and so it | |
37 | works with all compilers). | |
38 | \item wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime is | |
39 | not available, \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}. You need to provide | |
40 | {\bf both} CHM and HTB versions of the help file. For 32bit Windows only. | |
41 | \item wxExtHelpController, for controlling external browsers under Unix. | |
42 | The default browser is Netscape Navigator. The 'help' sample shows its use. | |
43 | \item \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, a sophisticated help controller using \helpref{wxHTML}{wxhtml}, in | |
44 | a similar style to the Microsoft HTML Help viewer and using some of the same files. | |
45 | Although it has an API compatible with other help controllers, it has more advanced features, so it is | |
46 | recommended that you use the specific API for this class instead. | |
47 | \end{itemize} | |
48 | ||
49 | \wxheading{Derived from} | |
50 | ||
51 | wxHelpControllerBase\\ | |
52 | \helpref{wxObject}{wxobject} | |
53 | ||
54 | \wxheading{Include files} | |
55 | ||
56 | <wx/help.h> (wxWindows chooses the appropriate help controller class)\\ | |
57 | <wx/helpbase.h> (wxHelpControllerBase class)\\ | |
58 | <wx/helpwin.h> (Windows Help controller)\\ | |
59 | <wx/msw/helpchm.h> (MS HTML Help controller)\\ | |
60 | <wx/generic/helpext.h> (external HTML browser controller)\\ | |
61 | <wx/html/helpctrl.h> (wxHTML based help controller: wxHtmlHelpController) | |
62 | ||
63 | \wxheading{See also} | |
64 | ||
65 | \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller}, \helpref{wxHTML}{wxhtml} | |
66 | ||
67 | \latexignore{\rtfignore{\wxheading{Members}}} | |
68 | ||
69 | \membersection{wxHelpController::wxHelpController} | |
70 | ||
71 | \func{}{wxHelpController}{\void} | |
72 | ||
73 | Constructs a help instance object, but does not invoke the help viewer. | |
74 | ||
75 | \membersection{wxHelpController::\destruct{wxHelpController}} | |
76 | ||
77 | \func{}{\destruct{wxHelpController}}{\void} | |
78 | ||
79 | Destroys the help instance, closing down the viewer if it is running. | |
80 | ||
81 | \membersection{wxHelpController::Initialize}\label{wxhelpcontrollerinitialize} | |
82 | ||
83 | \func{virtual void}{Initialize}{\param{const wxString\& }{file}} | |
84 | ||
85 | \func{virtual void}{Initialize}{\param{const wxString\& }{file}, \param{int}{ server}} | |
86 | ||
87 | Initializes the help instance with a help filename, and optionally a server socket | |
88 | number if using wxHelp (now obsolete). Does not invoke the help viewer. | |
89 | This must be called directly after the help instance object is created and before | |
90 | any attempts to communicate with the viewer. | |
91 | ||
92 | You may omit the file extension and a suitable one will be chosen. For | |
93 | wxHtmlHelpController, the extensions zip, htb and hhp will be appended while searching for | |
94 | a suitable file. For WinHelp, the hlp extension is appended. | |
95 | ||
96 | \membersection{wxHelpController::DisplayBlock}\label{wxhelpcontrollerdisplayblock} | |
97 | ||
98 | \func{virtual bool}{DisplayBlock}{\param{long}{ blockNo}} | |
99 | ||
100 | If the help viewer is not running, runs it and displays the file at the given block number. | |
101 | ||
102 | {\it WinHelp:} Refers to the context number. | |
103 | ||
104 | {\it MS HTML Help:} Refers to the context number. | |
105 | ||
106 | {\it External HTML help:} the same as for \helpref{wxHelpController::DisplaySection}{wxhelpcontrollerdisplaysection}. | |
107 | ||
108 | {\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}. | |
109 | ||
110 | This function is for backward compatibility only, and applications should use \helpref{wxHelpController}{wxhelpcontrollerdisplaysection} instead. | |
111 | ||
112 | \membersection{wxHelpController::DisplayContents}\label{wxhelpcontrollerdisplaycontents} | |
113 | ||
114 | \func{virtual bool}{DisplayContents}{\void} | |
115 | ||
116 | If the help viewer is not running, runs it and displays the | |
117 | contents. | |
118 | ||
119 | \membersection{wxHelpController::DisplayContextPopup}\label{wxhelpcontrollerdisplaycontextpopup} | |
120 | ||
121 | \func{virtual bool}{DisplayContextPopup}{\param{int }{contextId}} | |
122 | ||
123 | Displays the section as a popup window using a context id. | |
124 | ||
125 | Returns FALSE if unsuccessful or not implemented. | |
126 | ||
127 | \membersection{wxHelpController::DisplaySection}\label{wxhelpcontrollerdisplaysection} | |
128 | ||
129 | \func{virtual bool}{DisplaySection}{\param{const wxString\&}{ section}} | |
130 | ||
131 | If the help viewer is not running, runs it and displays the given section. | |
132 | ||
133 | The interpretation of {\it section} differs between help viewers. For most viewers, | |
134 | this call is equivalent to KeywordSearch. For MS HTML Help, external HTML help | |
135 | and simple wxHTML help, if {\it section} has a .htm | |
136 | or .html extension, that HTML file will be displayed; otherwise | |
137 | a keyword search is done. | |
138 | ||
139 | \func{virtual bool}{DisplaySection}{\param{int}{ sectionNo}} | |
140 | ||
141 | If the help viewer is not running, runs it and displays the given section. | |
142 | ||
143 | {\it WinHelp, MS HTML Help:} {\it sectionNo} is a context id. | |
144 | ||
145 | {\it External HTML help/simple wxHTML help:} wxExtHelpController implements {\it sectionNo} as an id in a map file, which is of the form: | |
146 | ||
147 | \begin{verbatim} | |
148 | 0 wx.html ; Index | |
149 | 1 wx34.html#classref ; Class reference | |
150 | 2 wx204.html ; Function reference | |
151 | \end{verbatim} | |
152 | ||
153 | {\it wxHtmlHelpController:} {\it sectionNo} is an identifier as specified in the {\tt .hhc} file. See \helpref{Help files format}{helpformat}. | |
154 | ||
155 | See also the help sample for notes on how to specify section numbers for various help file formats. | |
156 | ||
157 | \membersection{wxHelpController::DisplayTextPopup}\label{wxhelpcontrollerdisplaytextpopup} | |
158 | ||
159 | \func{virtual bool}{DisplayTextPopup}{\param{const wxString\&}{ text}, \param{const wxPoint\& }{pos}} | |
160 | ||
161 | Displays the text in a popup window, if possible. | |
162 | ||
163 | Returns FALSE if unsuccessful or not implemented. | |
164 | ||
165 | \membersection{wxHelpController::GetFrameParameters}\label{wxhelpcontrollergetframeparameters} | |
166 | ||
167 | \func{virtual wxFrame *}{GetFrameParameters}{\param{const wxSize * }{size = NULL}, \param{const wxPoint * }{pos = NULL}, | |
168 | \param{bool *}{newFrameEachTime = NULL}} | |
169 | ||
170 | wxHtmlHelpController returns the frame, size and position. | |
171 | ||
172 | For all other help controllers, this function does nothing | |
173 | and just returns NULL. | |
174 | ||
175 | \wxheading{Parameters} | |
176 | ||
177 | \docparam{viewer}{This defaults to "netscape" for wxExtHelpController.} | |
178 | ||
179 | \docparam{flags}{This defaults to wxHELP\_NETSCAPE for wxExtHelpController, indicating | |
180 | that the viewer is a variant of Netscape Navigator.} | |
181 | ||
182 | \membersection{wxHelpController::KeywordSearch}\label{wxhelpcontrollerkeywordsearch} | |
183 | ||
184 | \func{virtual bool}{KeywordSearch}{\param{const wxString\& }{keyWord}} | |
185 | ||
186 | If the help viewer is not running, runs it, and searches for sections matching the given keyword. If one | |
187 | match is found, the file is displayed at this section. | |
188 | ||
189 | {\it WinHelp, MS HTML Help:} If more than one match is found, | |
190 | the first topic is displayed. | |
191 | ||
192 | {\it External HTML help, simple wxHTML help:} If more than one match is found, | |
193 | a choice of topics is displayed. | |
194 | ||
195 | {\it wxHtmlHelpController:} see \helpref{wxHtmlHelpController::KeywordSearch}{wxhtmlhelpcontrollerkeywordsearch}. | |
196 | ||
197 | \membersection{wxHelpController::LoadFile}\label{wxhelpcontrollerloadfile} | |
198 | ||
199 | \func{virtual bool}{LoadFile}{\param{const wxString\& }{file = ""}} | |
200 | ||
201 | If the help viewer is not running, runs it and loads the given file. | |
202 | If the filename is not supplied or is | |
203 | empty, the file specified in {\bf Initialize} is used. If the viewer is | |
204 | already displaying the specified file, it will not be reloaded. This | |
205 | member function may be used before each display call in case the user | |
206 | has opened another file. | |
207 | ||
208 | wxHtmlHelpController ignores this call. | |
209 | ||
210 | \membersection{wxHelpController::OnQuit}\label{wxhelpcontrolleronquit} | |
211 | ||
212 | \func{virtual bool}{OnQuit}{\void} | |
213 | ||
214 | Overridable member called when this application's viewer is quit by the user. | |
215 | ||
216 | This does not work for all help controllers. | |
217 | ||
218 | \membersection{wxHelpController::SetFrameParameters}\label{wxhelpcontrollersetframeparameters} | |
219 | ||
220 | \func{virtual void}{SetFrameParameters}{\param{const wxString \& }{title}, | |
221 | \param{const wxSize \& }{size}, \param{const wxPoint \& }{pos = wxDefaultPosition}, | |
222 | \param{bool }{newFrameEachTime = FALSE}} | |
223 | ||
224 | For wxHtmlHelpController, the title is set (again with \%s indicating the | |
225 | page title) and also the size and position of the frame if the frame is already | |
226 | open. {\it newFrameEachTime} is ignored. | |
227 | ||
228 | For all other help controllers this function has no effect. | |
229 | ||
230 | \membersection{wxHelpController::SetViewer}\label{wxhelpcontrollersetviewer} | |
231 | ||
232 | \func{virtual void}{SetViewer}{\param{const wxString\& }{viewer}, \param{long}{ flags}} | |
233 | ||
234 | Sets detailed viewer information. So far this is only relevant to wxExtHelpController. | |
235 | ||
236 | Some examples of usage: | |
237 | ||
238 | \begin{verbatim} | |
239 | m_help.SetViewer("kdehelp"); | |
240 | m_help.SetViewer("gnome-help-browser"); | |
241 | m_help.SetViewer("netscape", wxHELP_NETSCAPE); | |
242 | \end{verbatim} | |
243 | ||
244 | \membersection{wxHelpController::Quit}\label{wxhelpcontrollerquit} | |
245 | ||
246 | \func{virtual bool}{Quit}{\void} | |
247 | ||
248 | If the viewer is running, quits it by disconnecting. | |
249 | ||
250 | For Windows Help, the viewer will only close if no other application is using it. | |
251 |