assistant-quick-guide.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \if !defined(ASSISTANT_INTERNAL)
    \previouspage Qt Assistant Manual
    \endif
    \page assistant-quick-guide.html
    \nextpage Using Qt Assistant
 
    \title Qt Assistant Quick Guide
 
    Once you have installed Qt, you can start Qt Assistant in the same way as
    any other application on the development host.
 
    The \QA main window contains a sidebar (1) with navigation windows for:
 
    \list
        \li Viewing a list of documents in Qt help format that are installed on
            the development host.
        \li Managing bookmarks.
        \li Searching for keywords in the index.
        \li Searching for information using a free text search function.
        \li Switching between open topics.
    \endlist
 
    The selected topic in the selected document is displayed in the
    \b Documentation window (2).
 
    \image assistant-assistant.png {Screenshot of the \QA window with
           options to choose documentation of every category}
 
    Click the \gui Previous and \gui Next toolbar buttons (3) to navigate within
    the topics you have visited.
 
    \section1 Managing Bookmarks
 
    \image assistant-bookmarks.png {Screenshot showing the bookmark menu of the
           \QA to save documentation}
 
    To bookmark topics of particular interest, select \gui Bookmarks >
    \gui {Add Bookmark} (or press \key{Ctrl+B}). A bookmark for the
    page that is currently showing in the \gui Documentation window is added.
 
    You can view and manage bookmarks in the \gui Bookmarks window.
    Double-click a bookmark to open the topic in the \gui Documentation window.
    You can also right-click the bookmark and select \gui{Show Bookmark} in the
    context menu.
 
    To rename or delete the highlighted bookmark, select \gui {Rename Bookmark}
    or \gui {Delete Bookmark} in the context menu.
 
    \section1 Searching for Keywords
 
    \image assistant-index.png {Screenshot of the \QA index menu to search
           for keywords}
 
    To perform an index search, click the \gui{Index} tab on the sidebar
    (or press \key{Alt+I}). In the \gui{Look For} field, enter the search term.
    As you type, words are found and highlighted in a list beneath the field.
    If the highlighted text matches what you are
    looking for, double-click it or press \key{Enter}. The
    \gui Documentation window displays the relevant topic. 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 topic that is relevant.
 
    \section1 Using Free Text Search
 
    \image assistant-search.png {Screenshot of the \QA search menu to
           browse through documentation}
 
    \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 the \gui{Search} tab on the sidebar. Then enter the term you are
    looking for and click \gui{Search}. All documents containing the specified
    term are listed.
*/
 
