--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/simpletextviewer.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,461 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \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
+ \o \c Assistant provides functionality to launch \QA.
+ \o \c MainWindow is the main application window.
+ \o \c FindFileDialog allows the user to search for
+ files using wildcard matching.
+ \o \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
+ \o Simple Text Viewer
+ \list
+ \o Find File
+ \list
+ \o File Dialog
+ \o Wildcard Matching
+ \o Browse
+ \endlist
+ \o 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 examples/help/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 examples/help/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 examples/help/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 examples/help/simpletextviewer/mainwindow.cpp 0
+ \dots
+ \snippet examples/help/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 examples/help/simpletextviewer/mainwindow.cpp 4
+ \dots
+ \snippet examples/help/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 examples/help/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 examples/help/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 examples/help/simpletextviewer/findfiledialog.cpp 0
+ \dots
+ \snippet examples/help/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 examples/help/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.
+*/