Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qthelp.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\group helpsystem
6
\title Help System
7
\ingroup groups
8
9
\brief Classes used to provide online-help for applications.
10
11
\keyword help system
12
13
These classes provide online-help for your application,
14
with three levels of detail:
15
16
\list 1
17
\li Tool Tips and Status Bar message - flyweight help, extremely brief,
18
entirely integrated in the user interface, requiring little
19
or no user interaction to invoke.
20
\li What's This? - lightweight, but can be
21
a three-paragraph explanation.
22
\li Online Help - can encompass any amount of information,
23
but is typically slower to call up, somewhat separated
24
from the user's work, and often users feel that using online
25
help is a digression from their real task.
26
\endlist
27
28
*/
29
30
/*!
31
\page qthelp-framework.html
32
\title The Qt Help Framework
33
\brief Integrating Documentation in Applications
34
\ingroup frameworks-technologies
35
36
\section1 Overview
37
The Qt help system includes tools for generating and viewing
38
Qt help files. In addition, it provides classes for accessing
39
help contents programmatically to be able to integrate online
40
help into Qt applications.
41
42
The actual help data, meaning the table of contents, index
43
keywords, or HTML documents, is contained in Qt compressed help
44
files. So, one such a help file represents usually one manual
45
or documentation set. Since most products are more comprehensive
46
and consist of a number of tools, one manual is rarely enough.
47
Instead, more manuals, which should be accessible at the same
48
time, exist. Ideally, it should also be possible to reference
49
certain points of interest of one manual to another.
50
Therefore, the Qt help system operates on help collection files,
51
which include any number of compressed help files.
52
53
However, having collection files to merge many documentation
54
sets may lead to some problems. For example, one index keyword
55
may be defined in different documentation sets. So, when only seeing
56
a keyword in the index and activating it, you cannot be sure that
57
the expected documentation will be shown. Therefore, the Qt
58
help system offers the possibility to filter the help contents
59
after certain attributes. This requires, however, that the
60
attributes have been assigned to the help contents before the
61
generation of the compressed help file.
62
63
As already mentioned, the Qt compressed help file contains all
64
data, so there is no need any longer to ship all the single HTML
65
files. Instead, only the compressed help file and, optionally, the
66
collection file have to be distributed. The collection file is
67
optional since any existing collection file, for example from an older
68
release, could be used.
69
70
So, in general, there are four files interacting with the help
71
system, two used for generating Qt help and two meant for
72
distribution:
73
74
\table
75
\header
76
\li Name
77
\li Extension
78
\li Brief Description
79
\row
80
\li \l {Qt Help Project}
81
\li .qhp
82
\li Contains the table of contents, indices, and references to the
83
actual documentation files (*.html). It also defines a unique
84
namespace for the documentation. This file is passed to the help
85
generator for creating a compressed help file.
86
87
\row
88
\li Qt Compressed Help
89
\li .qch
90
\li Contains all the information specified in the help project file
91
along with all the compressed documentation files.
92
93
\row
94
\li \l {Qt Help Collection Project}
95
\li .qhcp
96
\li An XML file that contains references to the compressed help
97
files that should be included in the help collection. This file
98
can be passed to the help generator for creating a help collection
99
file.
100
101
\row
102
\li Qt Help Collection
103
\li .qhc
104
\li The help collection file that QHelpEngine operates on. It can
105
contain references to any number of compressed help files as
106
well as additional information.
107
\endtable
108
109
\section1 Generating Qt Help
110
111
Building help files for the Qt help system assumes that the HTML
112
documentation files already exist.
113
114
Once the HTML documents are in place, a \l {Qt Help Project} file, with
115
an extension of \c .qhp, has to be created. After specifying all the relevant
116
information in this file, it needs to be compiled by calling:
117
118
\snippet doc_src_qthelp.qdoc 2
119
120
The file \e doc.qch contains all the HTML files in compressed
121
form along with the table of contents and index keywords. To
122
test if the generated file is correct, open Qt Assistant and
123
install the file in \uicontrol Settings > \uicontrol Documentation.
124
125
For the standard Qt source build, the .qhp file is generated and placed
126
in the same directory as the HTML pages.
127
128
\target Qt Help Collection Project
129
\section2 Creating a Qt Help Collection
130
131
The first step is to create a Qt Help Collection Project file.
132
Since a Qt help collection stores primarily references to
133
compressed help files, the project \e mycollection.qhcp file
134
looks unsurprisingly simple:
135
136
\snippet doc_src_qthelp.qdoc 3
137
138
For actually creating the collection file call:
139
140
\snippet doc_src_qthelp.qdoc 4
141
142
To generate both the compressed help and the collection file in one go,
143
modify the help collection project file so that it instructs the help
144
generator to create the compressed help first:
145
146
\snippet doc_src_qthelp.qdoc 5
147
148
Of course, it is possible to specify more than one file in the
149
\c generate or \c register section, so any number of compressed
150
help files can be generated and registered in one go.
151
152
\section1 Using QHelpEngine API
153
154
QHelpEngine allows embedding the help contents directly in an
155
application.
156
157
Instead of showing the help in an external application such as a
158
web browser, it is also possible to embed the online help in
159
the application. The contents can then be retrieved via the
160
QHelpEngine class and can be displayed in nearly any form.
161
Showing the help in a QTextBrowser is probably the most common way, but
162
embedding it in What's This help is also perfectly possible.
163
164
Retrieving help data from the file engine does not involve a
165
lot of code. The first step is to create an instance of the
166
help engine. Then we ask the engine for the links assigned to
167
the identifier, in this case \c MyDialog::ChangeButton. If a link
168
was found, meaning at least one help document exists on this topic,
169
we get the actual help contents by calling QHelpEngineCore::fileData() and
170
display the document to the user.
171
172
\snippet doc_src_qthelp.cpp 6
173
174
For further information on how to use the API, have a look at
175
the QHelpEngine class reference.
176
*/
177
178
/*!
179
\page qthelpproject.html
180
\title Qt Help Project
181
182
A Qt help project collects all data necessary to generate a
183
compressed help file. Along with the actual help data, like
184
the table of contents, index keywords and help documents, it
185
contains some extra information like a namespace to identify
186
the help file. One help project stands for one documentation set,
187
for example the \l{qmake Manual}.
188
189
\section1 Qt Help Project File Format
190
191
The file format is XML-based. For a better understanding of
192
the format we will discuss the following example:
193
194
\snippet doc_src_qthelp.qdoc 7
195
196
\section2 Namespace
197
198
To enable the QHelpEngine to retrieve the proper documentation to
199
a given link, every documentation set has to have a unique
200
identifier. A unique identifier also makes it possible for the
201
help collection to keep track of a documentation set without relying
202
on its file name. The Qt help system uses a namespace as identifier
203
which is defined by the mandatory namespace tags. In the example
204
above, the namespace is "mycompany.com.myapplication.1.0".
205
206
\target Virtual Folders
207
\section2 Virtual Folders
208
209
Having a namespace for every documentation set naturally means that
210
the documentation sets are quite separated. From the help engine's
211
point of view, this is beneficial. However, from the writer's view
212
it is often desirable to cross reference certain topics from one
213
manual to another without having to specify absolute links. To
214
solve this problem, the help system introduced the concept of
215
virtual folders.
216
217
A virtual folder will become the root directory of all files
218
referenced in a compressed help file. When two documentation sets
219
share the same virtual folder, they can use relative paths when
220
defining hyperlinks pointing to each other. If a file is contained
221
in both documentation sets, the one from the current set has
222
precedence over the other.
223
224
\snippet doc_src_qthelp.qdoc 8
225
226
The above example specifies \e doc as virtual folder. If another
227
manual specifies the same folder, for example for a small helper
228
tool \e {My Application}, it is sufficient to write
229
\e {doc.html#section1} to reference the first section in the
230
\e {My Application} manual.
231
232
The virtual folder tag is mandatory and the folder name must not
233
contain any slashes (/).
234
235
\target Filter Section
236
\section2 Filter Section
237
238
A filter section contains the actual documentation. A Qt help project
239
file may contain more than one filter section. Every filter section
240
consists of the table of contents, the keywords, and the files list.
241
In theory all parts are optional but not specifying anything there will
242
result in an empty documentation set.
243
244
\section3 Table of Contents
245
246
\snippet doc_src_qthelp.qdoc 11
247
248
One section tag represents one item in the table of contents. The
249
sections can be nested to any degree, but from a user's perspective
250
it should not be more than four or five levels. A section is defined
251
by its title and reference. The reference, like all file references in a Qt
252
help project, are relative to the help project file itself.
253
\note The referenced files must be in the same directory as the help
254
project file (or in a subdirectory). An absolute file path is not supported
255
either.
256
257
\section3 Keywords
258
259
\snippet doc_src_qthelp.qdoc 12
260
261
The keyword section lists all keywords of this filter section. A
262
keyword consists basically of a name and a file reference. If the
263
attribute \e name is used, the keyword specified there will appear in the
264
visible index. That is, it will be accessible through the QHelpIndexModel
265
class. If \e id is used, the keyword does not appear in the index and is
266
only accessible via \l QHelpEngineCore::documentsForIdentifier(). \e name
267
and \e id can be specified at the same time.
268
269
\section3 Files
270
271
\snippet doc_src_qthelp.qdoc 13
272
273
Finally, the actual documentation files have to be listed. Make sure
274
that all files necessary to display the help are mentioned. That is,
275
stylesheets or similar files need to be listed as well. The files, like all
276
file references in a Qt help project, are relative to the help project file
277
itself. As the example shows, files (but not directories) can also be
278
specified as patterns using wildcards. All listed files will be compressed
279
and written to the Qt compressed help file. So, in the end, one single Qt
280
help file contains all documentation files along with the contents and
281
indices. \note The referenced files must be inside the same directory
282
as the help project file (or in a subdirectory). An absolute file path
283
is not supported either.
284
*/
qttools
src
assistant
help
doc
src
qthelp.qdoc
Generated on Sat Sep 21 2024 01:06:09 for Qt by
1.12.0