/*!
    \if !defined(ASSISTANT_INTERNAL)
    \nextpage Customizing Qt Assistant
    \endif
    \page assistant-details.html
    \title Using Qt Assistant
    \previouspage Qt Assistant Quick Guide
 
    \image assistant-dockwidgets.png {Screenshot of Qt Assistant showing widgets
           for documentation}
 
    You can read documentation in the \gui Documentation window. To open a topic
    in a new tab, right click it in the \gui Contents window to open a context
    menu and select \gui {Open Link in New Tab}. All open topics are listed in
    the \gui {Open Pages} window. Select a topic to view it in the
    \gui Documentation window.
 
    If you want the \gui{Documentation} window to use as much space as possible,
    you can easily group, move or hide the sidebar windows. To group the windows,
    drag one on top of the other and release the mouse. If one or all sidebar
    windows are not shown, select keyboard shortcuts to display them. You can
    view the keyboard shortcuts in the \gui View menu.
 
    The sidebar windows can be docked into the main window, so you can drag them
    to the top, left, right or bottom of the main window, or you can
    drag them outside \QA to float them as independent windows.
 
    To change the font family and font sizes of the browser window displaying
    the documentation or the application itself, select \gui Edit >
    \gui Preferences > \gui Fonts.
 
    \image assistant-preferences-fonts.png {Screenshot showing the preference menu
           of the \QA to change font settings}
 
    To temporarily increase or decrease the font size in the \gui Documentation
    window, select \gui View > \gui {Zoom in} or \gui {Zoom out}. To reset the
    font size, select \gui View > \gui {Normal Size}.
 
    To navigate between pages, select \gui Go > \gui Previous or \gui Next. This
    takes you to the previous or next page in the history. To return to the home
    page, select \gui Go > \gui Home. To specify the home page, select
    \gui Edit > \gui Preferences > \gui Options.
 
    To synchronize the \gui{Contents} window with the page currently shown in
    the \gui{Documentation} window, select \gui Go >
    \gui {Sync with Table of Contents}.
 
    The address toolbar provides a fast way to enter a specific URL for a
    documentation file. To show the address toolbar, select \gui View >
    \gui Toolbars > \gui {Address Toolbar}.
 
    \section1 Searching from Page Contents
 
    To find text on the current page, select \gui Edit > \gui {Find in Text}.
    Enter the search term in the field. The search is incremental, meaning that
    the most relevant result is shown as you enter characters into the field.
 
    If you select the \gui{Case sensitive} checkbox, the search considers the
    case of the search term. For example, if you search for \b spin, it matches
    \b spin but not \b Spin.
 
    To search forwards or backwards from your current position on the page,
    click \gui Previous or \gui Next.
 
    To hide the find control, either click \gui Close or press \key Esc.
 
    \section1 Full Text Searching
 
    \img assistant-search.png {Screenshot of the \QA search menu to
           browse through documentation}
 
    \QA provides a powerful full text search engine. You can search for certain
    words or text in the \gui Search window. Enter the text you want to look for
    and press \key{Enter} or click \gui{Search}. The search is not case sensitive.
    For example, \b Foo, \b fOo and \b FOO are all treated as the same.
 
    You can create complex queries using the
    \l{https://sqlite.org/fts5.html#full_text_query_syntax}{FTS query syntax}.
 
    The following are examples of common search patterns:
 
    \list
    \li \c deep -- lists all the documents that contain the word \b deep
    \li \c{deep*} -- lists all the documents that contain a word beginning
    with \b deep
    \li \c{deep copy} -- lists all documents that contain both \b deep \e
    and \b copy
    \li \c{"deep copy"} -- list all documents that contain the phrase
     \b {deep copy}
    \endlist
 
    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.
 
    \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, you can view
    Qt reference documentation for several Qt versions 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 most keywords are defined in more than one Qt
    version. 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,
    which means that every documentation set usually has one or more attributes.
 
    For example, the \QA documentation defines the attributes \c {assistant} and
    \c{tools}, whereas \QD defines \c{designer} and \c{tools}.
    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. That is, it is equivalent to requesting unfiltered documentation.
 
    To create and remove documentation filters, select \gui Edit >
    \gui Preferences > \gui Filters.
 
    \image assistant-preferences-filters.png {Screenshot showing the preference menu
           of the \QA to filter which categories should be shown}
 
    To add a new filter, click \gui Add,
    specify a filter name, and click \gui OK. Then select the filter attributes
    in the \gui Attributes field.
 
    To delete a filter, select it and click \gui Remove.
 
    The filter toolbar allows you to apply a filter to the currently installed
    documentation. To show the filter toolbar, select \gui View > \gui Toolbars
    > \gui {Filter Toolbar}.
 
    \section1 Adding Documentation
 
    To install and remove compressed help files, select \gui Edit >
    \gui Preferences > \gui Documentation.
 
    \image assistant-preferences-documentation.png {Screenshot showing the preference menu
           of the \QA to add or remove to the documentation list}
 
    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}.
 
    \section1 Specifying Home Page
 
    To specify the homepage \QA displays when you click the \gui{Home} button,
    select \gui Edit > \gui Preferences > \gui Options.
 
    \image assistant-preferences-options.png
 
    Enter the URL of the home page or select \gui{Current Page} to set the
    currently displayed page as your home page. To leave the home page blank,
    select \gui {Blank page}. Select \gui{Restore to default} to reset your home
    page to the default home page.
 
    \section1 Using Command Line Options
 
    \QA handles the following command line options:
 
    \table
        \header
            \li Command Line Option
            \li Brief Description
        \row
            \li -collectionFile <file.qhc>
            \li Uses the specified collection file instead of the default one.
        \row
            \li -showUrl <URL>
            \li Shows the document referenced by URL.
        \row
            \li -enableRemoteControl
            \li Enables \QA to be remotely controlled.
        \row
            \li -show <widget>
            \li Shows the specified sidebar window which can be "contents", "index",
            "bookmarks" or "search".
        \row
            \li -hide <widget>
            \li Hides the specified sidebar window which can be "contents", "index",
            "bookmarks" or "search".
        \row
            \li -activate <widget>
            \li Activates the specified sidebar window which can be "contents",
            "index", "bookmarks" or "search".
        \row
            \li -register <doc.qch>
            \li Registers the specified compressed help file in the given help
            collection.
        \row
            \li -unregister <doc.qch>
            \li Unregisters the specified compressed help file from the given
               collection file.
        \row
            \li -remove-search-index
            \li 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
            \li -rebuild-search-index
            \li Rebuilds the help search engine's index.
               Note that this operation may take a while to finish.
        \row
            \li -setCurrentFilter <filter>
            \li Sets the given filter as the active filter.
        \row
            \li -quiet
            \li Does not show any error, warning or success messages.
    \endtable
 
*/