--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/development/assistant-manual.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,810 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page assistant-manual.html
+ \title Qt Assistant Manual
+ \ingroup qttools
+
+ \startpage {index.html}{Qt Reference Documentation}
+ \nextpage Qt Assistant in More Detail
+
+ \keyword Qt Assistant
+
+ This document introduces \QA, a tool for presenting on-line
+ documentation. The document is divided into the following sections:
+
+ Table of contents:
+
+ \list
+ \o \l{The One-Minute Guide to Using Qt Assistant}
+ \o \l{Qt Assistant in More Detail}
+ \o \l{Using Qt Assistant as a Custom Help Viewer}
+ \endlist
+
+ \chapter The One-Minute Guide to Using Qt Assistant
+
+ Once you have installed Qt, \QA should be ready to run:
+
+ \list
+ \o On Windows, \QA is available as a menu option on the Qt menu.
+ \o On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory.
+ \o On Unix/Linux, open a terminal, type \c{assistant} and press \key{Enter}.
+ \endlist
+
+ When you start up \QA, you will be presented with a standard main window
+ application, with a menu bar and toolbar. Below these, on the left hand
+ side are navigation windows called \e{Contents}, \e{Index} and \e{Bookmarks}.
+ On the right, taking up most of the space, is the \e{Documentation} window.
+ By default, \QA loads the Qt reference documentation along with the manuals
+ of other Qt tools, like \QD or \QL.
+
+ \QA works in a similar way to a Web browser. If you click hyperlinks
+ (cross-references), the \e{Documentation} window will present the relevant
+ page. You can bookmark pages of particular interest and you can click the
+ \gui{Previous} and \gui{Next} toolbar buttons to navigate within the pages
+ you have visited.
+
+ Although \QA can be used just like a Web browser to navigate through
+ the documentation, \QA offers a powerful means of navigation that Web
+ browsers do not provide. \QA uses an advanced full text search engine
+ to index all the pages in each compressed help file so that you can
+ search for particular words and phrases.
+
+ To perform an index search, click the \gui{Index} tab on the Sidebar
+ (or press \key{Alt+I}). In the \gui{'Look For'} line edit enter a word;
+ e.g., 'homedirpath'. As you type, words are found and highlighted in a list
+ beneath the line edit. If the highlighted text matches what you're
+ looking for, double click it, (or press \key{Enter}) and the
+ \e{Documentation} window will display the relevant page. You rarely have
+ to type in the whole word before \QA finds a match. Note that for some
+ words there may be more than one possible page that is relevant.
+
+ \QA also provides full text searching for finding specific words in
+ the documentation. To activate the full text search, either press \key(Alt+S)
+ or click on the \gui{Search} tab in the \e{Documentation} window. Then
+ enter the term you're looking for and hit the \gui{Search} button. All
+ documents containing the specified term will then be listed in the list box
+ below.
+*/
+
+/*!
+ \page assistant-details.html
+ \title Qt Assistant in More Detail
+
+ \contentspage {Qt Assistant Manual}{Contents}
+ \previouspage Qt Assistant Manual
+ \nextpage Using Qt Assistant as a Custom Help Viewer
+
+ \tableofcontents
+
+ \img assistant-assistant.png
+
+ \section1 Command Line Options
+
+ \QA handles the following command line options:
+
+ \table
+ \header
+ \o Command Line Option
+ \o Brief Description
+ \row
+ \o -collectionFile <file.qhc>
+ \o Uses the specified collection file instead of the default one.
+ \row
+ \o -showUrl URL
+ \o Shows the document referenced by URL.
+ \row
+ \o -enableRemoteControl
+ \o Enables \QA to be remotly controlled.
+ \row
+ \o -show <widget>
+ \o Shows the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search".
+ \row
+ \o -hide <widget>
+ \o Hides the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search.
+ \row
+ \o -activate <widget>
+ \o Activates the specified dockwidget which can be "contents",
+ "index", "bookmarks" or "search.
+ \row
+ \o -register <doc.qch>
+ \o Registers the specified compressed help file in the given help
+ collection.
+ \row
+ \o -unregister <doc.qch>
+ \o Unregisters the specified compressed help file from the given
+ collection file.
+ \row
+ \o -setCurrentFilter filter
+ \o Sets the given filter as the active filter.
+ \row
+ \o -quiet
+ \o Doesn't show any error, warning or success messages.
+ \endtable
+
+ \section1 Tool Windows
+
+ \img assistant-dockwidgets.png
+
+ The tool windows provide four ways to navigate the documentation:
+
+ \list
+ \o The \gui{Contents} window presents a table of contents implemented as a
+ tree view for the documentation that is available. If you click an item,
+ its documentation will appear in the \e{Documentation} window. If you double
+ click an item or click on the control to the left of it, the item's sub-items
+ will appear. Click a sub-item to make its page appear in the \e{Documentation}
+ window. Click on the control next to an open item to hide its sub-items.
+ \o The \gui{Index} window is used to look up key words or phrases.
+ See \l{The One-Minute Guide to Using Qt Assistant} for how to use this
+ window.
+ \o The \gui{Bookmarks} window lists any bookmarks you have made. Double
+ click a bookmark to make its page appear in the \e{Documentation} window.
+ The \gui{Bookmarks} window provides a context menu with \gui{Show Item},
+ \gui{Delete Item} as well as \gui{Rename Item}. Click in the main menu
+ \menu{Bookmark|Add Bookmark...} (or press \key{Ctrl+B}) to bookmark the
+ page that is currently showing in the \e{Documentation} window. Right click
+ a bookmark in the list to rename or delete the highlighted bookmark.
+ \endlist
+
+ If you want the \gui{Documentation} window to use as much space as possible,
+ you can easily group, move or hide the tool windows. To group the windows,
+ drag one on top of the other and release the mouse. If one or all tool
+ windows are not shown, press \key{Alt+C}, \key{Alt+I} or \key{Alt+O} to show
+ the required window.
+
+ The tool windows can be docked into the main window, so you can drag them
+ to the top, left, right or bottom of \e{Qt Assistant's} window, or you can
+ drag them outside \QA to float them as independent windows.
+
+ \section1 Documentation Window
+
+ \img assistant-docwindow.png
+
+ The \gui{Documentation} window lets you create a tab for each
+ documentation page that you view. Click the \gui{Add Tab} button and a new
+ tab will appear with the page name as the tab's caption. This makes it
+ convenient to switch between pages when you are working with different
+ documentation. You can delete a tab by clicking the \gui{Close Tab} button
+ located on the right side of the \gui{Documentation} window.
+
+ \section1 Toolbars
+
+ \img assistant-toolbar.png
+
+ The main toolbar provides fast access to the most common actions.
+
+ \table
+ \header \o Action \o Description \o Menu Item \o Shortcut
+ \row \o \gui{Previous} \o Takes you to the previous page in the history.
+ \o \menu{Go|Previous} \o \key{Alt+Left Arrow}
+ \row \o \gui{Next} \o Takes you to the next page in the history.
+ \o \menu{Go|Next} \o \key{Alt+Right Arrow}
+ \row \o \gui{Home}
+ \o Takes you to the home page as specified in the Preferences Dialog.
+ \o \menu{Go|Home} \o \key{Ctrl+Home}.
+ \row \o \gui{Sync with Table of Contents}
+ \o Synchronizes the \gui{Contents} tool window with the page currently
+ shown in the \gui{Documentation} window.
+ \o \menu{Go|Sync with Table of Contents} \o
+ \row \o \gui{Copy} \o Copies any selected text to the clipboard.
+ \o \menu{Edit|Copy} \o \key{Ctrl+C}
+ \row \o \gui{Print} \o Opens the \gui{Print} dialog.
+ \o \menu{File|Print} \o \key{Ctrl+P}
+ \row \o \gui{Find in Text} \o Opens the \gui{Find Text} dialog.
+ \o \menu{Edit|Find in Text} \o \key{Ctrl+F}
+ \row \o \gui{Zoom in}
+ \o Increases the font size used to display text in the current tab.
+ \o \menu{View|Zoom in} \o \key{Ctrl++}
+ \row \o \gui{Zoom out}
+ \o Decreases the font size used to display text in the current tab.
+ \o \menu{View|Zoom out} \o \key{Ctrl+-}
+ \row \o \gui{Normal Size}
+ \o Resets the font size to its normal size in the current tab.
+ \o \menu{View|Normal Size} \o \key{Ctrl+0}
+ \endtable
+
+ \img assistant-address-toolbar.png
+
+ The address toolbar provides a fast way to enter a specific URL for a
+ documentation file. By default, the address toolbar is not shown, so it
+ has to be activated via \menu{View|Toolbars|Address Toolbar}.
+
+ \img assistant-filter-toolbar.png
+
+ The filter toolbar allows you to apply a filter to the currently installed
+ documentation. As with the address toolbar, the filter toolbar is not visible
+ by default and has to be activated via \menu{View|Toolbars|Filter Toolbar}.
+
+ \section1 Menus
+
+ \section2 File Menu
+
+ \list
+ \o \menu{File|Page Setup...} invokes a dialog allowing you to define
+ page layout properties, such as margin sizes, page orientation and paper size.
+ \o \menu{File|Print Preview...} provides a preview of the printed pages.
+ \o \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}.
+ \o \menu{File|New Tab} opens a new empty tab in the \gui{Documentation}
+ window.
+ \o \menu{File|Close Tab} closes the current tab of the
+ \gui{Documentation} window.
+ \o \menu{File|Exit} closes the \QA application.
+ \endlist
+
+ \section2 Edit Menu
+
+ \list
+ \o \menu{Edit|Copy} copies any selected text to the clipboard.
+ \o \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text}
+ control} at the lower end of the \gui{Documentation} window.
+ \o \menu{Edit|Find Next} looks for the next occurance of the specified
+ text in the \gui{Find Text} control.
+ \o \menu{Edit|Find Previous} looks for the previous occurance of
+ the specified text in the \l{#Find Text Control}{\gui{Find Text} control}.
+ \o \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}.
+ \endlist
+
+ \section2 View Menu
+
+ \list
+ \o \menu{View|Zoom in} increases the font size in the current tab.
+ \o \menu{View|Zoom out} decreases the font size in the current tab.
+ \o \menu{View|Normal Size} resets the font size in the current tab.
+ \o \menu{View|Contents} toggles the display of the \gui{Contents} tool window.
+ \o \menu{View|Index} toggles the display of the \gui{Index} tool window.
+ \o \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window.
+ \o \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window.
+ \endlist
+
+ \section2 Go Menu
+
+ \list
+ \o \menu{Go|Home} goes to the home page.
+ \o \menu{Go|Back} displays the previous page in the history.
+ \o \menu{Go|Forward} displays the next page in the history.
+ \o \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page.
+ \o \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window.
+ \o \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window.
+ \endlist
+
+ \section2 Bookmarks Menu
+
+ \list
+ \o \menu{Bookmarks|Add} adds the current page to the list of bookmarks.
+ \endlist
+
+ \section1 Dialogs
+
+ \section2 Print Dialog
+
+ This dialog is platform-specific. It gives access to various printer
+ options and can be used to print the document shown in the current tab.
+
+ \section2 Preferences Dialog
+
+ \img assistant-preferences-fonts.png
+
+ The \menu{Fonts} page allows you to change the font family and font sizes of the
+ browser window displaying the documentation or the application itself.
+
+ \img assistant-preferences-filters.png
+
+ The \menu{Filters} page lets you create and remove documentation
+ filters. To add a new filter, click the \gui{Add} button, specify a
+ filter name in the pop-up dialog and click \gui{OK}, then select
+ the filter attributes in the list box on the right hand side.
+ You can delete a filter by selecting it and clicking the \gui{Remove}
+ button.
+
+ \img assistant-preferences-documentation.png
+
+ The \menu{Documentation} page lets you install and remove compressed help
+ files. Click the \gui{Install} button and choose the path of the compressed
+ help file (*.qch) you would like to install.
+ To delete a help file, select a documentation set in the list and click
+ \gui{Remove}.
+
+ \img assistant-preferences-options.png
+
+ The \menu{Options} page lets you specify the homepage \QA will display when
+ you click the \gui{Home} button in \QA's main user interface. You can specify
+ the hompage by typing it here or clicking on one of the buttons below the
+ textbox. \gui{Current Page} sets the currently displayed page as your home
+ page while \gui{Restore to default} will reset your home page to the default
+ home page.
+
+ \section1 Find Text Control
+
+ This control is used to find text in the current page. Enter the text you want
+ to find in the line edit. The search is incremental, meaning that the most
+ relevant result is shown as you enter characters into the line edit.
+
+ If you check the \gui{Whole words only} checkbox, the search will only consider
+ whole words; for example, if you search for "spin" with this checkbox checked it will
+ not match "spinbox", but will match "spin". If you check the \gui{Case sensitive}
+ checkbox then, for example, "spin" will match "spin" but not "Spin". You can
+ search forwards or backwards from your current position in the page by clicking
+ the \gui{Previous} or \gui{Next} buttons. To hide the find control, either click the
+ \gui{Close} button or hit the \key{Esc} key.
+
+ \section1 Filtering Help Contents
+
+ \QA allows you to install any kind of documentation as long as it is organized
+ in Qt compressed help files (*.qch). For example, it is possible to install the
+ Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. In many
+ respects, this is very convenient since only one version of \QA is needed.
+ However, at the same time it becomes more complicated when performing tasks like
+ searching the index because nearly every keyword is defined in Qt 4.4.0 as well
+ as in Qt 4.4.1. This means that \QA will always ask the user to choose which one
+ should be displayed.
+
+ We use documentation filters to solve this issue. A filter is identified by its
+ name, and contains a list of filter attributes. An attribute is just a string and
+ can be freely chosen. Attributes are defined by the documentation itself, this
+ means that every documentation set usually has one or more attributes.
+
+ For example, the Qt 4.4.0 \QA documentation defines the attributes \c {assistant},
+ \c{tools} and \c{4.4.0}, \QD defines \c{designer}, \c{tools} and \c{4.4.0}.
+ The filter to display all tools would then define only the attribute
+ \c{tools} since this attribute is part of both documentation sets.
+ Adding the attribute \c{assistant} to the filter would then only show \QA
+ documentation since the \QD documentation does not contain this
+ attribute. Having an empty list of attributes in a filter will match all
+ documentation; i.e., it is equivalent to requesting unfiltered documentation.
+
+ \section1 Full Text Searching
+
+ \img assistant-search.png
+
+ \QA provides a powerful full text search engine. To search
+ for certain words or text, click the \gui{Search} tab in the \gui{Documentation}
+ window. Then enter the text you want to look for and press \key{Enter}
+ or click the \gui{Search} button. The search is not case sensitive, so,
+ for example, Foo, fOo and FOO are all treated as the same. The following are
+ examples of common search patterns:
+
+ \list
+ \o \c deep -- lists all the documents that contain the word 'deep'
+ \o \c{deep*} -- lists all the documents that contain a word beginning
+ with 'deep'
+ \o \c{deep copy} -- lists all documents that contain both 'deep' \e
+ and 'copy'
+ \o \c{"deep copy"} -- list all documents that contain the phrase 'deep copy'
+ \endlist
+
+ It is also possible to use the \gui{Advanced search} to get more flexibility.
+ You can specify some words so that hits containing these are excluded from the
+ result, or you can search for an exact phrase. Searching for similar words will
+ give results like these:
+
+ \list
+ \o \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString}
+ \o \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString}
+ \o \c{QStrin} -- lists all the documents with titles that are similar, such as \c{QString}
+ \endlist
+
+ Options can be combined to improve the search results.
+
+ The list of documents found is ordered according to the number of
+ occurrences of the search text which they contain, with those containing
+ the highest number of occurrences appearing first. Simply click any
+ document in the list to display it in the \gui{Documentation} window.
+
+ If the documentation has changed \mdash for example, if documents have been added
+ or removed \mdash \QA will index them again.
+
+*/
+
+/*!
+ \page assistant-custom-help-viewer.html
+ \title Using Qt Assistant as a Custom Help Viewer
+
+ \contentspage {Qt Assistant Manual}{Contents}
+ \previouspage Qt Assistant in More Detail
+
+ Using \QA as custom help viewer requires more than just being able to
+ display custom documentation. It is equally important that the
+ appearance of \QA can be customized so that it is seen as a
+ application-specific help viewer rather than \QA. This is achieved by
+ changing the window title or icon, as well as some application-specific
+ menu texts and actions. The complete list of possible customizations
+ can be found in the \l{Creating a Custom Help Collection File} section.
+
+ Another requirement of a custom help viewer is the ability to receive
+ actions or commands from the application it provides help for. This is
+ especially important when the application offers context sensitive help.
+ When used in this way, the help viewer may need to change its contents
+ depending on the state the application is currently in. This means that
+ the application has to communicate the current state to the help viewer.
+ The section about \l{Using Qt Assistant Remotely} explains how this can
+ be done.
+
+ \tableofcontents
+
+ The \l{Simple Text Viewer Example}{Simple Text Viewer} example uses the
+ techniques described in this document to show how to use \QA as a custom
+ help viewer for an application.
+
+ \warning In order to ship Qt Assistant in your application, it is crucial
+ that you include the sqlite plugin. For more information on how to include
+ plugins in your application, refer to the \l{Deploying Qt Applications}
+ {deployment documentation}.
+
+ \section1 Qt Help Collection Files
+
+ The first important point to know about \QA is that it stores all
+ settings related to its appearance \e and a list of installed
+ documentation in a help collection file. This means, when starting \QA
+ with different collection files, \QA may look totally different. This
+ complete separation of settings makes it possible to deploy \QA as a
+ custom help viewer for more than one application on one machine
+ without risk of interference between different instances of \QA.
+
+ To apply a certain help collection to \QA, specify the respective
+ collection file on the command line when starting it. For example:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
+
+ However, storing all settings in one collection file raises some problems.
+ The collection file is usually installed in the same directory as the
+ application itself, or one of its subdirectories. Depending on the
+ directory and the operating system, the user may not have any permissions
+ to modify this file which would happen when the user settings are stored.
+ Also, it may not even be possible to give the user write permissions;
+ e.g., when the file is located on a read-only medium like a CD-ROM.
+
+ Even if it is possible to give everybody the right to store their settings
+ in a globally available collection file, the settings from one user would
+ be overwritten by another user when exiting \QA.
+
+ To solve this dilemma, \QA creates user specific collection files which
+ are more or less copied from the original collection file. The user-specific
+ collection file will be saved in a subdirectory of the path returned by
+ QDesktopServices::DataLocation. The subdirectory, or \e{cache directory}
+ within this user-specific location, can be defined in the help collection
+ project file. For example:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 7
+
+ So, when calling
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
+
+ \QA actually uses the collection file:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 9
+
+ There is no need ever to start \QA with the user specific collection
+ file. Instead, the collection file shipped with the application should
+ always be used. Also, when adding or removing documentation from the
+ collection file (see next section) always use the normal collection file.
+ \QA will take care of synchronizing the user collection files when the
+ list of installed documentation has changed.
+
+ \section1 Displaying Custom Documentation
+
+ Before \QA is able to show documentation, it has to know where it can
+ find the actual documentation files, meaning that it has to know the
+ location of the Qt compressed help file (*.qch). As already mentioned,
+ \QA stores references to the compressed help files in the currently used
+ collection file. So, when creating a new collection file you can list
+ all compressed help files \QA should display.
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 5
+
+ Sometimes, depending on the application for which \QA acts as a
+ help viewer, more documentation needs to be added over time; for
+ example, when installing more application components or plugins.
+ This can be done manually by starting \QA, opening the \gui{Edit|Preferences}
+ dialog and navigating to the \gui{Documentation} tab page. Then click
+ the \gui{Add...} button, select a Qt compressed help file (*.qch)
+ and press \gui{Open}. However, this approach has the disadvantage
+ that every user has to do it manually to get access to the new
+ documentation.
+
+ The prefered way of adding documentation to an already existing collection
+ file is to use the \c{-register} command line flag of \QA. When starting
+ \QA with this flag, the documentation will be added and \QA will
+ exit right away displaying a message if the registration was successful
+ or not.
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 6
+
+ The \c{-quiet} flag can be passed on to \QA to prevent it from writing
+ out the status message.
+
+ \bold{Note:} \QA will show the documentation in the contents view in the same
+ order as it was registered.
+
+
+ \section1 Changing the Appearance of Qt Assistant
+
+ The appearance of \QA can be changed by passing different command line options
+ on startup. However, these command line options only allow to show or hide
+ specific widgets, like the contents or index view. Other customizations, such
+ as changing the application title or icon, or disabling the filter functionality,
+ can be done by creating a custom help collection file.
+
+ \section2 Creating a Custom Help Collection File
+
+ The help collection file (*.qhc) used by \QA is created when running the
+ \c qcollectiongenerator tool on a help collection project file (*.qhcp).
+ The project file format is XML and supports the following tags:
+
+ \table
+ \header
+ \o Tag
+ \o Brief Description
+ \row
+ \o \c{<title>}
+ \o This property is used to specify a window title for \QA.
+ \row
+ \o \c{<homePage>}
+ \o This tag specifies which page should be display when
+ pressing the home button in \QA's main user interface.
+ \row
+ \o \c{<startPage>}
+ \o This tag specifies which page \QA should initially
+ display when the help collection is used.
+ \row
+ \o \c{<currentFilter>}
+ \o This tag specifies the \l{Qt Assistant in More Detail#Preferences Dialog}{filter}
+ that is initially used.
+ If this filter is not specified, the documentation will not be filtered. This has
+ no impact if only one documentation set is installed.
+ \row
+ \o \c{<applicationIcon>}
+ \o This tag describes an icon that will be used instead of the normal \QA
+ application icon. This is specified as a relative path from the directory
+ containing the collection file.
+ \row
+ \o \c{<enableFilterFunctionality>}
+ \o This tag is used to enable or disable user accessible filter functionality,
+ making it possible to prevent the user from changing any filter when running \QA.
+ It does not mean that the internal filter functionality is completely disabled.
+ Set the value to \c{false} if you want to disable the filtering. If the filter
+ toolbar should be shown by default, set the attribute \c{visible} to \c{true}.
+ \row
+ \o \c{<enableDocumentationManager>}
+ \o This tag is used to specify whether the documentation manager should be shown
+ in the preferences dialog. Disabling the Documentation Manager allows you to limit
+ \QA to display a specific documentation set or make it impossible for the end user
+ to accidentally remove or install documentation. To hide the documentation manager,
+ set the tag value to \c{false}.
+ \row
+ \o \c{<enableAddressBar>}
+ \o This tag describes if the address bar can be shown. By default it is
+ enabled; if you want to disable it set the tag value to \c{false}. If the
+ address bar functionality is enabled, the address bar can be shown by setting the
+ tag attribute \c{visible} to \c{true}.
+ \row
+ \o \c{<aboutMenuText>, <text>}
+ \o The \c{aboutMenuText} tag lists texts for different languages which will
+ later appear in the \menu{Help} menu; e.g., "About Application". A text is
+ specified within the \c{text} tags; the \c{language} attribute takes the two
+ letter language name. The text is used as the default text if no language
+ attribute is specified.
+ \row
+ \o \c{<aboutDialog>, <file>, <icon>}
+ \o The \c{aboutDialog} tag can be used to specify the text for the \gui{About}
+ dialog that can be opened from the \menu{Help} menu. The text is taken from the
+ file in the \c{file} tags. It is possible to specify a different file or any
+ language. The icon defined by the \c{icon} tags is applied to any language.
+ \row
+ \o \c{<cacheDirectory>}
+ \o Specified as a path relative to the directory given by
+ QDesktopServices::DataLocation, the cache path is used to store index files
+ needed for the full text search and a copy of the collection file.
+ The copy is needed because \QA stores all its settings in the collection file;
+ i.e., it must be writable for the user.
+ \endtable
+
+ In addition to those \QA specific tags, the tags for generating and registering
+ documentation can be used. See \l{The Qt Help Framework#Creating a Qt Help Collection}
+ {Qt Help Collection} documentation for more information.
+
+ An example of a help collection file that uses all the available tags is shown below:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 1
+
+ To create the binary collection file, run the \c qcollectiongenerator tool:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 10
+
+ To test the generated collection file, start \QA in the following way:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
+
+ \section1 Using Qt Assistant Remotely
+
+ Even though the help viewer is a standalone application, it will mostly
+ be launched by the application it provides help for. This approach
+ gives the application the possibility to ask for specific help contents
+ to be displayed as soon as the help viewer is started. Another advantage
+ with this approach is that the application can communicate with the
+ help viewer process and can therefore request other help contents to be
+ shown depending on the current state of the application.
+
+ So, to use \QA as the custom help viewer of your application, simply
+ create a QProcess and specify the path to the Assistant executable. In order
+ to make Assistant listen to your application, turn on its remote control
+ functionality by passing the \c{-enableRemoteControl} command line option.
+
+ \warning The trailing '\0' must be appended separately to the QByteArray,
+ e.g., \c{QByteArray("command" + '\0')}.
+
+ The following example shows how this can be done:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 2
+
+ Once \QA is running, you can send commands by using the stdin channel of
+ the process. The code snippet below shows how to tell \QA to show a certain
+ page in the documentation.
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 3
+
+ The following commands can be used to control \QA:
+
+ \table
+ \header
+ \o Command
+ \o Brief Description
+ \row
+ \o \c{show <Widget>}
+ \o Shows the dock widget specified by <Widget>. If the widget
+ is already shown and this command is sent again, the widget will be
+ activated, meaning that it will be raised and given the input focus.
+ Possible values for <Widget> are "contents", "index", "bookmarks" or "search".
+ \row
+ \o \c{hide <Widget>}
+ \o Hides the dock widget specified by <Widget>. Possible values for
+ <Widget> are "contents", "index", "bookmarks" and "search".
+ \row
+ \o \c{setSource <Url>}
+ \o Displays the given <Url>. The URL can be absolute or relative
+ to the currently displayed page. If the URL is absolute, it has to
+ be a valid Qt help system URL; i.e., starting with "qthelp://".
+ \row
+ \o \c{activateKeyword <Keyword>}
+ \o Inserts the specified <Keyword> into the line edit of the
+ index dock widget and activates the corresponding item in the
+ index list. If such an item has more than one link associated
+ with it, a topic chooser will be shown.
+ \row
+ \o \c{activateIdentifier <Id>}
+ \o Displays the help contents for the given <Id>. An ID is unique
+ in each namespace and has only one link associated to it, so the
+ topic chooser will never pop up.
+ \row
+ \o \c{syncContents}
+ \o Selects the item in the contents widget which corresponds to
+ the currently displayed page.
+ \row
+ \o \c{setCurrentFilter}
+ \o Selects the specified filter and updates the visual representation
+ accordingly.
+ \row
+ \o \c{expandToc <Depth>}
+ \o Expands the table of contents tree to the given depth. If depth
+ is less than 1, the tree will be collapsed completely.
+ \endtable
+
+ If you want to send several commands within a short period of time, it is
+ recommended that you write only a single line to the stdin of the process
+ instead of one line for every command. The commands have to be separated by
+ a semicolon, as shown in the following example:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 4
+
+ \section1 Compatibility with Old Formats
+
+ In older versions of Qt, the help system was based on Document Content File
+ (DCF) and Qt Assistant Documentation Profile (ADP) formats. In contrast,
+ Qt Assistant and the help system used in Qt 4.4 use the formats described
+ earlier in this manual.
+
+ Unfortunately, the old file formats are not compatible with the new ones.
+ In general, the differences are not that big \mdash in most cases is the old
+ format is just a subset of the new one. One example is the \c namespace tag in
+ the Qt Help Project format, which was not part of the old format, but plays a vital
+ role in the new one. To help you to move to the new file format, we have created
+ a conversion wizard.
+
+ The wizard is started by executing \c qhelpconverter. It guides you through the
+ conversion of different parts of the file and generates a new \c qch or \c qhcp
+ file.
+
+ Once the wizard is finished and the files created, run the \c qhelpgenerator
+ or the \c qcollectiongenerator tool to generate the binary help files used by \QA.
+*/
+
+/*
+\section2 Modifying \QA with Command Line Options
+
+ Different help collections can be shown by simply passing the help collection
+ path to \QA. For example:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 0
+
+ Other available options the can be passed on the command line.
+
+ \table
+ \header
+ \o Command Line Option
+ \o Brief Description
+ \row
+ \o -collectionFile <file.qhc>
+ \o Uses the specified collection file instead of the default one.
+ \row
+ \o -showUrl URL
+ \o Shows the document referenced by URL.
+ \row
+ \o -enableRemoteControl
+ \o Enables \QA to be remotly controlled.
+ \row
+ \o -show <widget>
+ \o Shows the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search".
+ \row
+ \o -hide <widget>
+ \o Hides the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search.
+ \row
+ \o -activate <widget>
+ \o Activates the specified dockwidget which can be "contents",
+ "index", "bookmarks" or "search.
+ \row
+ \o -register <doc.qch>
+ \o Registers the specified compressed help file in the given help
+ collection.
+ \row
+ \o -unregister <doc.qch>
+ \o Unregisters the specified compressed help file from the given
+ collection file.
+ \row
+ \o -quiet
+ \o Doesn't show any error, warning or success messages.
+ \endtable
+ */