--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example help/simpletextviewer
+ \title Simple Text Viewer Example
+
+ The Simple Text Viewer example shows how to use \QA as a customized
+ help viewer for your application.
+
+ This is done in two stages. Firstly, documentation is created and \QA
+ is customized; secondly, the functionality to launch and control
+ \QA is added to the application.
+
+ \image simpletextviewer-example.png
+
+ The Simple Text Viewer application lets the user select and view
+ existing files.
+
+ The application provides its own custom documentation that is
+ available from the \gui Help menu in the main window's menu bar
+ or by clicking the \gui Help button in the application's find file
+ dialog.
+
+ The example consists of four classes:
+
+ \list
+ \li \c Assistant provides functionality to launch \QA.
+ \li \c MainWindow is the main application window.
+ \li \c FindFileDialog allows the user to search for
+ files using wildcard matching.
+ \li \c TextEdit provides a rich text browser that makes
+ sure that images referenced in HTML documents are
+ displayed properly.
+ \endlist
+
+ Note that we will only comment on the parts of the implementation
+ that are relevant to the main issue, that is making Qt Assistant
+ act as a customized help viewer for our Simple Text Viewer
+ application.
+
+ \section1 Creating Documentation and Customizing \QA
+
+ How to create the actual documentation in the form of HTML pages is
+ not in the scope of this example. In general, HTML pages can either
+ be written by hand or generated with the help of documentation tools
+ like qdoc or Doxygen. For the purposes of this example we assume that
+ the HTML files have already been created. So, the only thing that
+ remains to be done is to tell \QA how to structure and display the
+ help information.
+
+ \section2 Organizing Documentation for \QA
+
+ Plain HTML files only contain text or documentation about specific topics,
+ but they usually include no information about how several HTML documents
+ relate to each other or in which order they are supposed to be read.
+ What is missing is a table of contents along with an index to access
+ certain help contents quickly, without having to browse through a lot
+ of documents in order to find a piece of information.
+
+ To organize the documentation and make it available for \QA, we have
+ to create a Qt help project (.qhp) file. The first and most important
+ part of the project file is the definition of the namespace. The namespace
+ has to be unique and will be the first part of the page URL in \QA.
+ In addition, we have to set a virtual folder which acts as a common
+ folder for documentation sets. This means, that two documentation sets
+ identified by two different namespaces can cross reference HTML files
+ since those files are in one big virtual folder. However, for this
+ example, we'll only have one documentation set available, so the
+ virtual folder name and functionality are not important.
+
+ \code
+ <?xml version="1.0" encoding="UTF-8"?>
+ <QtHelpProject version="1.0">
+ <namespace>com.trolltech.examples.simpletextviewer</namespace>
+ <virtualFolder>doc</virtualFolder>
+ \endcode
+
+ The next step is to define the filter section. A filter section
+ contains the table of contents, indices and a complete list of
+ all documentation files, and can have any number of filter attributes
+ assigned to it. A filter attribute is an ordinary string which can
+ be freely chosen. Later in \QA, users can then define a custom
+ filter referencing those attributes. If the attributes of a filter
+ section match the attributes of the custom filter the documentation
+ will be shown, otherwise \QA will hide the documentation.
+
+ Again, since we'll only have one documentation set, we do not need
+ the filtering functionality of \QA and can therefore skip the
+ filter attributes.
+
+ Now, we build up the table of contents. An item in the table is
+ defined by the \c section tag which contains the attributes for the
+ item title as well as link to the actual page. Section tags can be
+ nested infinitely, but for practical reasons it is not recommended
+ to nest them deeper than three or four levels. For our example we
+ want to use the following outline for the table of contents:
+
+ \list
+ \li Simple Text Viewer
+ \list
+ \li Find File
+ \list
+ \li File Dialog
+ \li Wildcard Matching
+ \li Browse
+ \endlist
+ \li Open File
+ \endlist
+ \endlist
+
+ In the help project file, the outline is represented by:
+
+ \code
+ <filterSection>
+ <toc>
+ <section title="Simple Text Viewer" ref="index.html">
+ <section title="Find File" ref="./findfile.html">
+ <section title="File Dialog" ref="./filedialog.html"></section>
+ <section title="Wildcard Matching" ref="./wildcardmatching.html"></section>
+ <section title="Browse" ref="./browse.html"></section>
+ </section>
+ <section title="Open File" ref="./openfile.html"></section>
+ </section>
+ </toc>
+ \endcode
+
+ After the table of contents is defined, we will list all index keywords:
+
+ \code
+ <keywords>
+ <keyword name="Display" ref="./index.html"/>
+ <keyword name="Rich text" ref="./index.html"/>
+ <keyword name="Plain text" ref="./index.html"/>
+ <keyword name="Find" ref="./findfile.html"/>
+ <keyword name="File menu" ref="./findfile.html"/>
+ <keyword name="File name" ref="./filedialog.html"/>
+ <keyword name="File dialog" ref="./filedialog.html"/>
+ <keyword name="File globbing" ref="./wildcardmatching.html"/>
+ <keyword name="Wildcard matching" ref="./wildcardmatching.html"/>
+ <keyword name="Wildcard syntax" ref="./wildcardmatching.html"/>
+ <keyword name="Browse" ref="./browse.html"/>
+ <keyword name="Directory" ref="./browse.html"/>
+ <keyword name="Open" ref="./openfile.html"/>
+ <keyword name="Select" ref="./openfile.html"/>
+ </keywords>
+ \endcode
+
+ As the last step, we have to list all files making up the documentation.
+ An important point to note here is that all files have to listed, including
+ image files, and even stylesheets if they are used.
+
+ \code
+ <files>
+ <file>browse.html</file>
+ <file>filedialog.html</file>
+ <file>findfile.html</file>
+ <file>index.html</file>
+ <file>intro.html</file>
+ <file>openfile.html</file>
+ <file>wildcardmatching.html</file>
+ <file>images/browse.png</file>
+ <file>images/*.png</file>
+ </files>
+ </filterSection>
+ </QtHelpProject>
+ \endcode
+
+ The help project file is now finished. If you want to see the resulting
+ documentation in \QA, you have to generate a Qt compressed help file
+ out of it and register it with the default help collection of \QA.
+
+ \code
+ qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
+ assistant -register simpletextviewer.qch
+ \endcode
+
+ If you start \QA now, you'll see the Simple Text Viewer documentation
+ beside the Qt documentation. This is OK for testing purposes, but
+ for the final version we want to only have the Simple Text Viewer
+ documentation in \QA.
+
+ \section2 Customizing \QA
+
+ The easiest way to make \QA only display the Simple Text Viewer
+ documentation is to create our own help collection file. A collection
+ file is stored in a binary format, similar to the compressed help file,
+ and generated from a help collection project file (*.qhcp). With
+ the help of a collection file, we can customize the appearance and even
+ some functionality offered by \QA.
+
+ At first, we change the window title and icon. Instead of showing "\QA"
+ it will show "Simple Text Viewer", so it is much clearer for the user
+ that the help viewer actually belongs to our application.
+
+ \code
+ <?xml version="1.0" encoding="UTF-8"?>
+ <QHelpCollectionProject version="1.0">
+ <assistant>
+ <title>Simple Text Viewer</title>
+ <applicationIcon>images/handbook.png</applicationIcon>
+ <cacheDirectory>Trolltech/SimpleTextViewer</cacheDirectory>
+ \endcode
+
+ The \c cacheDirectory tag specifies a subdirectory of the users
+ data directory (see the
+ \l{Using Qt Assistant as a Custom Help Viewer#Qt Help Collection Files}{Qt Help Collection Files})
+ where the cache file for the full text search or the settings file will
+ be stored.
+
+ After this, we set the page displayed by \QA when launched for the very
+ first time in its new configuration. The URL consists of the namespace
+ and virtual folder defined in the Qt help project file, followed by the
+ actual page file name.
+
+ \code
+ <startPage>qthelp://com.trolltech.examples.simpletextviewer/doc/index.html</startPage>
+ \endcode
+
+ Next, we alter the name of the "About" menu item to "About Simple
+ Text Viewer". The contents of the \gui{About} dialog are also changed
+ by specifying a file where the about text or icon is taken from.
+
+ \code
+ <aboutMenuText>
+ <text>About Simple Text Viewer</text>
+ </aboutMenuText>
+ <aboutDialog>
+ <file>about.txt</file>
+ <icon>images/icon.png</icon>
+ </aboutDialog>
+ \endcode
+
+ \QA offers the possibility to add or remove documentation via its
+ preferences dialog. This functionality is helpful when using \QA
+ as the central help viewer for more applications, but in our case
+ we want to actually prevent the user from removing the documentation.
+ So, we disable the documentation manager.
+
+ Since the address bar is not really relevant in such a small
+ documentation set we switch it off as well. By having just one filter
+ section, without any filter attributes, we can also disable the filter
+ functionality of \QA, which means that the filter page and the filter
+ toolbar will not be available.
+
+ \code
+ <enableDocumentationManager>false</enableDocumentationManager>
+ <enableAddressBar>false</enableAddressBar>
+ <enableFilterFunctionality>false</enableFilterFunctionality>
+ </assistant>
+ \endcode
+
+ For testing purposes, we already generated the compressed help file
+ and registered it with \QA's default help collection. With the
+ following lines we achieve the same result. The only and important
+ difference is that we register the compressed help file, not in
+ the default collection, but in our own collection file.
+
+ \code
+ <docFiles>
+ <generate>
+ <file>
+ <input>simpletextviewer.qhp</input>
+ <output>simpletextviewer.qch</output>
+ </file>
+ </generate>
+ <register>
+ <file>simpletextviewer.qch</file>
+ </register>
+ </docFiles>
+ </QHelpCollectionProject>
+ \endcode
+
+ As the last step, we have to generate the binary collection file
+ out of the help collection project file. This is done by running the
+ \c qcollectiongenerator tool.
+
+ \code
+ qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc
+ \endcode
+
+ To test all our customizations made to \QA, we add the collection
+ file name to the command line:
+
+ \code
+ assistant -collectionFile simpletextviewer.qhc
+ \endcode
+
+ \section1 Controlling \QA via the Assistant Class
+
+ We will first take a look at how to start and operate \QA from a
+ remote application. For that purpose, we create a class called
+ \c Assistant.
+
+ This class provides a public function that is used to show pages
+ of the documentation, and one private helper function to make sure
+ that \QA is up and running.
+
+ Launching \QA is done in the function \c startAssistant() by simply
+ creating and starting a QProcess. If the process is already running,
+ the function returns immediately. Otherwise, the process has
+ to be set up and started.
+
+ \snippet simpletextviewer/assistant.cpp 2
+
+ To start the process we need the executable name of \QA as well as the
+ command line arguments for running \QA in a customized mode. The
+ executable name is a little bit tricky since it depends on the
+ platform, but fortunately it is only different on Mac OS X.
+
+ The displayed documentation can be altered using the \c -collectionFile
+ command line argument when launching \QA. When started without any options,
+ \QA displays a default set of documentation. When Qt is installed,
+ the default documentation set in \QA contains the Qt reference
+ documentation as well as the tools that come with Qt, such as Qt
+ Designer and \c qmake.
+
+ In our example, we replace the default documentation set with our
+ custom documentation by passing our application-specific collection
+ file to the process's command line options.
+
+ As the last argument, we add \c -enableRemoteControl, which makes \QA
+ listen to its \c stdin channel for commands, such as those to display
+ a certain page in the documentation.
+ Then we start the process and wait until it is actually running. If,
+ for some reason \QA cannot be started, \c startAssistant() will return
+ false.
+
+ The implementation for \c showDocumentation() is now straightforward.
+ Firstly, we ensure that \QA is running, then we send the request to
+ display the \a page via the \c stdin channel of the process. It is very
+ important here that the command is terminated by the '\\0' character
+ followed by an end of line token to flush the channel.
+
+ \snippet simpletextviewer/assistant.cpp 1
+
+ Finally, we make sure that \QA is terminated properly in the case that
+ the application is shut down. The destructor of QProcess kills the
+ process, meaning that the application has no possibility to do things
+ like save user settings, which would result in corrupted settings files.
+ To avoid this, we ask \QA to terminate in the destructor of the
+ \c Assistant class.
+
+ \snippet simpletextviewer/assistant.cpp 0
+
+ \section1 MainWindow Class
+
+ \image simpletextviewer-mainwindow.png
+
+ The \c MainWindow class provides the main application window with
+ two menus: the \gui File menu lets the user open and view an
+ existing file, while the \gui Help menu provides information about
+ the application and about Qt, and lets the user open \QA to
+ display the application's documentation.
+
+ To be able to access the help functionality, we initialize the
+ \c Assistant object in the \c MainWindow's constructor.
+
+ \snippet simpletextviewer/mainwindow.cpp 0
+ \dots
+ \snippet simpletextviewer/mainwindow.cpp 1
+
+ Then we create all the actions for the Simple Text Viewer application.
+ Of special interest is the \c assistantAct action accessible
+ via the \key{F1} shortcut or the \menu{Help|Help Contents} menu item.
+ This action is connected to the \c showDocumentation() slot of
+ the \c MainWindow class.
+
+ \snippet simpletextviewer/mainwindow.cpp 4
+ \dots
+ \snippet simpletextviewer/mainwindow.cpp 5
+
+ In the \c showDocumentation() slot, we call the \c showDocumentation()
+ function of the \c Assistant class with the URL of home page of the
+ documentation.
+
+ \snippet simpletextviewer/mainwindow.cpp 3
+
+ Finally, we must reimplement the protected QWidget::closeEvent()
+ event handler to ensure that the application's \QA instance is
+ properly closed before we terminate the application.
+
+ \snippet simpletextviewer/mainwindow.cpp 2
+
+ \section1 FindFileDialog Class
+
+ \image simpletextviewer-findfiledialog.png
+
+ The Simple Text Viewer application provides a find file dialog
+ allowing the user to search for files using wildcard matching. The
+ search is performed within the specified directory, and the user
+ is given an option to browse the existing file system to find the
+ relevant directory.
+
+ In the constructor we save the references to the \c Assistant
+ and \c QTextEdit objects passed as arguments. The \c Assistant
+ object will be used in the \c FindFileDialog's \c help() slot,
+ as we will see shortly, while the QTextEdit will be used in the
+ dialog's \c openFile() slot to display the chosen file.
+
+ \snippet simpletextviewer/findfiledialog.cpp 0
+ \dots
+ \snippet simpletextviewer/findfiledialog.cpp 1
+
+ The most relevant member to observe in the \c FindFileDialog
+ class is the private \c help() slot. The slot is connected to the
+ dialog's \gui Help button, and brings the current \QA instance
+ to the foreground with the documentation for the dialog by
+ calling \c Assistant's \c showDocumentation() function.
+
+ \snippet simpletextviewer/findfiledialog.cpp 2
+
+ \section1 Summary
+
+ In order to make \QA act as a customized help tool for
+ your application, you must provide your application with a
+ process that controls \QA in addition to a custom help collection
+ file including Qt compressed help files.
+
+ The \l{Using Qt Assistant as a Custom Help Viewer} document contains
+ more information about the options and settings available to
+ applications that use \QA as a custom help viewer.
+*/
include(../../shared/fontpanel/fontpanel.pri)
+QMAKE_DOCS = $$PWD/doc/assistant.qdocconf
+
# ## Work around a qmake issue when statically linking to
# ## not-yet-installed plugins
QMAKE_LIBDIR += $$QT.core.plugins/sqldrivers
+++ /dev/null
-How to build/ update a new assistant.qch for Assistant internal help
-
-- update:
- - open assistant.qdocconf, update year and qt version
-
- - ..\..\..\..\qdoc3\debug\qdoc3.exe assistant.qdocconf
- will generate an folder html containing all required stuff
-
- - cp assistant.qhp to generated html folder
- - run qhelpgenerator html\assistant.qhp -o ..\assistant.qch
-
- - rebuild assistant
-
-- to test your changes:
- - remove assistant.qch in your cache directory
- - restart assistant
+++ /dev/null
-/****************************************************************************
-**
-** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and Digia. For licensing terms and
-** conditions see http://qt.digia.com/licensing. For further information
-** use the contact form at http://qt.digia.com/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page assistant.html
- \title Qt Assistant
-
- \chapter Introduction
-
- This document introduces \e{Qt Assistant}, a tool for presenting on-line
- documentation. It also introduces the Qt Reference Documentation which
- is accessible using \e{Qt Assistant}, or with a web browser. The document is
- divided into the following sections:
-
- Table of contents:
-
- \list
- \li \l{Introduction}
- \li \l{The One-Minute Guide to Using Qt Assistant}
- \li \l{Introduction to the Qt Reference Documentation}
- \li \l{Qt Assistant in More Detail}
- \li \l{Full Text Searching}
- \endlist
-
- \chapter The One-Minute Guide to Using Qt Assistant
-
- Once you have installed Qt, \QA should be ready to run:
-
- \list
- \li On Windows, \QA is available as a menu option on the Qt menu.
- \li On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory.
- \li 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.
-
- \chapter Introduction to the Qt Reference Documentation
-
- The documentation for the Qt library is written in-line in the \c
- .cpp files by the developers themselves. The documentation team
- revises the documentation to ensure that it is accurate and usable,
- and to provide quality control. The documentation team also writes the
- larger texts, such as the class descriptions that introduce a class
- along with the concepts the class uses, as well as introducing the
- functions and properties that the class provides.
-
- The documentation focuses on the API rather than the internals, since
- we make great efforts to keep our API consistent and compatible with
- each new version, but we may change the internals considerably to improve
- performance and enhance functionality.
-
- The Qt Reference Documentation consists of almost 1,500 HTML pages
- (over 2,500 printed pages). The overwhelming majority of pages
- document Qt classes. Since developers differ in the way they
- think and work we provide a variety of approaches to navigating the
- documentation set:
-
- \list
- \li The \menu{Qt's Classes} page lists every class
- in Qt's public API, and consists of several hundred classes.
- \li The \menu{Qt's Main Classes} page lists the
- classes you're most likely to use most often, and provides a much
- shorter and more managable list than the All Classes list.
- \li The \menu{Grouped Classes} page presents a list
- of groups, each of which leads to a list of related classes, for
- example, the \menu{Advanced Widgets} list.
- \li The \menu{Class Inheritance Hierarchy} page
- presents a list of classes in terms of the hierarchy of Qt classes.
- \li The \menu{Member Function Index} page lists all the
- functions provided by Qt classes, each one with links to the class(es)
- in which it appears.
- \endlist
-
- No matter where you find yourself in the Qt documentation, you will
- find extensive cross-referencing. Even snippets of example code
- contain clickable links, so that for example, if you come across a
- class declaration in a code example, the class name will be a
- clickable link to the class's documentation.
-
- In addition to the class documentation some of Qt's modules have
- extensive descriptions, and there are many overview documents which
- describe various aspects of the Qt library; all these are linked from
- the reference documentation home page. There are also two tutorials
- and numerous example programs in the examples subdirectory of the Qt
- distribution.
-
- \chapter Qt Assistant in More Detail
-
- \img assistant-assistant.png
-
- \section1 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 remotly controlled.
- \row
- \li -show <widget>
- \li Shows the specified dockwidget which can be "contents", "index",
- "bookmarks" or "search".
- \row
- \li -hide <widget>
- \li Hides the specified dockwidget which can be "contents", "index",
- "bookmarks" or "search.
- \row
- \li -activate <widget>
- \li Activates the specified dockwidget 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 -quiet
- \li 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
- \li 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.
- \li 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.
- \li 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 \li Action \li Description \li Menu Item \li Shortcut
- \row \li \gui{Previous} \li Takes you to the previous page in the history.
- \li \menu{Go|Previous} \li \key{Alt+Left Arrow}
- \row \li \gui{Next} \li Takes you to the next page in the history.
- \li \menu{Go|Next} \li \key{Alt+Right Arrow}
- \row \li \gui{Home}
- \li Takes you to the home page as specified in the Preferences Dialog.
- \li \menu{Go|Home} \li \key{Ctrl+Home}.
- \row \li \gui{Sync with Table of Contents}
- \li Synchronizes the \gui{Contents} tool window with the page currently
- shown in the \gui{Documentation} window.
- \li \menu{Go|Sync with Table of Contents} \li
- \row \li \gui{Copy} \li Copies any selected text to the clipboard.
- \li \menu{Edit|Copy} \li \key{Ctrl+C}
- \row \li \gui{Print} \li Opens the \gui{Print} dialog.
- \li \menu{File|Print} \li \key{Ctrl+P}
- \row \li \gui{Find in Text} \li Opens the \gui{Find Text} dialog.
- \li \menu{Edit|Find in Text} \li \key{Ctrl+F}
- \row \li \gui{Zoom in}
- \li Increases the font size used to display text in the current tab.
- \li \menu{View|Zoom in} \li \key{Ctrl++}
- \row \li \gui{Zoom out}
- \li Decreases the font size used to display text in the current tab.
- \li \menu{View|Zoom out} \li \key{Ctrl+-}
- \row \li \gui{Normal Size}
- \li Resets the font size to its normal size in the current tab.
- \li \menu{View|Normal Size} \li \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
- \li \menu{File|Page Setup...} invokes a dialog allowing you to define
- page layout properties, such as margin sizes, page orientation and paper size.
- \li \menu{File|Print Preview...} provides a preview of the printed pages.
- \li \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}.
- \li \menu{File|New Tab} opens a new empty tab in the \gui{Documentation}
- window.
- \li \menu{File|Close Tab} closes the current tab of the
- \gui{Documentation} window.
- \li \menu{File|Exit} closes the \QA application.
- \endlist
-
- \section2 Edit Menu
-
- \list
- \li \menu{Edit|Copy} copies any selected text to the clipboard.
- \li \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text}
- control} at the lower end of the \gui{Documentation} window.
- \li \menu{Edit|Find Next} looks for the next occurance of the specified
- text in the \gui{Find Text} control.
- \li \menu{Edit|Find Previous} looks for the previous occurance of
- the specified text in the \l{#Find Text Control}{\gui{Find Text} control}.
- \li \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}.
- \endlist
-
- \section2 View Menu
-
- \list
- \li \menu{View|Zoom in} increases the font size in the current tab.
- \li \menu{View|Zoom out} decreases the font size in the current tab.
- \li \menu{View|Normal Size} resets the font size in the current tab.
- \li \menu{View|Contents} toggles the display of the \gui{Contents} tool window.
- \li \menu{View|Index} toggles the display of the \gui{Index} tool window.
- \li \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window.
- \li \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window.
- \endlist
-
- \section2 Go Menu
-
- \list
- \li \menu{Go|Home} goes to the home page.
- \li \menu{Go|Back} displays the previous page in the history.
- \li \menu{Go|Forward} displays the next page in the history.
- \li \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page.
- \li \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window.
- \li \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window.
- \endlist
-
- \section2 Bookmarks Menu
-
- \list
- \li \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
- \li \c deep -- lists all the documents that contain the word 'deep'
- \li \c{deep*} -- lists all the documents that contain a word beginning
- with 'deep'
- \li \c{deep copy} -- lists all documents that contain both 'deep' \e
- and 'copy'
- \li \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
- \li \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString}
- \li \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString}
- \li \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.
-*/
-include(../../../../qdoc3/test/qt.qdocconf)
-
-version =
-
-sourcedirs = $QTDIR/tools/assistant/tools/assistant/doc
-imagedirs = $QTDIR/tools/assistant/tools/assistant/doc/images
-outputdir = $QTDIR/tools/assistant/tools/assistant/doc/html
-project = assistant
-description = "Qt Assistant"
-HTML.{postheader,address} = ""
-HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
- "<table width=\"100%\" cellspacing=\"0\" border=\"0\"><tr class=\"address\">\n" \
- "<td width=\"30%\" align=\"left\">Copyright © 2012 Digia Plc and/or its subsidiary(-ies)</td>\n" \
- "<td width=\"40%\" align=\"center\">Trademarks</td>\n" \
- "<td width=\"30%\" align=\"right\"><div align=\"right\">Qt 5.0.0</div></td>\n" \
- "</tr></table></div></address>"
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+
+project = Qt Assistant
+description = Qt Assistant Manual
+url = http://qt-project.org/doc/qtassistant
+
+qhp.projects = Assistant
+
+qhp.Assistant.file = assistant.qhp
+qhp.Assistant.namespace = com.qt-project.assistant.500
+qhp.Assistant.virtualFolder = assistant
+qhp.Assistant.indexTitle = Qt Assistant Manual
+
+qhp.Assistant.filterAttributes = qt 5.0.0 tools assistant
+qhp.Assistant.customFilters.Assistant.name = Qt Assistant Manual
+qhp.Assistant.customFilters.Assistant.filterAttributes = qt tools assistant
+qhp.Assistant.subprojects = manual examples
+qhp.Assistant.subprojects.manual.title = Manual
+qhp.Assistant.subprojects.manual.indexTitle = Qt Assistant Manual
+qhp.Assistant.subprojects.manual.selectors = fake:page
+qhp.Assistant.subprojects.examples.title = Examples
+qhp.Assistant.subprojects.examples.indexTitle = Qt Examples
+qhp.Assistant.subprojects.examples.selectors = fake:example
+qhp.Assistant.subprojects.examples.sortPages = true
+
+language = Cpp
+
+sourcedirs = ..
+
+exampledirs = ../../../../examples \
+ snippets
+
+imagedirs = images
+
+outputdir = $QT_INSTALL_DOCS/assistant
+
+depends += qtdoc
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<QtHelpProject version="1.0">
- <virtualFolder>assistant</virtualFolder>
- <namespace>com.trolltech.com.assistantinternal-1.0.0</namespace>
- <filterSection>
- <files>
- <file>assistant.html</file>
- <file>classic.css</file>
- <file>images/assistant-address-toolbar.png</file>
- <file>images/assistant-assistant.png</file>
- <file>images/assistant-dockwidgets.png</file>
- <file>images/assistant-docwindow.png</file>
- <file>images/assistant-filter-toolbar.png</file>
- <file>images/assistant-preferences-documentation.png</file>
- <file>images/assistant-preferences-filters.png</file>
- <file>images/assistant-preferences-fonts.png</file>
- <file>images/assistant-preferences-options.png</file>
- <file>images/assistant-search.png</file>
- <file>images/assistant-toolbar.png</file>
- </files>
- </filterSection>
-</QtHelpProject>
+++ /dev/null
-h3.fn,span.fn
-{
- margin-left: 1cm;
- text-indent: -1cm;
-}
-
-a:link
-{
- color: #004faf;
- text-decoration: none
-}
-
-a:visited
-{
- color: #672967;
- text-decoration: none
-}
-
-td.postheader
-{
- font-family: sans-serif
-}
-
-tr.address
-{
- font-family: sans-serif
-}
-
-body
-{
- background: #ffffff;
- color: black
-}
-
-table tr.odd {
- background: #f0f0f0;
- color: black;
-}
-
-table tr.even {
- background: #e4e4e4;
- color: black;
-}
-
-table.annotated th {
- padding: 3px;
- text-align: left
-}
-
-table.annotated td {
- padding: 3px;
-}
-
-table tr pre
-{
- padding-top: none;
- padding-bottom: none;
- padding-left: none;
- padding-right: none;
- border: none;
- background: none
-}
-
-tr.qt-style
-{
- background: #a2c511;
- color: black
-}
-
-body pre
-{
- padding: 0.2em;
- border: #e7e7e7 1px solid;
- background: #f1f1f1;
- color: black
-}
-
-span.preprocessor, span.preprocessor a
-{
- color: darkblue;
-}
-
-span.comment
-{
- color: darkred;
- font-style: italic
-}
-
-span.string,span.char
-{
- color: darkgreen;
-}
--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+** of its contributors may be used to endorse or promote products derived
+** from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+assistant -collectionFile file
+//! [0]
+
+
+//! [1]
+<?xml version="1.0" encoding="utf-8" ?>
+<QHelpCollectionProject version="1.0">
+ <assistant>
+ <title>My Application Help</title>
+ <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
+ <currentFilter>myfilter</currentFilter>
+ <applicationIcon>application.png</applicationIcon>
+ <enableFilterFunctionality>false</enableFilterFunctionality>
+ <enableDocumentationManager>false</enableDocumentationManager>
+ <enableAddressBar visible="true">true</enableAddressBar>
+ <cacheDirectory>mycompany/myapplication</cacheDirectory>
+ <aboutMenuText>
+ <text>About My Application</text>
+ <text language="de">Über meine Applikation...</text>
+ </aboutMenuText>
+ <aboutDialog>
+ <file>about.txt</file>
+ <file language="de">ueber.txt</file>
+ <icon>about.png</icon>
+ </aboutDialog>
+ </assistant>
+ <docFiles>
+ <generate>
+ <file>
+ <input>myapplication-manual.qhp</input>
+ <output>myapplication-manual.qch</output>
+ </file>
+ </generate>
+ <register>
+ <file>myapplication-manual.qch</file>
+ </register>
+ </docFiles>
+</QHelpCollectionProject>
+//! [1]
+
+
+//! [2]
+QProcess *process = new QProcess;
+QStringList args;
+args << QLatin1String("-collectionFile")
+ << QLatin1String("mycollection.qhc")
+ << QLatin1String("-enableRemoteControl");
+process->start(QLatin1String("assistant"), args);
+if (!process->waitForStarted())
+ return;
+//! [2]
+
+
+//! [3]
+QByteArray ba;
+ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
+process->write(ba);
+//! [3]
+
+
+//! [4]
+QByteArray ba;
+ba.append("hide bookmarks;");
+ba.append("hide index;");
+ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
+process->write(ba);
+//! [4]
+
+//! [5]
+<?xml version="1.0" encoding="utf-8" ?>
+<QHelpCollectionProject version="1.0">
+ ...
+ <docFiles>
+ <register>
+ <file>myapplication-manual.qch</file>
+ <file>another-manual.qch</file>
+ </register>
+ </docFiles>
+</QHelpCollectionProject>
+//! [5]
+
+//! [6]
+assistant -collectionFile mycollection.qhc -register myapplication-manual.qch
+//! [6]
+
+//! [7]
+<?xml version="1.0" encoding="utf-8" ?>
+<QHelpCollectionProject version="1.0">
+ <assistant>
+ <title>My Application Help</title>
+ <cacheDirectory>mycompany/myapplication</cacheDirectory>
+ ...
+ </assistant>
+</QHelpCollectionProject>
+//! [7]
+
+//! [8]
+assistant -collectionFile mycollection.qhc
+//! [8]
+
+//! [9]
+%QDesktopServices::DataLocation%/mycompany/myapplication/mycollection.qhc
+//! [9]
+
+//! [10]
+qcollectiongenerator mycollection.qhcp -o mycollection.qhc
+//! [10]
--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+** of its contributors may be used to endorse or promote products derived
+** from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtCore/QByteArray>
+#include <QtCore/QDir>
+#include <QtCore/QLibraryInfo>
+#include <QtCore/QProcess>
+
+#include <QtWidgets/QMessageBox>
+
+#include "assistant.h"
+
+Assistant::Assistant()
+ : proc(0)
+{
+}
+
+//! [0]
+Assistant::~Assistant()
+{
+ if (proc && proc->state() == QProcess::Running) {
+ proc->terminate();
+ proc->waitForFinished(3000);
+ }
+ delete proc;
+}
+//! [0]
+
+//! [1]
+void Assistant::showDocumentation(const QString &page)
+{
+ if (!startAssistant())
+ return;
+
+ QByteArray ba("SetSource ");
+ ba.append("qthelp://com.trolltech.examples.simpletextviewer/doc/");
+
+ proc->write(ba + page.toLocal8Bit() + '\n');
+}
+//! [1]
+
+//! [2]
+bool Assistant::startAssistant()
+{
+ if (!proc)
+ proc = new QProcess();
+
+ if (proc->state() != QProcess::Running) {
+ QString app = QLibraryInfo::location(QLibraryInfo::BinariesPath) + QDir::separator();
+#if !defined(Q_OS_MAC)
+ app += QLatin1String("assistant");
+#else
+ app += QLatin1String("Assistant.app/Contents/MacOS/Assistant");
+#endif
+
+ QStringList args;
+ args << QLatin1String("-collectionFile")
+ << QLibraryInfo::location(QLibraryInfo::ExamplesPath)
+ + QLatin1String("/help/simpletextviewer/documentation/simpletextviewer.qhc")
+ << QLatin1String("-enableRemoteControl");
+
+ proc->start(app, args);
+
+ if (!proc->waitForStarted()) {
+ QMessageBox::critical(0, QObject::tr("Simple Text Viewer"),
+ QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
+ return false;
+ }
+ }
+ return true;
+}
+//! [2]
--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+** of its contributors may be used to endorse or promote products derived
+** from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtCore/QDir>
+#include <QtWidgets/QLayout>
+#include <QtWidgets/QComboBox>
+#include <QtWidgets/QTreeWidget>
+#include <QtWidgets/QLayout>
+#include <QtWidgets/QFileDialog>
+#include <QtWidgets/QDialogButtonBox>
+#include <QtWidgets/QToolButton>
+#include <QtWidgets/QPushButton>
+#include <QtWidgets/QLabel>
+
+#include "findfiledialog.h"
+#include "assistant.h"
+#include "textedit.h"
+
+//! [0]
+FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant)
+ : QDialog(editor)
+{
+ currentAssistant = assistant;
+ currentEditor = editor;
+//! [0]
+
+ createButtons();
+ createComboBoxes();
+ createFilesTree();
+ createLabels();
+ createLayout();
+
+ directoryComboBox->addItem(QDir::toNativeSeparators(QDir::currentPath()));
+ fileNameComboBox->addItem("*");
+ findFiles();
+
+ setWindowTitle(tr("Find File"));
+//! [1]
+}
+//! [1]
+
+void FindFileDialog::browse()
+{
+ QString currentDirectory = directoryComboBox->currentText();
+ QString newDirectory = QFileDialog::getExistingDirectory(this,
+ tr("Select Directory"), currentDirectory);
+ if (!newDirectory.isEmpty()) {
+ directoryComboBox->addItem(QDir::toNativeSeparators(newDirectory));
+ directoryComboBox->setCurrentIndex(directoryComboBox->count() - 1);
+ update();
+ }
+}
+
+//! [2]
+void FindFileDialog::help()
+{
+ currentAssistant->showDocumentation("filedialog.html");
+}
+//! [2]
+
+void FindFileDialog::openFile(QTreeWidgetItem *item)
+{
+ if (!item) {
+ item = foundFilesTree->currentItem();
+ if (!item)
+ return;
+ }
+
+ QString fileName = item->text(0);
+ QString path = directoryComboBox->currentText() + QDir::separator();
+
+ currentEditor->setContents(path + fileName);
+ close();
+}
+
+void FindFileDialog::update()
+{
+ findFiles();
+ buttonBox->button(QDialogButtonBox::Open)->setEnabled(
+ foundFilesTree->topLevelItemCount() > 0);
+}
+
+void FindFileDialog::findFiles()
+{
+ QRegExp filePattern(fileNameComboBox->currentText() + "*");
+ filePattern.setPatternSyntax(QRegExp::Wildcard);
+
+ QDir directory(directoryComboBox->currentText());
+
+ QStringList allFiles = directory.entryList(QDir::Files | QDir::NoSymLinks);
+ QStringList matchingFiles;
+
+ foreach (QString file, allFiles) {
+ if (filePattern.exactMatch(file))
+ matchingFiles << file;
+ }
+ showFiles(matchingFiles);
+}
+
+void FindFileDialog::showFiles(const QStringList &files)
+{
+ foundFilesTree->clear();
+
+ for (int i = 0; i < files.count(); ++i) {
+ QTreeWidgetItem *item = new QTreeWidgetItem(foundFilesTree);
+ item->setText(0, files[i]);
+ }
+
+ if (files.count() > 0)
+ foundFilesTree->setCurrentItem(foundFilesTree->topLevelItem(0));
+}
+
+void FindFileDialog::createButtons()
+{
+ browseButton = new QToolButton;
+ browseButton->setText(tr("..."));
+ connect(browseButton, SIGNAL(clicked()), this, SLOT(browse()));
+
+ buttonBox = new QDialogButtonBox(QDialogButtonBox::Open
+ | QDialogButtonBox::Cancel
+ | QDialogButtonBox::Help);
+ connect(buttonBox, SIGNAL(accepted()), this, SLOT(openFile()));
+ connect(buttonBox, SIGNAL(rejected()), this, SLOT(reject()));
+ connect(buttonBox, SIGNAL(helpRequested()), this, SLOT(help()));
+}
+
+void FindFileDialog::createComboBoxes()
+{
+ directoryComboBox = new QComboBox;
+ fileNameComboBox = new QComboBox;
+
+ fileNameComboBox->setEditable(true);
+ fileNameComboBox->setSizePolicy(QSizePolicy::Expanding,
+ QSizePolicy::Preferred);
+
+ directoryComboBox->setMinimumContentsLength(30);
+ directoryComboBox->setSizeAdjustPolicy(
+ QComboBox::AdjustToMinimumContentsLength);
+ directoryComboBox->setSizePolicy(QSizePolicy::Expanding,
+ QSizePolicy::Preferred);
+
+ connect(fileNameComboBox, SIGNAL(editTextChanged(QString)),
+ this, SLOT(update()));
+ connect(directoryComboBox, SIGNAL(currentIndexChanged(QString)),
+ this, SLOT(update()));
+}
+
+void FindFileDialog::createFilesTree()
+{
+ foundFilesTree = new QTreeWidget;
+ foundFilesTree->setColumnCount(1);
+ foundFilesTree->setHeaderLabels(QStringList(tr("Matching Files")));
+ foundFilesTree->setRootIsDecorated(false);
+ foundFilesTree->setSelectionMode(QAbstractItemView::SingleSelection);
+
+ connect(foundFilesTree, SIGNAL(itemActivated(QTreeWidgetItem*,int)),
+ this, SLOT(openFile(QTreeWidgetItem*)));
+}
+
+void FindFileDialog::createLabels()
+{
+ directoryLabel = new QLabel(tr("Search in:"));
+ fileNameLabel = new QLabel(tr("File name (including wildcards):"));
+}
+
+void FindFileDialog::createLayout()
+{
+ QHBoxLayout *fileLayout = new QHBoxLayout;
+ fileLayout->addWidget(fileNameLabel);
+ fileLayout->addWidget(fileNameComboBox);
+
+ QHBoxLayout *directoryLayout = new QHBoxLayout;
+ directoryLayout->addWidget(directoryLabel);
+ directoryLayout->addWidget(directoryComboBox);
+ directoryLayout->addWidget(browseButton);
+
+ QVBoxLayout *mainLayout = new QVBoxLayout;
+ mainLayout->addLayout(fileLayout);
+ mainLayout->addLayout(directoryLayout);
+ mainLayout->addWidget(foundFilesTree);
+ mainLayout->addStretch();
+ mainLayout->addWidget(buttonBox);
+ setLayout(mainLayout);
+}
--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the examples of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
+** of its contributors may be used to endorse or promote products derived
+** from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtCore/QLibraryInfo>
+#include <QtWidgets/QApplication>
+#include <QtWidgets/QAction>
+#include <QtWidgets/QMenu>
+#include <QtWidgets/QMenuBar>
+#include <QtWidgets/QMessageBox>
+
+#include "mainwindow.h"
+#include "findfiledialog.h"
+#include "assistant.h"
+#include "textedit.h"
+
+// ![0]
+MainWindow::MainWindow()
+{
+ assistant = new Assistant;
+// ![0]
+ textViewer = new TextEdit;
+ textViewer->setContents(QLibraryInfo::location(QLibraryInfo::ExamplesPath)
+ + QLatin1String("/help/simpletextviewer/documentation/intro.html"));
+ setCentralWidget(textViewer);
+
+ createActions();
+ createMenus();
+
+ setWindowTitle(tr("Simple Text Viewer"));
+ resize(750, 400);
+// ![1]
+}
+//! [1]
+
+//! [2]
+void MainWindow::closeEvent(QCloseEvent *)
+{
+ delete assistant;
+}
+//! [2]
+
+void MainWindow::about()
+{
+ QMessageBox::about(this, tr("About Simple Text Viewer"),
+ tr("This example demonstrates how to use\n"
+ "Qt Assistant as help system for your\n"
+ "own application."));
+}
+
+//! [3]
+void MainWindow::showDocumentation()
+{
+ assistant->showDocumentation("index.html");
+}
+//! [3]
+
+void MainWindow::open()
+{
+ FindFileDialog dialog(textViewer, assistant);
+ dialog.exec();
+}
+
+//! [4]
+void MainWindow::createActions()
+{
+ assistantAct = new QAction(tr("Help Contents"), this);
+ assistantAct->setShortcut(QKeySequence::HelpContents);
+ connect(assistantAct, SIGNAL(triggered()), this, SLOT(showDocumentation()));
+//! [4]
+
+ openAct = new QAction(tr("&Open..."), this);
+ openAct->setShortcut(QKeySequence::Open);
+ connect(openAct, SIGNAL(triggered()), this, SLOT(open()));
+
+ clearAct = new QAction(tr("&Clear"), this);
+ clearAct->setShortcut(tr("Ctrl+C"));
+ connect(clearAct, SIGNAL(triggered()), textViewer, SLOT(clear()));
+
+ exitAct = new QAction(tr("E&xit"), this);
+ exitAct->setShortcuts(QKeySequence::Quit);
+ connect(exitAct, SIGNAL(triggered()), this, SLOT(close()));
+
+ aboutAct = new QAction(tr("&About"), this);
+ connect(aboutAct, SIGNAL(triggered()), this, SLOT(about()));
+
+ aboutQtAct = new QAction(tr("About &Qt"), this);
+ connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt()));
+//! [5]
+}
+//! [5]
+
+void MainWindow::createMenus()
+{
+ fileMenu = new QMenu(tr("&File"), this);
+ fileMenu->addAction(openAct);
+ fileMenu->addAction(clearAct);
+ fileMenu->addSeparator();
+ fileMenu->addAction(exitAct);
+
+ helpMenu = new QMenu(tr("&Help"), this);
+ helpMenu->addAction(assistantAct);
+ helpMenu->addSeparator();
+ helpMenu->addAction(aboutAct);
+ helpMenu->addAction(aboutQtAct);
+
+
+ menuBar()->addMenu(fileMenu);
+ menuBar()->addMenu(helpMenu);
+}
--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page assistant-manual.html
+ \title Qt Assistant Manual
+ \ingroup qttools
+
+ \startpage {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
+ \li \l{The One-Minute Guide to Using Qt Assistant}
+ \li \l{Qt Assistant in More Detail}
+ \li \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
+ \li On Windows, \QA is available as a menu option on the Qt menu.
+ \li On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory.
+ \li 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
+ \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 remotly controlled.
+ \row
+ \li -show <widget>
+ \li Shows the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search".
+ \row
+ \li -hide <widget>
+ \li Hides the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search.
+ \row
+ \li -activate <widget>
+ \li Activates the specified dockwidget 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 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
+ \li 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.
+ \li 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.
+ \li 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 \li Action \li Description \li Menu Item \li Shortcut
+ \row \li \gui{Previous} \li Takes you to the previous page in the history.
+ \li \menu{Go|Previous} \li \key{Alt+Left Arrow}
+ \row \li \gui{Next} \li Takes you to the next page in the history.
+ \li \menu{Go|Next} \li \key{Alt+Right Arrow}
+ \row \li \gui{Home}
+ \li Takes you to the home page as specified in the Preferences Dialog.
+ \li \menu{Go|Home} \li \key{Ctrl+Home}.
+ \row \li \gui{Sync with Table of Contents}
+ \li Synchronizes the \gui{Contents} tool window with the page currently
+ shown in the \gui{Documentation} window.
+ \li \menu{Go|Sync with Table of Contents} \li
+ \row \li \gui{Copy} \li Copies any selected text to the clipboard.
+ \li \menu{Edit|Copy} \li \key{Ctrl+C}
+ \row \li \gui{Print} \li Opens the \gui{Print} dialog.
+ \li \menu{File|Print} \li \key{Ctrl+P}
+ \row \li \gui{Find in Text} \li Opens the \gui{Find Text} dialog.
+ \li \menu{Edit|Find in Text} \li \key{Ctrl+F}
+ \row \li \gui{Zoom in}
+ \li Increases the font size used to display text in the current tab.
+ \li \menu{View|Zoom in} \li \key{Ctrl++}
+ \row \li \gui{Zoom out}
+ \li Decreases the font size used to display text in the current tab.
+ \li \menu{View|Zoom out} \li \key{Ctrl+-}
+ \row \li \gui{Normal Size}
+ \li Resets the font size to its normal size in the current tab.
+ \li \menu{View|Normal Size} \li \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
+ \li \menu{File|Page Setup...} invokes a dialog allowing you to define
+ page layout properties, such as margin sizes, page orientation and paper size.
+ \li \menu{File|Print Preview...} provides a preview of the printed pages.
+ \li \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}.
+ \li \menu{File|New Tab} opens a new empty tab in the \gui{Documentation}
+ window.
+ \li \menu{File|Close Tab} closes the current tab of the
+ \gui{Documentation} window.
+ \li \menu{File|Exit} closes the \QA application.
+ \endlist
+
+ \section2 Edit Menu
+
+ \list
+ \li \menu{Edit|Copy} copies any selected text to the clipboard.
+ \li \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text}
+ control} at the lower end of the \gui{Documentation} window.
+ \li \menu{Edit|Find Next} looks for the next occurance of the specified
+ text in the \gui{Find Text} control.
+ \li \menu{Edit|Find Previous} looks for the previous occurance of
+ the specified text in the \l{#Find Text Control}{\gui{Find Text} control}.
+ \li \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}.
+ \endlist
+
+ \section2 View Menu
+
+ \list
+ \li \menu{View|Zoom in} increases the font size in the current tab.
+ \li \menu{View|Zoom out} decreases the font size in the current tab.
+ \li \menu{View|Normal Size} resets the font size in the current tab.
+ \li \menu{View|Contents} toggles the display of the \gui{Contents} tool window.
+ \li \menu{View|Index} toggles the display of the \gui{Index} tool window.
+ \li \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window.
+ \li \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window.
+ \endlist
+
+ \section2 Go Menu
+
+ \list
+ \li \menu{Go|Home} goes to the home page.
+ \li \menu{Go|Back} displays the previous page in the history.
+ \li \menu{Go|Forward} displays the next page in the history.
+ \li \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page.
+ \li \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window.
+ \li \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window.
+ \endlist
+
+ \section2 Bookmarks Menu
+
+ \list
+ \li \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 homepage 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
+ \li \c deep -- lists all the documents that contain the word 'deep'
+ \li \c{deep*} -- lists all the documents that contain a word beginning
+ with 'deep'
+ \li \c{deep copy} -- lists all documents that contain both 'deep' \e
+ and 'copy'
+ \li \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
+ \li \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString}
+ \li \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString}
+ \li \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_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_assistant-manual.qdoc 7
+
+ So, when calling
+
+ \snippet doc_src_assistant-manual.qdoc 8
+
+ \QA actually uses the collection file:
+
+ \snippet 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_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_assistant-manual.qdoc 6
+
+ The \c{-quiet} flag can be passed on to \QA to prevent it from writing
+ out the status message.
+
+ \b{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
+ \li Tag
+ \li Brief Description
+ \row
+ \li \c{<title>}
+ \li This property is used to specify a window title for \QA.
+ \row
+ \li \c{<homePage>}
+ \li This tag specifies which page should be display when
+ pressing the home button in \QA's main user interface.
+ \row
+ \li \c{<startPage>}
+ \li This tag specifies which page \QA should initially
+ display when the help collection is used.
+ \row
+ \li \c{<currentFilter>}
+ \li 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
+ \li \c{<applicationIcon>}
+ \li 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
+ \li \c{<enableFilterFunctionality>}
+ \li 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
+ \li \c{<enableDocumentationManager>}
+ \li 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
+ \li \c{<enableAddressBar>}
+ \li 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
+ \li \c{<aboutMenuText>, <text>}
+ \li 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
+ \li \c{<aboutDialog>, <file>, <icon>}
+ \li 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
+ \li \c{<cacheDirectory base="collection|default">}
+ \li The cache directory 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.
+ The directory is specified as a relative path.
+ If the \c{base} attribute is set to "collection", the path is
+ relative to the directory the collection file resides in.
+ If the attribute is set to "default" or if it is missing,
+ the path is relative to the directory given by
+ QDesktopServices::DataLocation. The first form is useful for
+ collections that are used in a "mobile" way, e.g. carried around
+ on a USB stick.
+ \row
+ \li \c{<enableFullTextSearchFallback>}
+ \li This tag describes the ability to fallback and use the full text
+ search if a keyword can't be found in the index. This functionality
+ can be used while remote controlling \QA. To make it available for
+ remote control set the tag value to \c{true}.
+ \endtable
+
+ In addition to those \QA specific tags, the tags for generating and registering
+ documentation can be used. See \l{Qt Help Collection Project} documentation for more information.
+
+ An example of a help collection file that uses all the available tags is shown below:
+
+ \snippet doc_src_assistant-manual.qdoc 1
+
+ To create the binary collection file, run the \c qcollectiongenerator tool:
+
+ \snippet doc_src_assistant-manual.qdoc 10
+
+ To test the generated collection file, start \QA in the following way:
+
+ \snippet 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.
+
+ The following example shows how this can be done:
+
+ \snippet 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_assistant-manual.qdoc 3
+
+ Note that the trailing newline character is required to mark the end
+ of the input.
+
+ The following commands can be used to control \QA:
+
+ \table
+ \header
+ \li Command
+ \li Brief Description
+ \row
+ \li \c{show <Widget>}
+ \li 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
+ \li \c{hide <Widget>}
+ \li Hides the dock widget specified by <Widget>. Possible values for
+ <Widget> are "contents", "index", "bookmarks" and "search".
+ \row
+ \li \c{setSource <Url>}
+ \li 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
+ \li \c{activateKeyword <Keyword>}
+ \li 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
+ \li \c{activateIdentifier <Id>}
+ \li 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
+ \li \c{syncContents}
+ \li Selects the item in the contents widget which corresponds to
+ the currently displayed page.
+ \row
+ \li \c{setCurrentFilter <filter>}
+ \li Selects the specified filter and updates the visual representation
+ accordingly.
+ \row
+ \li \c{expandToc <Depth>}
+ \li Expands the table of contents tree to the given depth. If depth
+ is 0, the tree will be collapsed completely. If depth is -1,
+ the tree will be expanded completely.
+ \row
+ \li \c{register <help file>}
+ \li Adds the given Qt compressed help file to the collection.
+ \row
+ \li \c{unregister <help file>}
+ \li Removes the given Qt compressed help file from the collection.
+ \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_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_assistant-manual.qdoc 0
+
+ Other available options the can be passed on the command line.
+
+ \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 remotly controlled.
+ \row
+ \li -show <widget>
+ \li Shows the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search".
+ \row
+ \li -hide <widget>
+ \li Hides the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search.
+ \row
+ \li -activate <widget>
+ \li Activates the specified dockwidget 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 -quiet
+ \li Doesn't show any error, warning or success messages.
+ \endtable
+ */
projects / platform / upstream / qttools.git / commitdiff
