|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example help/simpletextviewer |
|
44 \title Simple Text Viewer Example |
|
45 |
|
46 The Simple Text Viewer example shows how to use \QA as a customized |
|
47 help viewer for your application. |
|
48 |
|
49 This is done in two stages. Firstly, documentation is created and \QA |
|
50 is customized; secondly, the functionality to launch and control |
|
51 \QA is added to the application. |
|
52 |
|
53 \image simpletextviewer-example.png |
|
54 |
|
55 The Simple Text Viewer application lets the user select and view |
|
56 existing files. |
|
57 |
|
58 The application provides its own custom documentation that is |
|
59 available from the \gui Help menu in the main window's menu bar |
|
60 or by clicking the \gui Help button in the application's find file |
|
61 dialog. |
|
62 |
|
63 The example consists of four classes: |
|
64 |
|
65 \list |
|
66 \o \c Assistant provides functionality to launch \QA. |
|
67 \o \c MainWindow is the main application window. |
|
68 \o \c FindFileDialog allows the user to search for |
|
69 files using wildcard matching. |
|
70 \o \c TextEdit provides a rich text browser that makes |
|
71 sure that images referenced in HTML documents are |
|
72 displayed properly. |
|
73 \endlist |
|
74 |
|
75 Note that we will only comment on the parts of the implementation |
|
76 that are relevant to the main issue, that is making Qt Assistant |
|
77 act as a customized help viewer for our Simple Text Viewer |
|
78 application. |
|
79 |
|
80 \section1 Creating Documentation and Customizing \QA |
|
81 |
|
82 How to create the actual documentation in the form of HTML pages is |
|
83 not in the scope of this example. In general, HTML pages can either |
|
84 be written by hand or generated with the help of documentation tools |
|
85 like qdoc or Doxygen. For the purposes of this example we assume that |
|
86 the HTML files have already been created. So, the only thing that |
|
87 remains to be done is to tell \QA how to structure and display the |
|
88 help information. |
|
89 |
|
90 \section2 Organizing Documentation for \QA |
|
91 |
|
92 Plain HTML files only contain text or documentation about specific topics, |
|
93 but they usually include no information about how several HTML documents |
|
94 relate to each other or in which order they are supposed to be read. |
|
95 What is missing is a table of contents along with an index to access |
|
96 certain help contents quickly, without having to browse through a lot |
|
97 of documents in order to find a piece of information. |
|
98 |
|
99 To organize the documentation and make it available for \QA, we have |
|
100 to create a Qt help project (.qhp) file. The first and most important |
|
101 part of the project file is the definition of the namespace. The namespace |
|
102 has to be unique and will be the first part of the page URL in \QA. |
|
103 In addition, we have to set a virtual folder which acts as a common |
|
104 folder for documentation sets. This means, that two documentation sets |
|
105 identified by two different namespaces can cross reference HTML files |
|
106 since those files are in one big virtual folder. However, for this |
|
107 example, we'll only have one documentation set available, so the |
|
108 virtual folder name and functionality are not important. |
|
109 |
|
110 \code |
|
111 <?xml version="1.0" encoding="UTF-8"?> |
|
112 <QtHelpProject version="1.0"> |
|
113 <namespace>com.trolltech.examples.simpletextviewer</namespace> |
|
114 <virtualFolder>doc</virtualFolder> |
|
115 \endcode |
|
116 |
|
117 The next step is to define the filter section. A filter section |
|
118 contains the table of contents, indices and a complete list of |
|
119 all documentation files, and can have any number of filter attributes |
|
120 assigned to it. A filter attribute is an ordinary string which can |
|
121 be freely chosen. Later in \QA, users can then define a custom |
|
122 filter referencing those attributes. If the attributes of a filter |
|
123 section match the attributes of the custom filter the documentation |
|
124 will be shown, otherwise \QA will hide the documentation. |
|
125 |
|
126 Again, since we'll only have one documentation set, we do not need |
|
127 the filtering functionality of \QA and can therefore skip the |
|
128 filter attributes. |
|
129 |
|
130 Now, we build up the table of contents. An item in the table is |
|
131 defined by the \c section tag which contains the attributes for the |
|
132 item title as well as link to the actual page. Section tags can be |
|
133 nested infinitely, but for practical reasons it is not recommended |
|
134 to nest them deeper than three or four levels. For our example we |
|
135 want to use the following outline for the table of contents: |
|
136 |
|
137 \list |
|
138 \o Simple Text Viewer |
|
139 \list |
|
140 \o Find File |
|
141 \list |
|
142 \o File Dialog |
|
143 \o Wildcard Matching |
|
144 \o Browse |
|
145 \endlist |
|
146 \o Open File |
|
147 \endlist |
|
148 \endlist |
|
149 |
|
150 In the help project file, the outline is represented by: |
|
151 |
|
152 \code |
|
153 <filterSection> |
|
154 <toc> |
|
155 <section title="Simple Text Viewer" ref="index.html"> |
|
156 <section title="Find File" ref="./findfile.html"> |
|
157 <section title="File Dialog" ref="./filedialog.html"></section> |
|
158 <section title="Wildcard Matching" ref="./wildcardmatching.html"></section> |
|
159 <section title="Browse" ref="./browse.html"></section> |
|
160 </section> |
|
161 <section title="Open File" ref="./openfile.html"></section> |
|
162 </section> |
|
163 </toc> |
|
164 \endcode |
|
165 |
|
166 After the table of contents is defined, we will list all index keywords: |
|
167 |
|
168 \code |
|
169 <keywords> |
|
170 <keyword name="Display" ref="./index.html"/> |
|
171 <keyword name="Rich text" ref="./index.html"/> |
|
172 <keyword name="Plain text" ref="./index.html"/> |
|
173 <keyword name="Find" ref="./findfile.html"/> |
|
174 <keyword name="File menu" ref="./findfile.html"/> |
|
175 <keyword name="File name" ref="./filedialog.html"/> |
|
176 <keyword name="File dialog" ref="./filedialog.html"/> |
|
177 <keyword name="File globbing" ref="./wildcardmatching.html"/> |
|
178 <keyword name="Wildcard matching" ref="./wildcardmatching.html"/> |
|
179 <keyword name="Wildcard syntax" ref="./wildcardmatching.html"/> |
|
180 <keyword name="Browse" ref="./browse.html"/> |
|
181 <keyword name="Directory" ref="./browse.html"/> |
|
182 <keyword name="Open" ref="./openfile.html"/> |
|
183 <keyword name="Select" ref="./openfile.html"/> |
|
184 </keywords> |
|
185 \endcode |
|
186 |
|
187 As the last step, we have to list all files making up the documentation. |
|
188 An important point to note here is that all files have to listed, including |
|
189 image files, and even stylesheets if they are used. |
|
190 |
|
191 \code |
|
192 <files> |
|
193 <file>browse.html</file> |
|
194 <file>filedialog.html</file> |
|
195 <file>findfile.html</file> |
|
196 <file>index.html</file> |
|
197 <file>intro.html</file> |
|
198 <file>openfile.html</file> |
|
199 <file>wildcardmatching.html</file> |
|
200 <file>images/browse.png</file> |
|
201 <file>images/*.png</file> |
|
202 </files> |
|
203 </filterSection> |
|
204 </QtHelpProject> |
|
205 \endcode |
|
206 |
|
207 The help project file is now finished. If you want to see the resulting |
|
208 documentation in \QA, you have to generate a Qt compressed help file |
|
209 out of it and register it with the default help collection of \QA. |
|
210 |
|
211 \code |
|
212 qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch |
|
213 assistant -register simpletextviewer.qch |
|
214 \endcode |
|
215 |
|
216 If you start \QA now, you'll see the Simple Text Viewer documentation |
|
217 beside the Qt documentation. This is OK for testing purposes, but |
|
218 for the final version we want to only have the Simple Text Viewer |
|
219 documentation in \QA. |
|
220 |
|
221 \section2 Customizing \QA |
|
222 |
|
223 The easiest way to make \QA only display the Simple Text Viewer |
|
224 documentation is to create our own help collection file. A collection |
|
225 file is stored in a binary format, similar to the compressed help file, |
|
226 and generated from a help collection project file (*.qhcp). With |
|
227 the help of a collection file, we can customize the appearance and even |
|
228 some functionality offered by \QA. |
|
229 |
|
230 At first, we change the window title and icon. Instead of showing "\QA" |
|
231 it will show "Simple Text Viewer", so it is much clearer for the user |
|
232 that the help viewer actually belongs to our application. |
|
233 |
|
234 \code |
|
235 <?xml version="1.0" encoding="UTF-8"?> |
|
236 <QHelpCollectionProject version="1.0"> |
|
237 <assistant> |
|
238 <title>Simple Text Viewer</title> |
|
239 <applicationIcon>images/handbook.png</applicationIcon> |
|
240 <cacheDirectory>Trolltech/SimpleTextViewer</cacheDirectory> |
|
241 \endcode |
|
242 |
|
243 The \c cacheDirectory tag specifies a subdirectory of the users |
|
244 data directory (see the |
|
245 \l{Using Qt Assistant as a Custom Help Viewer#Qt Help Collection Files}{Qt Help Collection Files}) |
|
246 where the cache file for the full text search or the settings file will |
|
247 be stored. |
|
248 |
|
249 After this, we set the page displayed by \QA when launched for the very |
|
250 first time in its new configuration. The URL consists of the namespace |
|
251 and virtual folder defined in the Qt help project file, followed by the |
|
252 actual page file name. |
|
253 |
|
254 \code |
|
255 <startPage>qthelp://com.trolltech.examples.simpletextviewer/doc/index.html</startPage> |
|
256 \endcode |
|
257 |
|
258 Next, we alter the name of the "About" menu item to "About Simple |
|
259 Text Viewer". The contents of the \gui{About} dialog are also changed |
|
260 by specifying a file where the about text or icon is taken from. |
|
261 |
|
262 \code |
|
263 <aboutMenuText> |
|
264 <text>About Simple Text Viewer</text> |
|
265 </aboutMenuText> |
|
266 <aboutDialog> |
|
267 <file>about.txt</file> |
|
268 <icon>images/icon.png</icon> |
|
269 </aboutDialog> |
|
270 \endcode |
|
271 |
|
272 \QA offers the possibility to add or remove documentation via its |
|
273 preferences dialog. This functionality is helpful when using \QA |
|
274 as the central help viewer for more applications, but in our case |
|
275 we want to actually prevent the user from removing the documentation. |
|
276 So, we disable the documentation manager. |
|
277 |
|
278 Since the address bar is not really relevant in such a small |
|
279 documentation set we switch it off as well. By having just one filter |
|
280 section, without any filter attributes, we can also disable the filter |
|
281 functionality of \QA, which means that the filter page and the filter |
|
282 toolbar will not be available. |
|
283 |
|
284 \code |
|
285 <enableDocumentationManager>false</enableDocumentationManager> |
|
286 <enableAddressBar>false</enableAddressBar> |
|
287 <enableFilterFunctionality>false</enableFilterFunctionality> |
|
288 </assistant> |
|
289 \endcode |
|
290 |
|
291 For testing purposes, we already generated the compressed help file |
|
292 and registered it with \QA's default help collection. With the |
|
293 following lines we achieve the same result. The only and important |
|
294 difference is that we register the compressed help file, not in |
|
295 the default collection, but in our own collection file. |
|
296 |
|
297 \code |
|
298 <docFiles> |
|
299 <generate> |
|
300 <file> |
|
301 <input>simpletextviewer.qhp</input> |
|
302 <output>simpletextviewer.qch</output> |
|
303 </file> |
|
304 </generate> |
|
305 <register> |
|
306 <file>simpletextviewer.qch</file> |
|
307 </register> |
|
308 </docFiles> |
|
309 </QHelpCollectionProject> |
|
310 \endcode |
|
311 |
|
312 As the last step, we have to generate the binary collection file |
|
313 out of the help collection project file. This is done by running the |
|
314 \c qcollectiongenerator tool. |
|
315 |
|
316 \code |
|
317 qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc |
|
318 \endcode |
|
319 |
|
320 To test all our customizations made to \QA, we add the collection |
|
321 file name to the command line: |
|
322 |
|
323 \code |
|
324 assistant -collectionFile simpletextviewer.qhc |
|
325 \endcode |
|
326 |
|
327 \section1 Controlling \QA via the Assistant Class |
|
328 |
|
329 We will first take a look at how to start and operate \QA from a |
|
330 remote application. For that purpose, we create a class called |
|
331 \c Assistant. |
|
332 |
|
333 This class provides a public function that is used to show pages |
|
334 of the documentation, and one private helper function to make sure |
|
335 that \QA is up and running. |
|
336 |
|
337 Launching \QA is done in the function \c startAssistant() by simply |
|
338 creating and starting a QProcess. If the process is already running, |
|
339 the function returns immediately. Otherwise, the process has |
|
340 to be set up and started. |
|
341 |
|
342 \snippet examples/help/simpletextviewer/assistant.cpp 2 |
|
343 |
|
344 To start the process we need the executable name of \QA as well as the |
|
345 command line arguments for running \QA in a customized mode. The |
|
346 executable name is a little bit tricky since it depends on the |
|
347 platform, but fortunately it is only different on Mac OS X. |
|
348 |
|
349 The displayed documentation can be altered using the \c -collectionFile |
|
350 command line argument when launching \QA. When started without any options, |
|
351 \QA displays a default set of documentation. When Qt is installed, |
|
352 the default documentation set in \QA contains the Qt reference |
|
353 documentation as well as the tools that come with Qt, such as Qt |
|
354 Designer and \c qmake. |
|
355 |
|
356 In our example, we replace the default documentation set with our |
|
357 custom documentation by passing our application-specific collection |
|
358 file to the process's command line options. |
|
359 |
|
360 As the last argument, we add \c -enableRemoteControl, which makes \QA |
|
361 listen to its \c stdin channel for commands, such as those to display |
|
362 a certain page in the documentation. |
|
363 Then we start the process and wait until it is actually running. If, |
|
364 for some reason \QA cannot be started, \c startAssistant() will return |
|
365 false. |
|
366 |
|
367 The implementation for \c showDocumentation() is now straightforward. |
|
368 Firstly, we ensure that \QA is running, then we send the request to |
|
369 display the \a page via the \c stdin channel of the process. It is very |
|
370 important here that the command is terminated by the '\\0' character |
|
371 followed by an end of line token to flush the channel. |
|
372 |
|
373 \snippet examples/help/simpletextviewer/assistant.cpp 1 |
|
374 |
|
375 Finally, we make sure that \QA is terminated properly in the case that |
|
376 the application is shut down. The destructor of QProcess kills the |
|
377 process, meaning that the application has no possibility to do things |
|
378 like save user settings, which would result in corrupted settings files. |
|
379 To avoid this, we ask \QA to terminate in the destructor of the |
|
380 \c Assistant class. |
|
381 |
|
382 \snippet examples/help/simpletextviewer/assistant.cpp 0 |
|
383 |
|
384 \section1 MainWindow Class |
|
385 |
|
386 \image simpletextviewer-mainwindow.png |
|
387 |
|
388 The \c MainWindow class provides the main application window with |
|
389 two menus: the \gui File menu lets the user open and view an |
|
390 existing file, while the \gui Help menu provides information about |
|
391 the application and about Qt, and lets the user open \QA to |
|
392 display the application's documentation. |
|
393 |
|
394 To be able to access the help functionality, we initialize the |
|
395 \c Assistant object in the \c MainWindow's constructor. |
|
396 |
|
397 \snippet examples/help/simpletextviewer/mainwindow.cpp 0 |
|
398 \dots |
|
399 \snippet examples/help/simpletextviewer/mainwindow.cpp 1 |
|
400 |
|
401 Then we create all the actions for the Simple Text Viewer application. |
|
402 Of special interest is the \c assistantAct action accessible |
|
403 via the \key{F1} shortcut or the \menu{Help|Help Contents} menu item. |
|
404 This action is connected to the \c showDocumentation() slot of |
|
405 the \c MainWindow class. |
|
406 |
|
407 \snippet examples/help/simpletextviewer/mainwindow.cpp 4 |
|
408 \dots |
|
409 \snippet examples/help/simpletextviewer/mainwindow.cpp 5 |
|
410 |
|
411 In the \c showDocumentation() slot, we call the \c showDocumentation() |
|
412 function of the \c Assistant class with the URL of home page of the |
|
413 documentation. |
|
414 |
|
415 \snippet examples/help/simpletextviewer/mainwindow.cpp 3 |
|
416 |
|
417 Finally, we must reimplement the protected QWidget::closeEvent() |
|
418 event handler to ensure that the application's \QA instance is |
|
419 properly closed before we terminate the application. |
|
420 |
|
421 \snippet examples/help/simpletextviewer/mainwindow.cpp 2 |
|
422 |
|
423 \section1 FindFileDialog Class |
|
424 |
|
425 \image simpletextviewer-findfiledialog.png |
|
426 |
|
427 The Simple Text Viewer application provides a find file dialog |
|
428 allowing the user to search for files using wildcard matching. The |
|
429 search is performed within the specified directory, and the user |
|
430 is given an option to browse the existing file system to find the |
|
431 relevant directory. |
|
432 |
|
433 In the constructor we save the references to the \c Assistant |
|
434 and \c QTextEdit objects passed as arguments. The \c Assistant |
|
435 object will be used in the \c FindFileDialog's \c help() slot, |
|
436 as we will see shortly, while the QTextEdit will be used in the |
|
437 dialog's \c openFile() slot to display the chosen file. |
|
438 |
|
439 \snippet examples/help/simpletextviewer/findfiledialog.cpp 0 |
|
440 \dots |
|
441 \snippet examples/help/simpletextviewer/findfiledialog.cpp 1 |
|
442 |
|
443 The most relevant member to observe in the \c FindFileDialog |
|
444 class is the private \c help() slot. The slot is connected to the |
|
445 dialog's \gui Help button, and brings the current \QA instance |
|
446 to the foreground with the documentation for the dialog by |
|
447 calling \c Assistant's \c showDocumentation() function. |
|
448 |
|
449 \snippet examples/help/simpletextviewer/findfiledialog.cpp 2 |
|
450 |
|
451 \section1 Summary |
|
452 |
|
453 In order to make \QA act as a customized help tool for |
|
454 your application, you must provide your application with a |
|
455 process that controls \QA in addition to a custom help collection |
|
456 file including Qt compressed help files. |
|
457 |
|
458 The \l{Using Qt Assistant as a Custom Help Viewer} document contains |
|
459 more information about the options and settings available to |
|
460 applications that use \QA as a custom help viewer. |
|
461 */ |