1 | /****************************************************************************
|
---|
2 | **
|
---|
3 | ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
|
---|
4 | ** All rights reserved.
|
---|
5 | ** Contact: Nokia Corporation ([email protected])
|
---|
6 | **
|
---|
7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
8 | **
|
---|
9 | ** $QT_BEGIN_LICENSE:LGPL$
|
---|
10 | ** Commercial Usage
|
---|
11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
13 | ** Software or, alternatively, in accordance with the terms contained in
|
---|
14 | ** a written agreement between you and Nokia.
|
---|
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 | ** GNU General Public License Usage
|
---|
29 | ** Alternatively, this file may be used under the terms of the GNU
|
---|
30 | ** General Public License version 3.0 as published by the Free Software
|
---|
31 | ** Foundation and appearing in the file LICENSE.GPL included in the
|
---|
32 | ** packaging of this file. Please review the following information to
|
---|
33 | ** ensure the GNU General Public License version 3.0 requirements will be
|
---|
34 | ** met: http://www.gnu.org/copyleft/gpl.html.
|
---|
35 | **
|
---|
36 | ** If you have questions regarding the use of this file, please contact
|
---|
37 | ** Nokia at [email protected].
|
---|
38 | ** $QT_END_LICENSE$
|
---|
39 | **
|
---|
40 | ****************************************************************************/
|
---|
41 |
|
---|
42 | /*!
|
---|
43 | \group helpsystem
|
---|
44 | \title Help System
|
---|
45 | \ingroup groups
|
---|
46 |
|
---|
47 | \brief Classes used to provide online-help for applications.
|
---|
48 |
|
---|
49 | \keyword help system
|
---|
50 |
|
---|
51 | These classes provide for all forms of online-help in your application,
|
---|
52 | with three levels of detail:
|
---|
53 |
|
---|
54 | \list 1
|
---|
55 | \o Tool Tips and Status Bar message - flyweight help, extremely brief,
|
---|
56 | entirely integrated in the user interface, requiring little
|
---|
57 | or no user interaction to invoke.
|
---|
58 | \o What's This? - lightweight, but can be
|
---|
59 | a three-paragraph explanation.
|
---|
60 | \o Online Help - can encompass any amount of information,
|
---|
61 | but is typically slower to call up, somewhat separated
|
---|
62 | from the user's work, and often users feel that using online
|
---|
63 | help is a digression from their real task.
|
---|
64 | \endlist
|
---|
65 |
|
---|
66 | */
|
---|
67 |
|
---|
68 | /*!
|
---|
69 | \page qthelp-framework.html
|
---|
70 | \title The Qt Help Framework
|
---|
71 | \brief Integrating Documentation in Applications
|
---|
72 | \ingroup frameworks-technologies
|
---|
73 |
|
---|
74 | \section1 Topics
|
---|
75 |
|
---|
76 | \tableofcontents
|
---|
77 |
|
---|
78 | \section1 Overview
|
---|
79 | The Qt help system includes tools for generating and viewing
|
---|
80 | Qt help files. In addition it provides classes for accessing
|
---|
81 | help contents programatically to be able to integrate online
|
---|
82 | help into Qt applications.
|
---|
83 |
|
---|
84 | The actual help data, meaning the table of contents, index
|
---|
85 | keywords or html documents, is contained in Qt compressed help
|
---|
86 | files. So, one such a help file represents usually one manual
|
---|
87 | or documentation set. Since most products are more comprehensive
|
---|
88 | and consist of a number of tools, one manual is rarely enough.
|
---|
89 | Instead, more manuals which should be accessible at the same
|
---|
90 | time, exist. Ideally, it should also be possible to reference
|
---|
91 | certain points of interest of one manual to another.
|
---|
92 | Therefore, the Qt help system operates on help collection files
|
---|
93 | which include any number of compressed help files.
|
---|
94 |
|
---|
95 | However, having collection files to merge many documentation
|
---|
96 | sets may lead to some problems. For example, one index keyword
|
---|
97 | may be defined in different documentations. So, when only seeing
|
---|
98 | it in the index and activating it, you cannot be sure that
|
---|
99 | the expected documentation will be shown. Therefore, the Qt
|
---|
100 | help system offers the possibiltiy to filter the help contents
|
---|
101 | after certain attributes. This requires however, that the
|
---|
102 | attributes have been assigned to the help contents before the
|
---|
103 | generation of the compressed help file.
|
---|
104 |
|
---|
105 | As already mentioned, the Qt compressed help file contains all
|
---|
106 | data, so there is no need any longer to ship all single html
|
---|
107 | files. Instead, only the compressed help file and optionally the
|
---|
108 | collection file has to be distributed. The collection file is
|
---|
109 | optional since any existing collection file, e.g. from an older
|
---|
110 | release could be used.
|
---|
111 |
|
---|
112 | So, in general, there are four files interacting with the help
|
---|
113 | system, two used for generating Qt help and two meant for
|
---|
114 | distribution:
|
---|
115 |
|
---|
116 | \table
|
---|
117 | \header
|
---|
118 | \o Name
|
---|
119 | \o Extension
|
---|
120 | \o Brief Description
|
---|
121 | \row
|
---|
122 | \o \l {Qt Help Project}
|
---|
123 | \o .qhp
|
---|
124 | \o The input file for the help generator consisting of the table
|
---|
125 | of contents, indices and references to the actual documentation
|
---|
126 | files (*.html); it also defines a unique namespace for the
|
---|
127 | documentation.
|
---|
128 |
|
---|
129 | \row
|
---|
130 | \o Qt Compressed Help
|
---|
131 | \o .qch
|
---|
132 | \o The output file of the help generator. This binary file contains
|
---|
133 | all information specified in the help project file along with all
|
---|
134 | compressed documentation files.
|
---|
135 |
|
---|
136 | \row
|
---|
137 | \o \l {Qt Help Collection Project}
|
---|
138 | \o .qhcp
|
---|
139 | \o The input file for the help collection generator. It contains
|
---|
140 | references to compressed help files which should be included in
|
---|
141 | the collection; it also may contain other information for
|
---|
142 | customizing Qt Assistant.
|
---|
143 |
|
---|
144 | \row
|
---|
145 | \o Qt Help Collection
|
---|
146 | \o .qhc
|
---|
147 | \o The output of the help collection generator. This is the file
|
---|
148 | QHelpEngine operates on. It contains references to any number of
|
---|
149 | compressed help files as well as additional information, such as
|
---|
150 | custom filters.
|
---|
151 | \endtable
|
---|
152 |
|
---|
153 | \section1 Generating Qt Help
|
---|
154 |
|
---|
155 | Building help files for the Qt help system assumes that the html
|
---|
156 | documentation files already exist, i.e. the Qt help system does
|
---|
157 | not offer the possibility to create html files like e.g. Doxygen.
|
---|
158 |
|
---|
159 | Once the html documentents are in place, a \l {Qt Help Project} file
|
---|
160 | has to be created. After specifying all relevant information in
|
---|
161 | this file, it needs to be compiled by calling:
|
---|
162 |
|
---|
163 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 2
|
---|
164 |
|
---|
165 | The file 'doc.qch' contains then all html files in compressed
|
---|
166 | form along with the table of contents and index keywords. To
|
---|
167 | test if the generated file is correct, open Qt Assistant and
|
---|
168 | install the file via the Settings|Documentation page.
|
---|
169 |
|
---|
170 | \target Qt Help Collection Project
|
---|
171 | \section2 Creating a Qt Help Collection
|
---|
172 |
|
---|
173 | The first step is to create a Qt Help Collection Project file.
|
---|
174 | Since a Qt help collection stores primarily references to
|
---|
175 | compressed help files, the project 'mycollection.qhcp' file
|
---|
176 | looks unsurprisingly simple:
|
---|
177 |
|
---|
178 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 3
|
---|
179 |
|
---|
180 | For actually creating the collection file call:
|
---|
181 |
|
---|
182 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 4
|
---|
183 |
|
---|
184 | Instead of running two tools, one for generating the compressed
|
---|
185 | help and one for generating the collection file, it is also
|
---|
186 | possible to just run the qcollectiongenerator tool with a
|
---|
187 | slightly modified project file instructing the generator to
|
---|
188 | create the compressed help first.
|
---|
189 |
|
---|
190 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 5
|
---|
191 |
|
---|
192 | Of course, it is possible to specify more than one file in the
|
---|
193 | 'generate' or 'register' section, so any number of compressed
|
---|
194 | help files can be generated and registered in one go.
|
---|
195 |
|
---|
196 | \section1 Using Qt Help
|
---|
197 |
|
---|
198 | Accessing the help contents can be done in two ways: Using Qt
|
---|
199 | Assistant as documentation browser or using the QHelpEngine
|
---|
200 | API for embedding the help contents directly in an application.
|
---|
201 |
|
---|
202 | \section2 Using Qt Assistant
|
---|
203 |
|
---|
204 | \QA operates on a collection file which can be specified
|
---|
205 | before start up. If no collection file is given, a default one
|
---|
206 | will be created and used. In either case, it is possible to
|
---|
207 | register any Qt compressed help file and access the help contents.
|
---|
208 |
|
---|
209 | When using Assistant as the help browser for an application, it
|
---|
210 | would be desirable that it can be customized to fit better to the
|
---|
211 | application and doesn't look like an independent, standalone
|
---|
212 | help browser. To achieve this, several additional properties can
|
---|
213 | be set in an Qt help collection file, to change e.g. the title
|
---|
214 | or application icon of Qt Assistant. For more information on
|
---|
215 | this topic have a look at the \l{assistant-manual.html}
|
---|
216 | {Qt Assistant manual}.
|
---|
217 |
|
---|
218 | \section2 Using QHelpEngine API
|
---|
219 |
|
---|
220 | Instead of showing the help in an external application like the
|
---|
221 | Qt Assistant, it is also possible to embed the online help in
|
---|
222 | the application. The contents can then be retrieved via the
|
---|
223 | QHelpEngine class and can be displayed in nearly any form.
|
---|
224 | Showing it in a QTextBrowser is probably the most common way, but
|
---|
225 | embedding it in What's This help is also perfectly possible.
|
---|
226 |
|
---|
227 | Retrieving help data from the file engine does not involve a
|
---|
228 | lot of code. The first step is to create an instance of the
|
---|
229 | help engine. Then we ask the engine for the links assigned to
|
---|
230 | the identifier, in this case "MyDialog::ChangeButton". If a link
|
---|
231 | was found, meaning at least one help document exists to this topic,
|
---|
232 | we get the actual help contents by calling fileData() and display
|
---|
233 | the document to the user.
|
---|
234 |
|
---|
235 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 6
|
---|
236 |
|
---|
237 | For further information on how to use the API, have a look at
|
---|
238 | the QHelpEngine class reference.
|
---|
239 | */
|
---|
240 |
|
---|
241 | /*!
|
---|
242 | \page qthelpproject.html
|
---|
243 | \title Qt Help Project
|
---|
244 |
|
---|
245 | A Qt help project collects all data necessary to generate a
|
---|
246 | compressed help file. Along with the actual help data, like
|
---|
247 | the table of contents, index keywords and help documents, it
|
---|
248 | contains some extra information like a namespace to identify
|
---|
249 | the help file. One help project stands for one documentation,
|
---|
250 | e.g. the Qt Assistant manual.
|
---|
251 |
|
---|
252 | \section1 Qt Help Project File Format
|
---|
253 |
|
---|
254 | The file format is XML-based. For a better understanding of
|
---|
255 | the format we'll discuss the following example:
|
---|
256 |
|
---|
257 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 7
|
---|
258 |
|
---|
259 | \section2 Namespace
|
---|
260 |
|
---|
261 | To enable the QHelpEngine to retrieve the proper documentation to
|
---|
262 | a given link, every documentation set has to have a unique
|
---|
263 | identifier. A unique identifier makes is also possible for the
|
---|
264 | help collection to keep track of a documentation set without relying
|
---|
265 | on its file name. The Qt help system uses a namespace as identifier
|
---|
266 | which is defined by the mandatory namespace tags. In the example
|
---|
267 | above, the namespace is "mycompany.com.myapplication.1_0".
|
---|
268 |
|
---|
269 | \target Virtual Folders
|
---|
270 | \section2 Virtual Folders
|
---|
271 |
|
---|
272 | Having a namespace for every documentation naturally means that
|
---|
273 | the documentation sets are quite separated. From the help engines
|
---|
274 | point of view this is beneficial, but from the documentors view
|
---|
275 | it is often desirable to cross reference certain topic from one
|
---|
276 | manual to another without having to specify absolute links. To
|
---|
277 | solve this problem, the help system introduced the concept of
|
---|
278 | virtual folders.
|
---|
279 |
|
---|
280 | A virtual folder will become the root directory of all files
|
---|
281 | referenced in a compressed help file. When two documentations
|
---|
282 | share the same virtual folder, they can use relative paths when
|
---|
283 | defining hyperlinks pointing to the other documentation. If a
|
---|
284 | file is contained in both documentations or manuals, the one
|
---|
285 | from the current manual has precedence over the other.
|
---|
286 |
|
---|
287 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 8
|
---|
288 |
|
---|
289 | The above example specifies 'doc' as virtual folder. If another
|
---|
290 | manual, e.g. for a small helper tool for 'My Application'
|
---|
291 | specifies the same folder, it is sufficient to write
|
---|
292 | 'doc.html#section1' to reference the first section in the
|
---|
293 | 'My Application' manual.
|
---|
294 |
|
---|
295 | The virtual folder tag is mandatory and the folder must not
|
---|
296 | contain any '/'.
|
---|
297 |
|
---|
298 | \target Custom Filters
|
---|
299 | \section2 Custom Filters
|
---|
300 |
|
---|
301 | Next in the Qt help project file are the optional definitions of
|
---|
302 | custom filters. A custom filter contains a list of filter
|
---|
303 | attributes which will be used later to display only the documentation
|
---|
304 | which has all those attributes assigned to. So, when setting the
|
---|
305 | current filter in the QHelpEngine to "My Application 1.0" only
|
---|
306 | the documentation which has "myapp" and "1.0" set as filter
|
---|
307 | attributes will be shown.
|
---|
308 |
|
---|
309 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 9
|
---|
310 |
|
---|
311 | It is possible to define any number of custom filters in a help
|
---|
312 | project file. Important to know is, that the filter attributes have
|
---|
313 | not to be specified in the same project file; they can be defined
|
---|
314 | in any other help file. The definition of a filter attributes
|
---|
315 | takes place by specifying them in a filter section.
|
---|
316 |
|
---|
317 | \target Filter Section
|
---|
318 | \section2 Filter Section
|
---|
319 |
|
---|
320 | A filter section contains the actual documentation. One Qt help project
|
---|
321 | file may contain more than one filter sections. Every filter section
|
---|
322 | consists of four parts, the filter attributes section, the table of
|
---|
323 | contents, the keywords and the files list. In theory all parts are
|
---|
324 | optional but not specifying anything there will result in an empty
|
---|
325 | documentation.
|
---|
326 |
|
---|
327 | \section3 Filter Attributes
|
---|
328 |
|
---|
329 | Every filter section should have filter attributes assigned to it, to
|
---|
330 | enable documentation filtering. If no filter attribute is defined, the
|
---|
331 | documentation will only be shown if no filtering occurs, meaning the
|
---|
332 | current custom filter in the QHelpEngine does not contain any filter
|
---|
333 | attributes.
|
---|
334 |
|
---|
335 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 10
|
---|
336 |
|
---|
337 | In this case, the filter attributes 'myapp' and '1.0' are assigned
|
---|
338 | to the filter section, i.e. all contents specified in this section
|
---|
339 | will only be shown if the current custom filter has 'myapp' or '1.0'
|
---|
340 | or both as filter attributes.
|
---|
341 |
|
---|
342 | \section3 Table of contents
|
---|
343 |
|
---|
344 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 11
|
---|
345 |
|
---|
346 | One section tag represents one item in the table of contents. The
|
---|
347 | sections can be nested to any degree, but from a users perspective
|
---|
348 | it should not be more than four or five levels. A section is defined
|
---|
349 | by its title and reference. The reference, like all file references in a Qt
|
---|
350 | help project, are relative to the help project file itself.
|
---|
351 | \note The referenced files must be inside the same directory (or within a
|
---|
352 | subdirectory) as the help project file. An absolute file path is not supported
|
---|
353 | either.
|
---|
354 |
|
---|
355 | \section3 Keywords
|
---|
356 |
|
---|
357 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 12
|
---|
358 |
|
---|
359 | The keyword section lists all keywords of this filter section. A
|
---|
360 | keyword consists basically of a name and a file reference. If the
|
---|
361 | attribute 'name' is used then the keyword specified there will appear in
|
---|
362 | the visible index, i.e. it will be accessible through the QHelpIndexModel.
|
---|
363 | If 'id' is used, the keyword does not appear in the index and is
|
---|
364 | only accessible via the linksForIdentifier() function of the
|
---|
365 | QHelpEngineCore. 'name' and 'id' can be specified at the same time.
|
---|
366 |
|
---|
367 | \section3 Files
|
---|
368 |
|
---|
369 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 13
|
---|
370 |
|
---|
371 | Finally, the actual documentation files have to be listed. Make sure
|
---|
372 | that all files neccessary to display the help are mentioned, i.e.
|
---|
373 | stylesheets or similar files need to be there as well. The files, like all
|
---|
374 | file references in a Qt help project, are relative to the help project file
|
---|
375 | itself. As the example shows, files (but not directories) can also be
|
---|
376 | specified as patterns using wildcards. All listed files will be compressed
|
---|
377 | and written to the Qt compressed help file. So, in the end, one single Qt
|
---|
378 | help file contains all documentation files along with the contents and
|
---|
379 | indices. \note The referenced files must be inside the same directory
|
---|
380 | (or within a subdirectory) as the help project file. An absolute file path
|
---|
381 | is not supported either.
|
---|
382 | */
|
---|