|
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 */ |