/****************************************************************************

**

** Copyright (C) 2010 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 -remove-search-index

            \o Purges the help search engine's index. This option is

               useful in case the associated index files get corrupted.

               \QA will re-index the documentation at the next start-up.

        \row

            \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{Qt Assistant Manual#The One-Minute Guide to Using Qt Assistant}{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