|
0
|
1 |
/****************************************************************************
|
|
|
2 |
**
|
|
|
3 |
** Copyright (C) 2009 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 |
\page assistant-manual.html
|
|
|
44 |
\title Qt Assistant Manual
|
|
|
45 |
\ingroup qttools
|
|
|
46 |
|
|
|
47 |
\startpage {index.html}{Qt Reference Documentation}
|
|
|
48 |
\nextpage Qt Assistant in More Detail
|
|
|
49 |
|
|
|
50 |
\keyword Qt Assistant
|
|
|
51 |
|
|
|
52 |
This document introduces \QA, a tool for presenting on-line
|
|
|
53 |
documentation. The document is divided into the following sections:
|
|
|
54 |
|
|
|
55 |
Table of contents:
|
|
|
56 |
|
|
|
57 |
\list
|
|
|
58 |
\o \l{The One-Minute Guide to Using Qt Assistant}
|
|
|
59 |
\o \l{Qt Assistant in More Detail}
|
|
|
60 |
\o \l{Using Qt Assistant as a Custom Help Viewer}
|
|
|
61 |
\endlist
|
|
|
62 |
|
|
|
63 |
\chapter The One-Minute Guide to Using Qt Assistant
|
|
|
64 |
|
|
|
65 |
Once you have installed Qt, \QA should be ready to run:
|
|
|
66 |
|
|
|
67 |
\list
|
|
|
68 |
\o On Windows, \QA is available as a menu option on the Qt menu.
|
|
|
69 |
\o On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory.
|
|
|
70 |
\o On Unix/Linux, open a terminal, type \c{assistant} and press \key{Enter}.
|
|
|
71 |
\endlist
|
|
|
72 |
|
|
|
73 |
When you start up \QA, you will be presented with a standard main window
|
|
|
74 |
application, with a menu bar and toolbar. Below these, on the left hand
|
|
|
75 |
side are navigation windows called \e{Contents}, \e{Index} and \e{Bookmarks}.
|
|
|
76 |
On the right, taking up most of the space, is the \e{Documentation} window.
|
|
|
77 |
By default, \QA loads the Qt reference documentation along with the manuals
|
|
|
78 |
of other Qt tools, like \QD or \QL.
|
|
|
79 |
|
|
|
80 |
\QA works in a similar way to a Web browser. If you click hyperlinks
|
|
|
81 |
(cross-references), the \e{Documentation} window will present the relevant
|
|
|
82 |
page. You can bookmark pages of particular interest and you can click the
|
|
|
83 |
\gui{Previous} and \gui{Next} toolbar buttons to navigate within the pages
|
|
|
84 |
you have visited.
|
|
|
85 |
|
|
|
86 |
Although \QA can be used just like a Web browser to navigate through
|
|
|
87 |
the documentation, \QA offers a powerful means of navigation that Web
|
|
|
88 |
browsers do not provide. \QA uses an advanced full text search engine
|
|
|
89 |
to index all the pages in each compressed help file so that you can
|
|
|
90 |
search for particular words and phrases.
|
|
|
91 |
|
|
|
92 |
To perform an index search, click the \gui{Index} tab on the Sidebar
|
|
|
93 |
(or press \key{Alt+I}). In the \gui{'Look For'} line edit enter a word;
|
|
|
94 |
e.g., 'homedirpath'. As you type, words are found and highlighted in a list
|
|
|
95 |
beneath the line edit. If the highlighted text matches what you're
|
|
|
96 |
looking for, double click it, (or press \key{Enter}) and the
|
|
|
97 |
\e{Documentation} window will display the relevant page. You rarely have
|
|
|
98 |
to type in the whole word before \QA finds a match. Note that for some
|
|
|
99 |
words there may be more than one possible page that is relevant.
|
|
|
100 |
|
|
|
101 |
\QA also provides full text searching for finding specific words in
|
|
|
102 |
the documentation. To activate the full text search, either press \key(Alt+S)
|
|
|
103 |
or click on the \gui{Search} tab in the \e{Documentation} window. Then
|
|
|
104 |
enter the term you're looking for and hit the \gui{Search} button. All
|
|
|
105 |
documents containing the specified term will then be listed in the list box
|
|
|
106 |
below.
|
|
|
107 |
*/
|
|
|
108 |
|
|
|
109 |
/*!
|
|
|
110 |
\page assistant-details.html
|
|
|
111 |
\title Qt Assistant in More Detail
|
|
|
112 |
|
|
|
113 |
\contentspage {Qt Assistant Manual}{Contents}
|
|
|
114 |
\previouspage Qt Assistant Manual
|
|
|
115 |
\nextpage Using Qt Assistant as a Custom Help Viewer
|
|
|
116 |
|
|
|
117 |
\tableofcontents
|
|
|
118 |
|
|
|
119 |
\img assistant-assistant.png
|
|
|
120 |
|
|
|
121 |
\section1 Command Line Options
|
|
|
122 |
|
|
|
123 |
\QA handles the following command line options:
|
|
|
124 |
|
|
|
125 |
\table
|
|
|
126 |
\header
|
|
|
127 |
\o Command Line Option
|
|
|
128 |
\o Brief Description
|
|
|
129 |
\row
|
|
|
130 |
\o -collectionFile <file.qhc>
|
|
|
131 |
\o Uses the specified collection file instead of the default one.
|
|
|
132 |
\row
|
|
|
133 |
\o -showUrl URL
|
|
|
134 |
\o Shows the document referenced by URL.
|
|
|
135 |
\row
|
|
|
136 |
\o -enableRemoteControl
|
|
|
137 |
\o Enables \QA to be remotly controlled.
|
|
|
138 |
\row
|
|
|
139 |
\o -show <widget>
|
|
|
140 |
\o Shows the specified dockwidget which can be "contents", "index",
|
|
|
141 |
"bookmarks" or "search".
|
|
|
142 |
\row
|
|
|
143 |
\o -hide <widget>
|
|
|
144 |
\o Hides the specified dockwidget which can be "contents", "index",
|
|
|
145 |
"bookmarks" or "search.
|
|
|
146 |
\row
|
|
|
147 |
\o -activate <widget>
|
|
|
148 |
\o Activates the specified dockwidget which can be "contents",
|
|
|
149 |
"index", "bookmarks" or "search.
|
|
|
150 |
\row
|
|
|
151 |
\o -register <doc.qch>
|
|
|
152 |
\o Registers the specified compressed help file in the given help
|
|
|
153 |
collection.
|
|
|
154 |
\row
|
|
|
155 |
\o -unregister <doc.qch>
|
|
|
156 |
\o Unregisters the specified compressed help file from the given
|
|
|
157 |
collection file.
|
|
|
158 |
\row
|
|
|
159 |
\o -setCurrentFilter filter
|
|
|
160 |
\o Sets the given filter as the active filter.
|
|
|
161 |
\row
|
|
|
162 |
\o -quiet
|
|
|
163 |
\o Doesn't show any error, warning or success messages.
|
|
|
164 |
\endtable
|
|
|
165 |
|
|
|
166 |
\section1 Tool Windows
|
|
|
167 |
|
|
|
168 |
\img assistant-dockwidgets.png
|
|
|
169 |
|
|
|
170 |
The tool windows provide four ways to navigate the documentation:
|
|
|
171 |
|
|
|
172 |
\list
|
|
|
173 |
\o The \gui{Contents} window presents a table of contents implemented as a
|
|
|
174 |
tree view for the documentation that is available. If you click an item,
|
|
|
175 |
its documentation will appear in the \e{Documentation} window. If you double
|
|
|
176 |
click an item or click on the control to the left of it, the item's sub-items
|
|
|
177 |
will appear. Click a sub-item to make its page appear in the \e{Documentation}
|
|
|
178 |
window. Click on the control next to an open item to hide its sub-items.
|
|
|
179 |
\o The \gui{Index} window is used to look up key words or phrases.
|
|
|
180 |
See \l{The One-Minute Guide to Using Qt Assistant} for how to use this
|
|
|
181 |
window.
|
|
|
182 |
\o The \gui{Bookmarks} window lists any bookmarks you have made. Double
|
|
|
183 |
click a bookmark to make its page appear in the \e{Documentation} window.
|
|
|
184 |
The \gui{Bookmarks} window provides a context menu with \gui{Show Item},
|
|
|
185 |
\gui{Delete Item} as well as \gui{Rename Item}. Click in the main menu
|
|
|
186 |
\menu{Bookmark|Add Bookmark...} (or press \key{Ctrl+B}) to bookmark the
|
|
|
187 |
page that is currently showing in the \e{Documentation} window. Right click
|
|
|
188 |
a bookmark in the list to rename or delete the highlighted bookmark.
|
|
|
189 |
\endlist
|
|
|
190 |
|
|
|
191 |
If you want the \gui{Documentation} window to use as much space as possible,
|
|
|
192 |
you can easily group, move or hide the tool windows. To group the windows,
|
|
|
193 |
drag one on top of the other and release the mouse. If one or all tool
|
|
|
194 |
windows are not shown, press \key{Alt+C}, \key{Alt+I} or \key{Alt+O} to show
|
|
|
195 |
the required window.
|
|
|
196 |
|
|
|
197 |
The tool windows can be docked into the main window, so you can drag them
|
|
|
198 |
to the top, left, right or bottom of \e{Qt Assistant's} window, or you can
|
|
|
199 |
drag them outside \QA to float them as independent windows.
|
|
|
200 |
|
|
|
201 |
\section1 Documentation Window
|
|
|
202 |
|
|
|
203 |
\img assistant-docwindow.png
|
|
|
204 |
|
|
|
205 |
The \gui{Documentation} window lets you create a tab for each
|
|
|
206 |
documentation page that you view. Click the \gui{Add Tab} button and a new
|
|
|
207 |
tab will appear with the page name as the tab's caption. This makes it
|
|
|
208 |
convenient to switch between pages when you are working with different
|
|
|
209 |
documentation. You can delete a tab by clicking the \gui{Close Tab} button
|
|
|
210 |
located on the right side of the \gui{Documentation} window.
|
|
|
211 |
|
|
|
212 |
\section1 Toolbars
|
|
|
213 |
|
|
|
214 |
\img assistant-toolbar.png
|
|
|
215 |
|
|
|
216 |
The main toolbar provides fast access to the most common actions.
|
|
|
217 |
|
|
|
218 |
\table
|
|
|
219 |
\header \o Action \o Description \o Menu Item \o Shortcut
|
|
|
220 |
\row \o \gui{Previous} \o Takes you to the previous page in the history.
|
|
|
221 |
\o \menu{Go|Previous} \o \key{Alt+Left Arrow}
|
|
|
222 |
\row \o \gui{Next} \o Takes you to the next page in the history.
|
|
|
223 |
\o \menu{Go|Next} \o \key{Alt+Right Arrow}
|
|
|
224 |
\row \o \gui{Home}
|
|
|
225 |
\o Takes you to the home page as specified in the Preferences Dialog.
|
|
|
226 |
\o \menu{Go|Home} \o \key{Ctrl+Home}.
|
|
|
227 |
\row \o \gui{Sync with Table of Contents}
|
|
|
228 |
\o Synchronizes the \gui{Contents} tool window with the page currently
|
|
|
229 |
shown in the \gui{Documentation} window.
|
|
|
230 |
\o \menu{Go|Sync with Table of Contents} \o
|
|
|
231 |
\row \o \gui{Copy} \o Copies any selected text to the clipboard.
|
|
|
232 |
\o \menu{Edit|Copy} \o \key{Ctrl+C}
|
|
|
233 |
\row \o \gui{Print} \o Opens the \gui{Print} dialog.
|
|
|
234 |
\o \menu{File|Print} \o \key{Ctrl+P}
|
|
|
235 |
\row \o \gui{Find in Text} \o Opens the \gui{Find Text} dialog.
|
|
|
236 |
\o \menu{Edit|Find in Text} \o \key{Ctrl+F}
|
|
|
237 |
\row \o \gui{Zoom in}
|
|
|
238 |
\o Increases the font size used to display text in the current tab.
|
|
|
239 |
\o \menu{View|Zoom in} \o \key{Ctrl++}
|
|
|
240 |
\row \o \gui{Zoom out}
|
|
|
241 |
\o Decreases the font size used to display text in the current tab.
|
|
|
242 |
\o \menu{View|Zoom out} \o \key{Ctrl+-}
|
|
|
243 |
\row \o \gui{Normal Size}
|
|
|
244 |
\o Resets the font size to its normal size in the current tab.
|
|
|
245 |
\o \menu{View|Normal Size} \o \key{Ctrl+0}
|
|
|
246 |
\endtable
|
|
|
247 |
|
|
|
248 |
\img assistant-address-toolbar.png
|
|
|
249 |
|
|
|
250 |
The address toolbar provides a fast way to enter a specific URL for a
|
|
|
251 |
documentation file. By default, the address toolbar is not shown, so it
|
|
|
252 |
has to be activated via \menu{View|Toolbars|Address Toolbar}.
|
|
|
253 |
|
|
|
254 |
\img assistant-filter-toolbar.png
|
|
|
255 |
|
|
|
256 |
The filter toolbar allows you to apply a filter to the currently installed
|
|
|
257 |
documentation. As with the address toolbar, the filter toolbar is not visible
|
|
|
258 |
by default and has to be activated via \menu{View|Toolbars|Filter Toolbar}.
|
|
|
259 |
|
|
|
260 |
\section1 Menus
|
|
|
261 |
|
|
|
262 |
\section2 File Menu
|
|
|
263 |
|
|
|
264 |
\list
|
|
|
265 |
\o \menu{File|Page Setup...} invokes a dialog allowing you to define
|
|
|
266 |
page layout properties, such as margin sizes, page orientation and paper size.
|
|
|
267 |
\o \menu{File|Print Preview...} provides a preview of the printed pages.
|
|
|
268 |
\o \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}.
|
|
|
269 |
\o \menu{File|New Tab} opens a new empty tab in the \gui{Documentation}
|
|
|
270 |
window.
|
|
|
271 |
\o \menu{File|Close Tab} closes the current tab of the
|
|
|
272 |
\gui{Documentation} window.
|
|
|
273 |
\o \menu{File|Exit} closes the \QA application.
|
|
|
274 |
\endlist
|
|
|
275 |
|
|
|
276 |
\section2 Edit Menu
|
|
|
277 |
|
|
|
278 |
\list
|
|
|
279 |
\o \menu{Edit|Copy} copies any selected text to the clipboard.
|
|
|
280 |
\o \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text}
|
|
|
281 |
control} at the lower end of the \gui{Documentation} window.
|
|
|
282 |
\o \menu{Edit|Find Next} looks for the next occurance of the specified
|
|
|
283 |
text in the \gui{Find Text} control.
|
|
|
284 |
\o \menu{Edit|Find Previous} looks for the previous occurance of
|
|
|
285 |
the specified text in the \l{#Find Text Control}{\gui{Find Text} control}.
|
|
|
286 |
\o \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}.
|
|
|
287 |
\endlist
|
|
|
288 |
|
|
|
289 |
\section2 View Menu
|
|
|
290 |
|
|
|
291 |
\list
|
|
|
292 |
\o \menu{View|Zoom in} increases the font size in the current tab.
|
|
|
293 |
\o \menu{View|Zoom out} decreases the font size in the current tab.
|
|
|
294 |
\o \menu{View|Normal Size} resets the font size in the current tab.
|
|
|
295 |
\o \menu{View|Contents} toggles the display of the \gui{Contents} tool window.
|
|
|
296 |
\o \menu{View|Index} toggles the display of the \gui{Index} tool window.
|
|
|
297 |
\o \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window.
|
|
|
298 |
\o \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window.
|
|
|
299 |
\endlist
|
|
|
300 |
|
|
|
301 |
\section2 Go Menu
|
|
|
302 |
|
|
|
303 |
\list
|
|
|
304 |
\o \menu{Go|Home} goes to the home page.
|
|
|
305 |
\o \menu{Go|Back} displays the previous page in the history.
|
|
|
306 |
\o \menu{Go|Forward} displays the next page in the history.
|
|
|
307 |
\o \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page.
|
|
|
308 |
\o \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window.
|
|
|
309 |
\o \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window.
|
|
|
310 |
\endlist
|
|
|
311 |
|
|
|
312 |
\section2 Bookmarks Menu
|
|
|
313 |
|
|
|
314 |
\list
|
|
|
315 |
\o \menu{Bookmarks|Add} adds the current page to the list of bookmarks.
|
|
|
316 |
\endlist
|
|
|
317 |
|
|
|
318 |
\section1 Dialogs
|
|
|
319 |
|
|
|
320 |
\section2 Print Dialog
|
|
|
321 |
|
|
|
322 |
This dialog is platform-specific. It gives access to various printer
|
|
|
323 |
options and can be used to print the document shown in the current tab.
|
|
|
324 |
|
|
|
325 |
\section2 Preferences Dialog
|
|
|
326 |
|
|
|
327 |
\img assistant-preferences-fonts.png
|
|
|
328 |
|
|
|
329 |
The \menu{Fonts} page allows you to change the font family and font sizes of the
|
|
|
330 |
browser window displaying the documentation or the application itself.
|
|
|
331 |
|
|
|
332 |
\img assistant-preferences-filters.png
|
|
|
333 |
|
|
|
334 |
The \menu{Filters} page lets you create and remove documentation
|
|
|
335 |
filters. To add a new filter, click the \gui{Add} button, specify a
|
|
|
336 |
filter name in the pop-up dialog and click \gui{OK}, then select
|
|
|
337 |
the filter attributes in the list box on the right hand side.
|
|
|
338 |
You can delete a filter by selecting it and clicking the \gui{Remove}
|
|
|
339 |
button.
|
|
|
340 |
|
|
|
341 |
\img assistant-preferences-documentation.png
|
|
|
342 |
|
|
|
343 |
The \menu{Documentation} page lets you install and remove compressed help
|
|
|
344 |
files. Click the \gui{Install} button and choose the path of the compressed
|
|
|
345 |
help file (*.qch) you would like to install.
|
|
|
346 |
To delete a help file, select a documentation set in the list and click
|
|
|
347 |
\gui{Remove}.
|
|
|
348 |
|
|
|
349 |
\img assistant-preferences-options.png
|
|
|
350 |
|
|
|
351 |
The \menu{Options} page lets you specify the homepage \QA will display when
|
|
|
352 |
you click the \gui{Home} button in \QA's main user interface. You can specify
|
|
|
353 |
the hompage by typing it here or clicking on one of the buttons below the
|
|
|
354 |
textbox. \gui{Current Page} sets the currently displayed page as your home
|
|
|
355 |
page while \gui{Restore to default} will reset your home page to the default
|
|
|
356 |
home page.
|
|
|
357 |
|
|
|
358 |
\section1 Find Text Control
|
|
|
359 |
|
|
|
360 |
This control is used to find text in the current page. Enter the text you want
|
|
|
361 |
to find in the line edit. The search is incremental, meaning that the most
|
|
|
362 |
relevant result is shown as you enter characters into the line edit.
|
|
|
363 |
|
|
|
364 |
If you check the \gui{Whole words only} checkbox, the search will only consider
|
|
|
365 |
whole words; for example, if you search for "spin" with this checkbox checked it will
|
|
|
366 |
not match "spinbox", but will match "spin". If you check the \gui{Case sensitive}
|
|
|
367 |
checkbox then, for example, "spin" will match "spin" but not "Spin". You can
|
|
|
368 |
search forwards or backwards from your current position in the page by clicking
|
|
|
369 |
the \gui{Previous} or \gui{Next} buttons. To hide the find control, either click the
|
|
|
370 |
\gui{Close} button or hit the \key{Esc} key.
|
|
|
371 |
|
|
|
372 |
\section1 Filtering Help Contents
|
|
|
373 |
|
|
|
374 |
\QA allows you to install any kind of documentation as long as it is organized
|
|
|
375 |
in Qt compressed help files (*.qch). For example, it is possible to install the
|
|
|
376 |
Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. In many
|
|
|
377 |
respects, this is very convenient since only one version of \QA is needed.
|
|
|
378 |
However, at the same time it becomes more complicated when performing tasks like
|
|
|
379 |
searching the index because nearly every keyword is defined in Qt 4.4.0 as well
|
|
|
380 |
as in Qt 4.4.1. This means that \QA will always ask the user to choose which one
|
|
|
381 |
should be displayed.
|
|
|
382 |
|
|
|
383 |
We use documentation filters to solve this issue. A filter is identified by its
|
|
|
384 |
name, and contains a list of filter attributes. An attribute is just a string and
|
|
|
385 |
can be freely chosen. Attributes are defined by the documentation itself, this
|
|
|
386 |
means that every documentation set usually has one or more attributes.
|
|
|
387 |
|
|
|
388 |
For example, the Qt 4.4.0 \QA documentation defines the attributes \c {assistant},
|
|
|
389 |
\c{tools} and \c{4.4.0}, \QD defines \c{designer}, \c{tools} and \c{4.4.0}.
|
|
|
390 |
The filter to display all tools would then define only the attribute
|
|
|
391 |
\c{tools} since this attribute is part of both documentation sets.
|
|
|
392 |
Adding the attribute \c{assistant} to the filter would then only show \QA
|
|
|
393 |
documentation since the \QD documentation does not contain this
|
|
|
394 |
attribute. Having an empty list of attributes in a filter will match all
|
|
|
395 |
documentation; i.e., it is equivalent to requesting unfiltered documentation.
|
|
|
396 |
|
|
|
397 |
\section1 Full Text Searching
|
|
|
398 |
|
|
|
399 |
\img assistant-search.png
|
|
|
400 |
|
|
|
401 |
\QA provides a powerful full text search engine. To search
|
|
|
402 |
for certain words or text, click the \gui{Search} tab in the \gui{Documentation}
|
|
|
403 |
window. Then enter the text you want to look for and press \key{Enter}
|
|
|
404 |
or click the \gui{Search} button. The search is not case sensitive, so,
|
|
|
405 |
for example, Foo, fOo and FOO are all treated as the same. The following are
|
|
|
406 |
examples of common search patterns:
|
|
|
407 |
|
|
|
408 |
\list
|
|
|
409 |
\o \c deep -- lists all the documents that contain the word 'deep'
|
|
|
410 |
\o \c{deep*} -- lists all the documents that contain a word beginning
|
|
|
411 |
with 'deep'
|
|
|
412 |
\o \c{deep copy} -- lists all documents that contain both 'deep' \e
|
|
|
413 |
and 'copy'
|
|
|
414 |
\o \c{"deep copy"} -- list all documents that contain the phrase 'deep copy'
|
|
|
415 |
\endlist
|
|
|
416 |
|
|
|
417 |
It is also possible to use the \gui{Advanced search} to get more flexibility.
|
|
|
418 |
You can specify some words so that hits containing these are excluded from the
|
|
|
419 |
result, or you can search for an exact phrase. Searching for similar words will
|
|
|
420 |
give results like these:
|
|
|
421 |
|
|
|
422 |
\list
|
|
|
423 |
\o \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString}
|
|
|
424 |
\o \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString}
|
|
|
425 |
\o \c{QStrin} -- lists all the documents with titles that are similar, such as \c{QString}
|
|
|
426 |
\endlist
|
|
|
427 |
|
|
|
428 |
Options can be combined to improve the search results.
|
|
|
429 |
|
|
|
430 |
The list of documents found is ordered according to the number of
|
|
|
431 |
occurrences of the search text which they contain, with those containing
|
|
|
432 |
the highest number of occurrences appearing first. Simply click any
|
|
|
433 |
document in the list to display it in the \gui{Documentation} window.
|
|
|
434 |
|
|
|
435 |
If the documentation has changed \mdash for example, if documents have been added
|
|
|
436 |
or removed \mdash \QA will index them again.
|
|
|
437 |
|
|
|
438 |
*/
|
|
|
439 |
|
|
|
440 |
/*!
|
|
|
441 |
\page assistant-custom-help-viewer.html
|
|
|
442 |
\title Using Qt Assistant as a Custom Help Viewer
|
|
|
443 |
|
|
|
444 |
\contentspage {Qt Assistant Manual}{Contents}
|
|
|
445 |
\previouspage Qt Assistant in More Detail
|
|
|
446 |
|
|
|
447 |
Using \QA as custom help viewer requires more than just being able to
|
|
|
448 |
display custom documentation. It is equally important that the
|
|
|
449 |
appearance of \QA can be customized so that it is seen as a
|
|
|
450 |
application-specific help viewer rather than \QA. This is achieved by
|
|
|
451 |
changing the window title or icon, as well as some application-specific
|
|
|
452 |
menu texts and actions. The complete list of possible customizations
|
|
|
453 |
can be found in the \l{Creating a Custom Help Collection File} section.
|
|
|
454 |
|
|
|
455 |
Another requirement of a custom help viewer is the ability to receive
|
|
|
456 |
actions or commands from the application it provides help for. This is
|
|
|
457 |
especially important when the application offers context sensitive help.
|
|
|
458 |
When used in this way, the help viewer may need to change its contents
|
|
|
459 |
depending on the state the application is currently in. This means that
|
|
|
460 |
the application has to communicate the current state to the help viewer.
|
|
|
461 |
The section about \l{Using Qt Assistant Remotely} explains how this can
|
|
|
462 |
be done.
|
|
|
463 |
|
|
|
464 |
\tableofcontents
|
|
|
465 |
|
|
|
466 |
The \l{Simple Text Viewer Example}{Simple Text Viewer} example uses the
|
|
|
467 |
techniques described in this document to show how to use \QA as a custom
|
|
|
468 |
help viewer for an application.
|
|
|
469 |
|
|
|
470 |
\warning In order to ship Qt Assistant in your application, it is crucial
|
|
|
471 |
that you include the sqlite plugin. For more information on how to include
|
|
|
472 |
plugins in your application, refer to the \l{Deploying Qt Applications}
|
|
|
473 |
{deployment documentation}.
|
|
|
474 |
|
|
|
475 |
\section1 Qt Help Collection Files
|
|
|
476 |
|
|
|
477 |
The first important point to know about \QA is that it stores all
|
|
|
478 |
settings related to its appearance \e and a list of installed
|
|
|
479 |
documentation in a help collection file. This means, when starting \QA
|
|
|
480 |
with different collection files, \QA may look totally different. This
|
|
|
481 |
complete separation of settings makes it possible to deploy \QA as a
|
|
|
482 |
custom help viewer for more than one application on one machine
|
|
|
483 |
without risk of interference between different instances of \QA.
|
|
|
484 |
|
|
|
485 |
To apply a certain help collection to \QA, specify the respective
|
|
|
486 |
collection file on the command line when starting it. For example:
|
|
|
487 |
|
|
|
488 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
|
|
|
489 |
|
|
|
490 |
However, storing all settings in one collection file raises some problems.
|
|
|
491 |
The collection file is usually installed in the same directory as the
|
|
|
492 |
application itself, or one of its subdirectories. Depending on the
|
|
|
493 |
directory and the operating system, the user may not have any permissions
|
|
|
494 |
to modify this file which would happen when the user settings are stored.
|
|
|
495 |
Also, it may not even be possible to give the user write permissions;
|
|
|
496 |
e.g., when the file is located on a read-only medium like a CD-ROM.
|
|
|
497 |
|
|
|
498 |
Even if it is possible to give everybody the right to store their settings
|
|
|
499 |
in a globally available collection file, the settings from one user would
|
|
|
500 |
be overwritten by another user when exiting \QA.
|
|
|
501 |
|
|
|
502 |
To solve this dilemma, \QA creates user specific collection files which
|
|
|
503 |
are more or less copied from the original collection file. The user-specific
|
|
|
504 |
collection file will be saved in a subdirectory of the path returned by
|
|
|
505 |
QDesktopServices::DataLocation. The subdirectory, or \e{cache directory}
|
|
|
506 |
within this user-specific location, can be defined in the help collection
|
|
|
507 |
project file. For example:
|
|
|
508 |
|
|
|
509 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 7
|
|
|
510 |
|
|
|
511 |
So, when calling
|
|
|
512 |
|
|
|
513 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
|
|
|
514 |
|
|
|
515 |
\QA actually uses the collection file:
|
|
|
516 |
|
|
|
517 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 9
|
|
|
518 |
|
|
|
519 |
There is no need ever to start \QA with the user specific collection
|
|
|
520 |
file. Instead, the collection file shipped with the application should
|
|
|
521 |
always be used. Also, when adding or removing documentation from the
|
|
|
522 |
collection file (see next section) always use the normal collection file.
|
|
|
523 |
\QA will take care of synchronizing the user collection files when the
|
|
|
524 |
list of installed documentation has changed.
|
|
|
525 |
|
|
|
526 |
\section1 Displaying Custom Documentation
|
|
|
527 |
|
|
|
528 |
Before \QA is able to show documentation, it has to know where it can
|
|
|
529 |
find the actual documentation files, meaning that it has to know the
|
|
|
530 |
location of the Qt compressed help file (*.qch). As already mentioned,
|
|
|
531 |
\QA stores references to the compressed help files in the currently used
|
|
|
532 |
collection file. So, when creating a new collection file you can list
|
|
|
533 |
all compressed help files \QA should display.
|
|
|
534 |
|
|
|
535 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 5
|
|
|
536 |
|
|
|
537 |
Sometimes, depending on the application for which \QA acts as a
|
|
|
538 |
help viewer, more documentation needs to be added over time; for
|
|
|
539 |
example, when installing more application components or plugins.
|
|
|
540 |
This can be done manually by starting \QA, opening the \gui{Edit|Preferences}
|
|
|
541 |
dialog and navigating to the \gui{Documentation} tab page. Then click
|
|
|
542 |
the \gui{Add...} button, select a Qt compressed help file (*.qch)
|
|
|
543 |
and press \gui{Open}. However, this approach has the disadvantage
|
|
|
544 |
that every user has to do it manually to get access to the new
|
|
|
545 |
documentation.
|
|
|
546 |
|
|
|
547 |
The prefered way of adding documentation to an already existing collection
|
|
|
548 |
file is to use the \c{-register} command line flag of \QA. When starting
|
|
|
549 |
\QA with this flag, the documentation will be added and \QA will
|
|
|
550 |
exit right away displaying a message if the registration was successful
|
|
|
551 |
or not.
|
|
|
552 |
|
|
|
553 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 6
|
|
|
554 |
|
|
|
555 |
The \c{-quiet} flag can be passed on to \QA to prevent it from writing
|
|
|
556 |
out the status message.
|
|
|
557 |
|
|
|
558 |
\bold{Note:} \QA will show the documentation in the contents view in the same
|
|
|
559 |
order as it was registered.
|
|
|
560 |
|
|
|
561 |
|
|
|
562 |
\section1 Changing the Appearance of Qt Assistant
|
|
|
563 |
|
|
|
564 |
The appearance of \QA can be changed by passing different command line options
|
|
|
565 |
on startup. However, these command line options only allow to show or hide
|
|
|
566 |
specific widgets, like the contents or index view. Other customizations, such
|
|
|
567 |
as changing the application title or icon, or disabling the filter functionality,
|
|
|
568 |
can be done by creating a custom help collection file.
|
|
|
569 |
|
|
|
570 |
\section2 Creating a Custom Help Collection File
|
|
|
571 |
|
|
|
572 |
The help collection file (*.qhc) used by \QA is created when running the
|
|
|
573 |
\c qcollectiongenerator tool on a help collection project file (*.qhcp).
|
|
|
574 |
The project file format is XML and supports the following tags:
|
|
|
575 |
|
|
|
576 |
\table
|
|
|
577 |
\header
|
|
|
578 |
\o Tag
|
|
|
579 |
\o Brief Description
|
|
|
580 |
\row
|
|
|
581 |
\o \c{<title>}
|
|
|
582 |
\o This property is used to specify a window title for \QA.
|
|
|
583 |
\row
|
|
|
584 |
\o \c{<homePage>}
|
|
|
585 |
\o This tag specifies which page should be display when
|
|
|
586 |
pressing the home button in \QA's main user interface.
|
|
|
587 |
\row
|
|
|
588 |
\o \c{<startPage>}
|
|
|
589 |
\o This tag specifies which page \QA should initially
|
|
|
590 |
display when the help collection is used.
|
|
|
591 |
\row
|
|
|
592 |
\o \c{<currentFilter>}
|
|
|
593 |
\o This tag specifies the \l{Qt Assistant in More Detail#Preferences Dialog}{filter}
|
|
|
594 |
that is initially used.
|
|
|
595 |
If this filter is not specified, the documentation will not be filtered. This has
|
|
|
596 |
no impact if only one documentation set is installed.
|
|
|
597 |
\row
|
|
|
598 |
\o \c{<applicationIcon>}
|
|
|
599 |
\o This tag describes an icon that will be used instead of the normal \QA
|
|
|
600 |
application icon. This is specified as a relative path from the directory
|
|
|
601 |
containing the collection file.
|
|
|
602 |
\row
|
|
|
603 |
\o \c{<enableFilterFunctionality>}
|
|
|
604 |
\o This tag is used to enable or disable user accessible filter functionality,
|
|
|
605 |
making it possible to prevent the user from changing any filter when running \QA.
|
|
|
606 |
It does not mean that the internal filter functionality is completely disabled.
|
|
|
607 |
Set the value to \c{false} if you want to disable the filtering. If the filter
|
|
|
608 |
toolbar should be shown by default, set the attribute \c{visible} to \c{true}.
|
|
|
609 |
\row
|
|
|
610 |
\o \c{<enableDocumentationManager>}
|
|
|
611 |
\o This tag is used to specify whether the documentation manager should be shown
|
|
|
612 |
in the preferences dialog. Disabling the Documentation Manager allows you to limit
|
|
|
613 |
\QA to display a specific documentation set or make it impossible for the end user
|
|
|
614 |
to accidentally remove or install documentation. To hide the documentation manager,
|
|
|
615 |
set the tag value to \c{false}.
|
|
|
616 |
\row
|
|
|
617 |
\o \c{<enableAddressBar>}
|
|
|
618 |
\o This tag describes if the address bar can be shown. By default it is
|
|
|
619 |
enabled; if you want to disable it set the tag value to \c{false}. If the
|
|
|
620 |
address bar functionality is enabled, the address bar can be shown by setting the
|
|
|
621 |
tag attribute \c{visible} to \c{true}.
|
|
|
622 |
\row
|
|
|
623 |
\o \c{<aboutMenuText>, <text>}
|
|
|
624 |
\o The \c{aboutMenuText} tag lists texts for different languages which will
|
|
|
625 |
later appear in the \menu{Help} menu; e.g., "About Application". A text is
|
|
|
626 |
specified within the \c{text} tags; the \c{language} attribute takes the two
|
|
|
627 |
letter language name. The text is used as the default text if no language
|
|
|
628 |
attribute is specified.
|
|
|
629 |
\row
|
|
|
630 |
\o \c{<aboutDialog>, <file>, <icon>}
|
|
|
631 |
\o The \c{aboutDialog} tag can be used to specify the text for the \gui{About}
|
|
|
632 |
dialog that can be opened from the \menu{Help} menu. The text is taken from the
|
|
|
633 |
file in the \c{file} tags. It is possible to specify a different file or any
|
|
|
634 |
language. The icon defined by the \c{icon} tags is applied to any language.
|
|
|
635 |
\row
|
|
|
636 |
\o \c{<cacheDirectory>}
|
|
|
637 |
\o Specified as a path relative to the directory given by
|
|
|
638 |
QDesktopServices::DataLocation, the cache path is used to store index files
|
|
|
639 |
needed for the full text search and a copy of the collection file.
|
|
|
640 |
The copy is needed because \QA stores all its settings in the collection file;
|
|
|
641 |
i.e., it must be writable for the user.
|
|
|
642 |
\endtable
|
|
|
643 |
|
|
|
644 |
In addition to those \QA specific tags, the tags for generating and registering
|
|
|
645 |
documentation can be used. See \l{The Qt Help Framework#Creating a Qt Help Collection}
|
|
|
646 |
{Qt Help Collection} documentation for more information.
|
|
|
647 |
|
|
|
648 |
An example of a help collection file that uses all the available tags is shown below:
|
|
|
649 |
|
|
|
650 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 1
|
|
|
651 |
|
|
|
652 |
To create the binary collection file, run the \c qcollectiongenerator tool:
|
|
|
653 |
|
|
|
654 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 10
|
|
|
655 |
|
|
|
656 |
To test the generated collection file, start \QA in the following way:
|
|
|
657 |
|
|
|
658 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
|
|
|
659 |
|
|
|
660 |
\section1 Using Qt Assistant Remotely
|
|
|
661 |
|
|
|
662 |
Even though the help viewer is a standalone application, it will mostly
|
|
|
663 |
be launched by the application it provides help for. This approach
|
|
|
664 |
gives the application the possibility to ask for specific help contents
|
|
|
665 |
to be displayed as soon as the help viewer is started. Another advantage
|
|
|
666 |
with this approach is that the application can communicate with the
|
|
|
667 |
help viewer process and can therefore request other help contents to be
|
|
|
668 |
shown depending on the current state of the application.
|
|
|
669 |
|
|
|
670 |
So, to use \QA as the custom help viewer of your application, simply
|
|
|
671 |
create a QProcess and specify the path to the Assistant executable. In order
|
|
|
672 |
to make Assistant listen to your application, turn on its remote control
|
|
|
673 |
functionality by passing the \c{-enableRemoteControl} command line option.
|
|
|
674 |
|
|
|
675 |
\warning The trailing '\0' must be appended separately to the QByteArray,
|
|
|
676 |
e.g., \c{QByteArray("command" + '\0')}.
|
|
|
677 |
|
|
|
678 |
The following example shows how this can be done:
|
|
|
679 |
|
|
|
680 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 2
|
|
|
681 |
|
|
|
682 |
Once \QA is running, you can send commands by using the stdin channel of
|
|
|
683 |
the process. The code snippet below shows how to tell \QA to show a certain
|
|
|
684 |
page in the documentation.
|
|
|
685 |
|
|
|
686 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 3
|
|
|
687 |
|
|
|
688 |
The following commands can be used to control \QA:
|
|
|
689 |
|
|
|
690 |
\table
|
|
|
691 |
\header
|
|
|
692 |
\o Command
|
|
|
693 |
\o Brief Description
|
|
|
694 |
\row
|
|
|
695 |
\o \c{show <Widget>}
|
|
|
696 |
\o Shows the dock widget specified by <Widget>. If the widget
|
|
|
697 |
is already shown and this command is sent again, the widget will be
|
|
|
698 |
activated, meaning that it will be raised and given the input focus.
|
|
|
699 |
Possible values for <Widget> are "contents", "index", "bookmarks" or "search".
|
|
|
700 |
\row
|
|
|
701 |
\o \c{hide <Widget>}
|
|
|
702 |
\o Hides the dock widget specified by <Widget>. Possible values for
|
|
|
703 |
<Widget> are "contents", "index", "bookmarks" and "search".
|
|
|
704 |
\row
|
|
|
705 |
\o \c{setSource <Url>}
|
|
|
706 |
\o Displays the given <Url>. The URL can be absolute or relative
|
|
|
707 |
to the currently displayed page. If the URL is absolute, it has to
|
|
|
708 |
be a valid Qt help system URL; i.e., starting with "qthelp://".
|
|
|
709 |
\row
|
|
|
710 |
\o \c{activateKeyword <Keyword>}
|
|
|
711 |
\o Inserts the specified <Keyword> into the line edit of the
|
|
|
712 |
index dock widget and activates the corresponding item in the
|
|
|
713 |
index list. If such an item has more than one link associated
|
|
|
714 |
with it, a topic chooser will be shown.
|
|
|
715 |
\row
|
|
|
716 |
\o \c{activateIdentifier <Id>}
|
|
|
717 |
\o Displays the help contents for the given <Id>. An ID is unique
|
|
|
718 |
in each namespace and has only one link associated to it, so the
|
|
|
719 |
topic chooser will never pop up.
|
|
|
720 |
\row
|
|
|
721 |
\o \c{syncContents}
|
|
|
722 |
\o Selects the item in the contents widget which corresponds to
|
|
|
723 |
the currently displayed page.
|
|
|
724 |
\row
|
|
|
725 |
\o \c{setCurrentFilter}
|
|
|
726 |
\o Selects the specified filter and updates the visual representation
|
|
|
727 |
accordingly.
|
|
|
728 |
\row
|
|
|
729 |
\o \c{expandToc <Depth>}
|
|
|
730 |
\o Expands the table of contents tree to the given depth. If depth
|
|
|
731 |
is less than 1, the tree will be collapsed completely.
|
|
|
732 |
\endtable
|
|
|
733 |
|
|
|
734 |
If you want to send several commands within a short period of time, it is
|
|
|
735 |
recommended that you write only a single line to the stdin of the process
|
|
|
736 |
instead of one line for every command. The commands have to be separated by
|
|
|
737 |
a semicolon, as shown in the following example:
|
|
|
738 |
|
|
|
739 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 4
|
|
|
740 |
|
|
|
741 |
\section1 Compatibility with Old Formats
|
|
|
742 |
|
|
|
743 |
In older versions of Qt, the help system was based on Document Content File
|
|
|
744 |
(DCF) and Qt Assistant Documentation Profile (ADP) formats. In contrast,
|
|
|
745 |
Qt Assistant and the help system used in Qt 4.4 use the formats described
|
|
|
746 |
earlier in this manual.
|
|
|
747 |
|
|
|
748 |
Unfortunately, the old file formats are not compatible with the new ones.
|
|
|
749 |
In general, the differences are not that big \mdash in most cases is the old
|
|
|
750 |
format is just a subset of the new one. One example is the \c namespace tag in
|
|
|
751 |
the Qt Help Project format, which was not part of the old format, but plays a vital
|
|
|
752 |
role in the new one. To help you to move to the new file format, we have created
|
|
|
753 |
a conversion wizard.
|
|
|
754 |
|
|
|
755 |
The wizard is started by executing \c qhelpconverter. It guides you through the
|
|
|
756 |
conversion of different parts of the file and generates a new \c qch or \c qhcp
|
|
|
757 |
file.
|
|
|
758 |
|
|
|
759 |
Once the wizard is finished and the files created, run the \c qhelpgenerator
|
|
|
760 |
or the \c qcollectiongenerator tool to generate the binary help files used by \QA.
|
|
|
761 |
*/
|
|
|
762 |
|
|
|
763 |
/*
|
|
|
764 |
\section2 Modifying \QA with Command Line Options
|
|
|
765 |
|
|
|
766 |
Different help collections can be shown by simply passing the help collection
|
|
|
767 |
path to \QA. For example:
|
|
|
768 |
|
|
|
769 |
\snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 0
|
|
|
770 |
|
|
|
771 |
Other available options the can be passed on the command line.
|
|
|
772 |
|
|
|
773 |
\table
|
|
|
774 |
\header
|
|
|
775 |
\o Command Line Option
|
|
|
776 |
\o Brief Description
|
|
|
777 |
\row
|
|
|
778 |
\o -collectionFile <file.qhc>
|
|
|
779 |
\o Uses the specified collection file instead of the default one.
|
|
|
780 |
\row
|
|
|
781 |
\o -showUrl URL
|
|
|
782 |
\o Shows the document referenced by URL.
|
|
|
783 |
\row
|
|
|
784 |
\o -enableRemoteControl
|
|
|
785 |
\o Enables \QA to be remotly controlled.
|
|
|
786 |
\row
|
|
|
787 |
\o -show <widget>
|
|
|
788 |
\o Shows the specified dockwidget which can be "contents", "index",
|
|
|
789 |
"bookmarks" or "search".
|
|
|
790 |
\row
|
|
|
791 |
\o -hide <widget>
|
|
|
792 |
\o Hides the specified dockwidget which can be "contents", "index",
|
|
|
793 |
"bookmarks" or "search.
|
|
|
794 |
\row
|
|
|
795 |
\o -activate <widget>
|
|
|
796 |
\o Activates the specified dockwidget which can be "contents",
|
|
|
797 |
"index", "bookmarks" or "search.
|
|
|
798 |
\row
|
|
|
799 |
\o -register <doc.qch>
|
|
|
800 |
\o Registers the specified compressed help file in the given help
|
|
|
801 |
collection.
|
|
|
802 |
\row
|
|
|
803 |
\o -unregister <doc.qch>
|
|
|
804 |
\o Unregisters the specified compressed help file from the given
|
|
|
805 |
collection file.
|
|
|
806 |
\row
|
|
|
807 |
\o -quiet
|
|
|
808 |
\o Doesn't show any error, warning or success messages.
|
|
|
809 |
\endtable
|
|
|
810 |
*/
|