1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\if !defined(ASSISTANT_INTERNAL)
\contentspage {Qt Assistant Manual}{Contents}
\previouspage Qt Assistant Manual
\endif
\page assistant-quick-guide.html
\nextpage Using Qt Assistant
\title Qt Assistant Quick Guide
Once you have installed Qt, you can start Qt Assistant in the same way as
any other application on the development host.
The \QA main window contains a sidebar (1) with navigation windows for:
\list
\li Viewing a list of documents in Qt help format that are installed on
the development host.
\li Managing bookmarks.
\li Searching for keywords in the index.
\li Searching for information using a free text search function.
\li Switching between open topics.
\endlist
The selected topic in the selected document is displayed in the
\b Documentation window (2).
\image assistant-assistant.png
Click the \gui Previous and \gui Next toolbar buttons (3) to navigate within
the topics you have visited.
\section1 Managing Bookmarks
\image assistant-bookmarks.png
To bookmark topics of particular interest, select \gui Bookmarks >
\gui {Add Bookmark} (or press \key{Ctrl+B}). A bookmark for the
page that is currently showing in the \gui Documentation window is added.
You can view and manage bookmarks in the \gui Bookmarks window.
Double-click a bookmark to open the topic in the \gui Documentation window.
You can also right-click the bookmark and select \gui{Show Bookmark} in the
context menu.
To rename or delete the highlighted bookmark, select \gui {Rename Bookmark}
or \gui {Delete Bookmark} in the context menu.
\section1 Searching for Keywords
\image assistant-index.png
To perform an index search, click the \gui{Index} tab on the sidebar
(or press \key{Alt+I}). In the \gui{Look For} field, enter the search term.
As you type, words are found and highlighted in a list beneath the field.
If the highlighted text matches what you are
looking for, double-click it or press \key{Enter}. The
\gui Documentation window displays the relevant topic. You rarely have
to type in the whole word before \QA finds a match. Note that for some
words there may be more than one possible topic that is relevant.
\section1 Using Free Text Search
\image assistant-search.png
\QA also provides full text searching for finding specific words in the
documentation. To activate the full text search, either press \key(Alt+S)
or click the \gui{Search} tab on the sidebar. Then enter the term you are
looking for and click \gui{Search}. All documents containing the specified
term are listed.
*/
/*!
\if !defined(ASSISTANT_INTERNAL)
\contentspage {Qt Assistant Manual}{Contents}
\nextpage Customizing Qt Assistant
\endif
\page assistant-details.html
\title Using Qt Assistant
\previouspage Qt Assistant Quick Guide
\image assistant-dockwidgets.png
You can read documentation in the \gui Documentation window. To open a topic
in a new tab, right click it in the \gui Contents window to open a context
menu and select \gui {Open Link in New Tab}. All open topics are listed in
the \gui {Open Pages} window. Select a topic to view it in the
\gui Documentation window.
If you want the \gui{Documentation} window to use as much space as possible,
you can easily group, move or hide the sidebar windows. To group the windows,
drag one on top of the other and release the mouse. If one or all sidebar
windows are not shown, select keyboard shortcuts to display them. You can
view the keyboard shortcuts in the \gui View menu.
The sidebar windows can be docked into the main window, so you can drag them
to the top, left, right or bottom of the main window, or you can
drag them outside \QA to float them as independent windows.
To change the font family and font sizes of the browser window displaying
the documentation or the application itself, select \gui Edit >
\gui Preferences > \gui Fonts.
\image assistant-preferences-fonts.png
To temporarily increase or decrease the font size in the \gui Documentation
window, select \gui View > \gui {Zoom in} or \gui {Zoom out}. To reset the
font size, select \gui View > \gui {Normal Size}.
To navigate between pages, select \gui Go > \gui Previous or \gui Next. This
takes you to the previous or next page in the history. To return to the home
page, select \gui Go > \gui Home. To specify the home page, select
\gui Edit > \gui Preferences > \gui Options.
To synchronize the \gui{Contents} window with the page currently shown in
the \gui{Documentation} window, select \gui Go >
\gui {Sync with Table of Contents}.
The address toolbar provides a fast way to enter a specific URL for a
documentation file. To show the address toolbar, select \gui View >
\gui Toolbars > \gui {Address Toolbar}.
\section1 Searching from Page Contents
To find text on the current page, select \gui Edit > \gui {Find in Text}.
Enter the search term in the field. The search is incremental, meaning that
the most relevant result is shown as you enter characters into the field.
If you select the \gui{Case sensitive} checkbox, the search considers the
case of the search term. For example, if you search for \b spin, it matches
\b spin but not \b Spin.
To search forwards or backwards from your current position on the page,
click \gui Previous or \gui Next.
To hide the find control, either click \gui Close or press \key Esc.
\section1 Full Text Searching
\img assistant-search.png
\QA provides a powerful full text search engine. You can search for certain
words or text in the \gui Search window. Enter the text you want to look for
and press \key{Enter} or click \gui{Search}. The search is not case sensitive.
For example, \b Foo, \b fOo and \b FOO are all treated as the same.
You can create complex queries using the
\l{https://sqlite.org/fts5.html#full_text_query_syntax}{FTS query syntax}.
The following are examples of common search patterns:
\list
\li \c deep -- lists all the documents that contain the word \b deep
\li \c{deep*} -- lists all the documents that contain a word beginning
with \b deep
\li \c{deep copy} -- lists all documents that contain both \b deep \e
and \b copy
\li \c{"deep copy"} -- list all documents that contain the phrase
\b {deep copy}
\endlist
The list of documents found is ordered according to the number of
occurrences of the search text which they contain, with those containing
the highest number of occurrences appearing first. Simply click any
document in the list to display it in the \gui{Documentation} window.
If the documentation has changed \mdash for example, if documents have been added
or removed \mdash \QA will index them again.
\section1 Filtering Help Contents
\QA allows you to install any kind of documentation as long as it is organized
in Qt compressed help files (*.qch). For example, you can view
Qt reference documentation for several Qt versions at the same time. In many
respects, this is very convenient since only one version of \QA is needed.
However, at the same time it becomes more complicated when performing tasks like
searching the index because most keywords are defined in more than one Qt
version. This means that \QA will always ask the user to choose which one
should be displayed.
We use documentation filters to solve this issue. A filter is identified by its
name, and contains a list of filter attributes. An attribute is just a string and
can be freely chosen. Attributes are defined by the documentation itself,
which means that every documentation set usually has one or more attributes.
For example, the \QA documentation defines the attributes \c {assistant} and
\c{tools}, whereas \QD defines \c{designer} and \c{tools}.
The filter to display all tools would then define only the attribute
\c{tools} since this attribute is part of both documentation sets.
Adding the attribute \c{assistant} to the filter would then only show \QA
documentation since the \QD documentation does not contain this
attribute. Having an empty list of attributes in a filter will match all
documentation. That is, it is equivalent to requesting unfiltered documentation.
To create and remove documentation filters, select \gui Edit >
\gui Preferences > \gui Filters.
\image assistant-preferences-filters.png
To add a new filter, click \gui Add,
specify a filter name, and click \gui OK. Then select the filter attributes
in the \gui Attributes field.
To delete a filter, select it and click \gui Remove.
The filter toolbar allows you to apply a filter to the currently installed
documentation. To show the filter toolbar, select \gui View > \gui Toolbars
> \gui {Filter Toolbar}.
\section1 Adding Documentation
To install and remove compressed help files, select \gui Edit >
\gui Preferences > \gui Documentation.
\image assistant-preferences-documentation.png
Click the \gui{Install} button and
choose the path of the compressed help file (*.qch) you would like to install.
To delete a help file, select a documentation set in the list and click
\gui{Remove}.
\section1 Specifying Home Page
To specify the homepage \QA displays when you click the \gui{Home} button,
select \gui Edit > \gui Preferences > \gui Options.
\image assistant-preferences-options.png
Enter the URL of the home page or select \gui{Current Page} to set the
currently displayed page as your home page. To leave the home page blank,
select \gui {Blank page}. Select \gui{Restore to default} to reset your home
page to the default home page.
\section1 Using Command Line Options
\QA handles the following command line options:
\table
\header
\li Command Line Option
\li Brief Description
\row
\li -collectionFile <file.qhc>
\li Uses the specified collection file instead of the default one.
\row
\li -showUrl <URL>
\li Shows the document referenced by URL.
\row
\li -enableRemoteControl
\li Enables \QA to be remotely controlled.
\row
\li -show <widget>
\li Shows the specified sidebar window which can be "contents", "index",
"bookmarks" or "search".
\row
\li -hide <widget>
\li Hides the specified sidebar window which can be "contents", "index",
"bookmarks" or "search".
\row
\li -activate <widget>
\li Activates the specified sidebar window which can be "contents",
"index", "bookmarks" or "search".
\row
\li -register <doc.qch>
\li Registers the specified compressed help file in the given help
collection.
\row
\li -unregister <doc.qch>
\li Unregisters the specified compressed help file from the given
collection file.
\row
\li -remove-search-index
\li Purges the help search engine's index. This option is
useful in case the associated index files get corrupted.
\QA will re-index the documentation at the next start-up.
\row
\li -rebuild-search-index
\li Rebuilds the help search engine's index.
Note that this operation may take a while to finish.
\row
\li -setCurrentFilter <filter>
\li Sets the given filter as the active filter.
\row
\li -quiet
\li Does not show any error, warning or success messages.
\endtable
*/
|
