source: trunk/doc/src/development/assistant-manual.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

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