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
assistant-manual.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
\page qtassistant-index.html
6
\title Qt Assistant Manual
7
\ingroup qttools
8
9
\startpage {Qt Reference Pages}
10
\nextpage Qt Assistant Quick Guide
11
12
\keyword Qt Assistant
13
14
\QA is a tool for viewing on-line documentation in Qt help file format.
15
For more information about basic \QA functions, see
16
\l{Qt Assistant Quick Guide}.
17
18
Qt installations include a set of reference and tools documentation that
19
you can view in the Qt Creator IDE and in \QA. You can add custom
20
documentation to the set of documents displayed in the \QA main view. For
21
detailed information about all \QA functions, see \l{Using Qt Assistant}.
22
23
You can use \QA as the help viewer in your applications. You can display
24
your own documentation and customize \QA to look and feel like part of your
25
application. You can change the window title or icon, as well as menu texts
26
and actions. For more information, see \l{Customizing Qt Assistant}.
27
28
\section1 Table of Contents
29
30
\list
31
\li \l{Qt Assistant Quick Guide}
32
\li \l{Using Qt Assistant}
33
\li \l{Customizing Qt Assistant}
34
\li \l{Licenses and Attributions}
35
\endlist
36
*/
37
38
/*!
39
\page assistant-custom-help-viewer.html
40
\title Customizing Qt Assistant
41
42
\previouspage Using Qt Assistant
43
\nextpage Licenses and Attributions
44
45
Using \QA as custom help viewer requires more than just being able to
46
display custom documentation. It is equally important that the
47
appearance of \QA can be customized so that it is seen as a
48
application-specific help viewer rather than \QA. This is achieved by
49
changing the window title or icon, as well as some application-specific
50
menu texts and actions. For a complete list of possible customizations,
51
see \l{Creating a Custom Help Collection File}.
52
53
Another requirement of a custom help viewer is the ability to receive
54
actions or commands from the application it provides help for. This is
55
especially important when the application offers context sensitive help.
56
When used in this way, the help viewer may need to change its contents
57
depending on the state the application is currently in. This means that
58
the application has to communicate the current state to the help viewer.
59
For more information, see \l{Using Qt Assistant Remotely}.
60
61
The \l{Simple Text Viewer Example}{Simple Text Viewer} example uses the
62
techniques described in this document to show how to use \QA as a custom
63
help viewer for an application.
64
65
\warning In order to ship Qt Assistant in your application, it is crucial
66
that you include the sqlite plugin. For more information on how to include
67
plugins in your application, refer to the \l{Deploying Qt Applications}
68
{deployment documentation}.
69
70
\section1 Qt Help Collection Files
71
72
The first important point to know about \QA is that it stores all
73
settings related to its appearance \e and a list of installed
74
documentation in a help collection file. This means, when starting \QA
75
with different collection files, \QA may look totally different. This
76
complete separation of settings makes it possible to deploy \QA as a
77
custom help viewer for more than one application on one machine
78
without risk of interference between different instances of \QA.
79
80
To apply a certain help collection to \QA, specify the respective
81
collection file on the command line when starting it. For example:
82
83
\snippet doc_src_assistant-manual.qdoc 8
84
85
However, storing all settings in one collection file raises some problems.
86
The collection file is usually installed in the same directory as the
87
application itself, or one of its subdirectories. Depending on the
88
directory and the operating system, the user may not have any permissions
89
to modify this file which would happen when the user settings are stored.
90
Also, it may not even be possible to give the user write permissions, for
91
example when the file is located on a read-only medium like a CD-ROM.
92
93
Even if it is possible to give everybody the right to store their settings
94
in a globally available collection file, the settings from one user would
95
be overwritten by another user when exiting \QA.
96
97
To solve this dilemma, \QA creates user specific collection files which
98
are more or less copied from the original collection file. The user-specific
99
collection file will be saved in a subdirectory of the path returned by
100
QDesktopServices::AppDataLocation. The subdirectory, or \e{cache directory}
101
within this user-specific location, can be defined in the help collection
102
project file. For example:
103
104
\snippet doc_src_assistant-manual.qdoc 7
105
106
So, when calling
107
108
\snippet doc_src_assistant-manual.qdoc 8
109
110
\QA actually uses the collection file:
111
112
\snippet doc_src_assistant-manual.qdoc 9
113
114
There is no need ever to start \QA with the user specific collection
115
file. Instead, the collection file shipped with the application should
116
always be used. Also, when adding or removing documentation from the
117
collection file (see next section) always use the normal collection file.
118
\QA will take care of synchronizing the user collection files when the
119
list of installed documentation has changed.
120
121
\section1 Displaying Custom Documentation
122
123
Before \QA is able to show documentation, it has to know where it can
124
find the actual documentation files, meaning that it has to know the
125
location of the Qt compressed help file (*.qch). As already mentioned,
126
\QA stores references to the compressed help files in the currently used
127
collection file. So, when creating a new collection file you can list
128
all compressed help files \QA should display.
129
130
\snippet doc_src_assistant-manual.qdoc 5
131
132
Sometimes, depending on the application for which \QA acts as a
133
help viewer, more documentation needs to be added over time; for
134
example, when installing more application components or plugins.
135
This can be done manually in \QA by selecting \gui Edit > \gui Preferences
136
> \gui Documentation. However, this approach has the disadvantage
137
that every user has to do it manually to get access to the new
138
documentation.
139
140
The preferred way of adding documentation to an already existing collection
141
file is to use the \c{-register} command line flag of \QA. When starting
142
\QA with this flag, the documentation will be added and \QA will
143
exit right away displaying a message if the registration was successful
144
or not.
145
146
The search indexing will only index your custom *.html, *.htm,
147
and *.txt files.
148
149
\snippet doc_src_assistant-manual.qdoc 6
150
151
The \c{-quiet} flag can be passed on to \QA to prevent it from writing
152
out the status message.
153
154
\note \QA shows the documentation in the \gui Contents view in the same
155
order as it was registered.
156
157
158
\section1 Changing the Appearance of Qt Assistant
159
160
The appearance of \QA can be changed by passing different command line options
161
on startup. However, these command line options only allow to show or hide
162
specific widgets, like the contents or index view. Other customizations, such
163
as changing the application title or icon, or disabling the filter functionality,
164
can be done by creating a custom help collection file.
165
166
\section2 Creating a Custom Help Collection File
167
168
The help collection file (*.qhc) used by \QA is created when running the
169
\c qhelpgenerator tool on a help collection project file (*.qhcp).
170
The project file format is XML and it supports the following tags:
171
172
\table
173
\header
174
\li Tag
175
\li Brief Description
176
\row
177
\li \c{<title>}
178
\li Specifies a window title for \QA.
179
\row
180
\li \c{<homePage>}
181
\li Specifies the page to display when selecting \gui Home in the
182
\QA main window.
183
\row
184
\li \c{<startPage>}
185
\li Specifies the page to display initially when the help collection
186
is used.
187
\row
188
\li \c{<currentFilter>}
189
\li Specifies the filter that is initially used.
190
If this filter is not specified, the documentation will not be filtered. This has
191
no impact if only one documentation set is installed.
192
\row
193
\li \c{<applicationIcon>}
194
\li Describes an icon that will be used instead of the normal \QA
195
application icon. This is specified as a relative path from the directory
196
containing the collection file.
197
\row
198
\li \c{<enableFilterFunctionality>}
199
\li Enables or disables user accessible filter functionality,
200
making it possible to prevent the user from changing any filter when running \QA.
201
It does not mean that the internal filter functionality is completely disabled.
202
Set the value to \c{false} if you want to disable the filtering. If the filter
203
toolbar should be shown by default, set the attribute \c{visible} to \c{true}.
204
\row
205
\li \c{<enableDocumentationManager>}
206
\li Shows or hides the \gui Documentation tab in the \gui Preferences
207
dialog. Disabling the \gui Documentation tab allows you to limit
208
\QA to display a specific documentation set or make it impossible for the end user
209
to accidentally remove or install documentation. To hide the \gui Documentation tab,
210
set the tag value to \c{false}.
211
\row
212
\li \c{<enableAddressBar>}
213
\li Enables or disables the address bar functionality. By default it
214
is enabled. To disable it, set the tag value to \c{false}. If the
215
address bar functionality is enabled, the address bar can be shown by setting the
216
tag attribute \c{visible} to \c{true}.
217
\row
218
\li \c{<aboutMenuText>, <text>}
219
\li Lists localized versions for the \gui About menu item in the
220
\gui Help menu. For example, \gui {About Application}. The text is
221
specified within the \c{text} tags. The \c{language} attribute takes the two
222
letter language name. The text is used as the default text if no language
223
attribute is specified.
224
\row
225
\li \c{<aboutDialog>, <file>, <icon>}
226
\li Specifies the text for the \gui About dialog that can be opened
227
from the \gui Help menu. The text is taken from the
228
file in the \c{file} tags. It is possible to specify a different file or any
229
language. The icon defined by the \c{icon} tags is applied to any language.
230
\row
231
\li \c{<cacheDirectory>, <cacheDirectory base="collection">}
232
\li Specifies the cache directory that is used to store index files
233
needed for the full text search and a copy of the collection file.
234
The copy is needed because \QA stores all its settings in the
235
collection file, and therefore, it must be writable for the user.
236
The directory is specified as a relative path.
237
If the \c{base} attribute is set to "collection", the path is
238
relative to the directory the collection file resides in.
239
If the attribute is set to "default" or if it is missing,
240
the path is relative to the directory given by
241
QDesktopServices::AppDataLocation. The first form is useful for
242
collections that are used in a \e mobile way, such as carried around
243
on a USB stick.
244
\row
245
\li \c{<enableFullTextSearchFallback>}
246
\li Enables or disables the ability to fallback and use the full text
247
search if a keyword cannot be found in the index. This functionality
248
can be used while remote controlling \QA. To make it available for
249
remote control, set the tag value to \c{true}.
250
\endtable
251
252
In addition to those \QA specific tags, the tags for generating and registering
253
documentation can be used. See \l{Qt Help Collection Files} documentation for more information.
254
255
An example of a help collection file that uses all the available tags is shown below:
256
257
\snippet doc_src_assistant-manual.qdoc 1
258
259
To create the binary collection file, run the \c qhelpgenerator tool:
260
261
\snippet doc_src_assistant-manual.qdoc 10
262
263
To test the generated collection file, start \QA in the following way:
264
265
\snippet doc_src_assistant-manual.qdoc 8
266
267
\section1 Using Qt Assistant Remotely
268
269
Even though the help viewer is a standalone application, it will mostly
270
be launched by the application it provides help for. This approach
271
gives the application the possibility to ask for specific help contents
272
to be displayed as soon as the help viewer is started. Another advantage
273
with this approach is that the application can communicate with the
274
help viewer process and can therefore request other help contents to be
275
shown depending on the current state of the application.
276
277
So, to use \QA as the custom help viewer of your application, simply
278
create a QProcess and specify the path to the \QA executable. In order
279
to make \QA listen to your application, turn on its remote control
280
functionality by passing the \c{-enableRemoteControl} command line option.
281
282
The following example shows how this can be done:
283
284
\snippet doc_src_assistant-manual.qdoc 2
285
286
Once \QA is running, you can send commands by using the stdin channel of
287
the process. The code snippet below shows how to tell \QA to show a certain
288
page in the documentation.
289
290
\snippet doc_src_assistant-manual.qdoc 3
291
292
\note The trailing newline character is required to mark the end
293
of the input.
294
295
The following commands can be used to control \QA:
296
297
\table
298
\header
299
\li Command
300
\li Brief Description
301
\row
302
\li \c{show <Widget>}
303
\li Shows the sidebar window (dock widget) specified by <Widget>. If the widget
304
is already shown and this command is sent again, the widget will be
305
activated, meaning that it will be raised and given the input focus.
306
Possible values for <Widget> are "contents", "index", "bookmarks" or "search".
307
\row
308
\li \c{hide <Widget>}
309
\li Hides the dock widget specified by <Widget>. Possible values for
310
<Widget> are "contents", "index", "bookmarks" and "search".
311
\row
312
\li \c{setSource <Url>}
313
\li Displays the given <Url>. The URL can be absolute or relative
314
to the currently displayed page. If the URL is absolute, it has to
315
be a valid Qt help system URL. That is, starting with "qthelp://".
316
\row
317
\li \c{activateKeyword <Keyword>}
318
\li Inserts the specified <Keyword> into the line edit of the
319
index dock widget and activates the corresponding item in the
320
index list. If such an item has more than one link associated
321
with it, a topic chooser will be shown.
322
\row
323
\li \c{activateIdentifier <Id>}
324
\li Displays the help contents for the given <Id>. An ID is unique
325
in each namespace and has only one link associated to it, so the
326
topic chooser will never pop up.
327
\row
328
\li \c{syncContents}
329
\li Selects the item in the contents widget which corresponds to
330
the currently displayed page.
331
\row
332
\li \c{setCurrentFilter <filter>}
333
\li Selects the specified filter and updates the visual representation
334
accordingly.
335
\row
336
\li \c{expandToc <Depth>}
337
\li Expands the table of contents tree to the given depth. If depth
338
is 0, the tree will be collapsed completely. If depth is -1,
339
the tree will be expanded completely.
340
\row
341
\li \c{register <help file>}
342
\li Adds the given Qt compressed help file to the collection.
343
\row
344
\li \c{unregister <help file>}
345
\li Removes the given Qt compressed help file from the collection.
346
\endtable
347
348
If you want to send several commands within a short period of time, it is
349
recommended that you write only a single line to the stdin of the process
350
instead of one line for every command. The commands have to be separated by
351
a semicolon, as shown in the following example:
352
353
\snippet doc_src_assistant-manual.qdoc 4
354
*/
355
356
/*
357
\section2 Modifying \QA with Command Line Options
358
359
Different help collections can be shown by simply passing the help collection
360
path to \QA. For example:
361
362
\snippet doc_src_assistant-manual.qdoc 0
363
364
Other available options the can be passed on the command line.
365
366
\table
367
\header
368
\li Command Line Option
369
\li Brief Description
370
\row
371
\li -collectionFile <file.qhc>
372
\li Uses the specified collection file instead of the default one.
373
\row
374
\li -showUrl URL
375
\li Shows the document referenced by URL.
376
\row
377
\li -enableRemoteControl
378
\li Enables \QA to be remotly controlled.
379
\row
380
\li -show <widget>
381
\li Shows the specified dockwidget which can be "contents", "index",
382
"bookmarks" or "search".
383
\row
384
\li -hide <widget>
385
\li Hides the specified dockwidget which can be "contents", "index",
386
"bookmarks" or "search.
387
\row
388
\li -activate <widget>
389
\li Activates the specified dockwidget which can be "contents",
390
"index", "bookmarks" or "search.
391
\row
392
\li -register <doc.qch>
393
\li Registers the specified compressed help file in the given help
394
collection.
395
\row
396
\li -unregister <doc.qch>
397
\li Unregisters the specified compressed help file from the given
398
collection file.
399
\row
400
\li -quiet
401
\li Doesn't show any error, warning or success messages.
402
\endtable
403
*/
404
405
/*!
406
\page assistant-licenses.html
407
\title Licenses and Attributions
408
409
\previouspage Customizing Qt Assistant
410
411
\QA is available under commercial licenses from \l{The Qt Company}. In
412
addition, it is available under the \l{GNU General Public License, version 3}.
413
414
Furthermore, \QA \QtVersion may contain third party modules
415
under following permissive licenses:
416
417
\generatelist{groupsbymodule attributions-qtassistant-tools}
418
*/
qttools
src
assistant
assistant
doc
src
assistant-manual.qdoc
Generated on Sat Sep 21 2024 01:06:09 for Qt by
1.12.0