Home · All Classes · Main Classes · Grouped Classes · Modules · Functions

Simple Text Viewer Example

Files:

The Simple Text Viewer example shows how you can make Qt Assistant act as a customized help tool for your application using the QAssistantClient class combined with a Qt Assistant Document Profile.

The Simple Text Viewer application allows the user to select and view existing files.

The application provides its own custom documentation that is available through the Help menu in the main window's menubar and through the Help button in the application's find file dialog. The documentation files are located in a separate documentation subdirectory.

The example consists of two classes:

MainWindow is the main application window.
FindFileDialog allows the user to search for files using wildcard matching.

First we will take a look at how the QAssistantClient is implemented in the MainWindow class. At the same time we will see how we can make the Qt Assistant display custom documentation using the Qt Assistant Document Profile (.adp) format. Then we will review the FindFileDialog class.

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-tool for our Simple Text Viewer application.

MainWindow Class Definition

The MainWindow class provides the main application window with two menus: The File menu lets the user open and view an existing file while the Help menu provides information about the application and about Qt, and lets the user open Qt Assistant displaying the application's documentation. Here is the relevant parts of the MainWindow class definition:

     QAssistantClient *assistantClient;

To use Qt Assistant as an application's help tool, we must provide the application with a QAssistantClient object. An instance of the QAssistantClient class enables the application to open or close Qt Assistant whenever it is required. The object only interacts with the particular Qt Assistant instance associated with it (i.e. it is a one to one relationship between a QAssistantClient object and an instance of the Qt Assistant application).

Note that the QAssistantClient class is not included in the Qt library. To use it you must add CONFIG += assistant to your pro file.

     void initializeAssistant();

We declare the private initializeAssistant() function to create and initialize the application's QAssistantClient object. It is a convenience function used when constructing the main window widget.

     void assistant();

To facilitate the Open Assistant menu entry in the Help menu we declare a private assistant() slot which will open the application's instance of Qt Assistant on user requests.

     void closeEvent(QCloseEvent *event);

Finally, we must reimplement the protected QWidget::closeEvent() event handler to ensure that the application's Qt Assistant instance is properly closed before we terminate the application.

MainWindow Class Implementation

The MainWindow constructor is straight forward. We create the required actions and menus, and initialize the application's QAssistantClient object:

 MainWindow::MainWindow()
 {
     textViewer = new QTextEdit;
     textViewer->setReadOnly(true);
     QFile file("documentation/intro.html");
     if (file.open(QIODevice::ReadOnly))
         textViewer->setHtml(file.readAll());

     setCentralWidget(textViewer);

     createActions();
     createMenus();

     initializeAssistant();

     setWindowTitle(tr("Simple Text Viewer"));
     resize(750, 400);
 }

When the user select the Open Assistant entry in the main window's Help menu, it triggers the assistant() slot.

 void MainWindow::assistant()
 {
     assistantClient->showPage(QLibraryInfo::location(QLibraryInfo::ExamplesPath) +
                                               QDir::separator() +
                                               "assistant/simpletextviewer/documentation/index.html");
 }

In this slot we use the QAssistantClient::showPage() function to make Qt Assistant show the documentation's index page. This function also brings the Qt Assistant application to the foreground if it is hidden.

In our example, the application's documentation is located in a subdirectory in the Simple Text Viewer example's directory. We use QLibraryInfo::location() to determine the location of Qt's example path (QLibraryInfo::ExamplesPath), and add the proper suffix specifying the index file of the documentation.

The documentation set can be altered using the command line arguments that are passed to Qt Assistant when it is launched. When started without any options, Qt Assistant displays a default set of documentation. When Qt is installed, the default documentation set in Qt Assistant contains the Qt reference documentation as well as the tools that come with Qt, such as Qt Designer and qmake.

In our example, we replace the default documentation set with our custom documentation in the initializeAssistant() function called from the constructor:

 void MainWindow::initializeAssistant()
 {
     assistantClient = new QAssistantClient(QLibraryInfo::location(QLibraryInfo::BinariesPath), this);

     QStringList arguments;
     arguments << "-profile" << QString("documentation") + QDir::separator() + QString("simpletextviewer.adp");
     assistantClient->setArguments(arguments);
 }

First we create the QAssistantClient object, then we set the command line arguments that are applied when Qt Assistant is started, using the QAssistantClient::setArguments() function: The -profile documentation/simpletextviewer.adp arguments tell Qt Assistant to use the documentation set specified by the given .adp file. The .adp file extension is an abbreviation for Qt Assistant Document Profile.

Qt Assistant Document Profile

Qt Assistant Document Profile
The Qt Assistant Document Profile is an extension of the Documentation Content File. Documentation can be added or removed from Qt Assistant by adding and removing the content files. A documentation content file must contain the documentation's table of contents and all important keywords for the index. See the Qt Assistant Manual for a more detailed description of how to write and use documentation contents file for Qt Assistant. The Qt Assistant Document Profile adds a profile tag, containing property tags, to the format. Using a profile, the documentation writer can change several of Qt Assistant's properties, for example its window title and start page. /documentation/simpletextviewer.adp <!DOCTYPE DCF> <assistantconfig version="3.2.0"> <profile> <property name="name">simpletextviewer</property> <property name="title">Simple Text Viewer</property> <property name="applicationicon">images/handbook.png</property> <property name="startpage">index.html</property> <property name="aboutmenutext">About Simple Text Viewer</property> <property name="abouturl">about.txt</property> <property name="assistantdocs">.</property> </profile> <DCF ref="index.html" icon="images/handbook.png" title="Simple Text Viewer"> <section ref="./findfile.html" title="Find File"> <keyword ref="./index.html">Display</keyword> <keyword ref="./index.html">Rich text</keyword> <keyword ref="./index.html">Plain text</keyword> <keyword ref="./findfile.html">Find</keyword> <keyword ref="./findfile.html">File menu</keyword> <keyword ref="./filedialog.html">File name</keyword> <keyword ref="./filedialog.html">File dialog</keyword> <keyword ref="./wildcardmatching.html">File globbing</keyword> <keyword ref="./wildcardmatching.html">Wildcard matching</keyword> <keyword ref="./wildcardmatching.html">Wildcard syntax</keyword> <keyword ref="./browse.html">Browse</keyword> <keyword ref="./browse.html">Directory</keyword> <keyword ref="./openfile.html">Open</keyword> <keyword ref="./openfile.html">Select</keyword> <section ref="./filedialog.html" title="File Dialog" /> <section ref="./wildcardmatching.html" title="Wildcard Matching" /> <section ref="./browse.html" title="Browse" /> </section> <section ref="./openfile.html" title="Open File" /> </DCF> </assistantconfig> The `simpletextviewer.adp` file quoted above, describes the Simple Text Viewer application's documentation and consists of two sections: One enclosed by the `profile` tag, and another delimited by the `DCF` (Documentation Content File) tag. The latter section describes the documentation content, and defines the keywords that appear in the Index tab in Qt Assistant's sidebar. The `profile` section describes the properties of our application's instance of Qt Assistant. Within the profile tag you might, for example, want to set the `startpage` which is the page that Qt Assistant displays by default, the `assistantdocs` which describes the location of the documentation (relative to the location of the `.adp` file) used when the user requests help from the Search tab, and the `title` property used to specify a window title for Qt Assistant.

The Qt Assistant Document Profile is an extension of the Documentation Content File.

Documentation can be added or removed from Qt Assistant by adding and removing the content files. A documentation content file must contain the documentation's table of contents and all important keywords for the index. See the Qt Assistant Manual for a more detailed description of how to write and use documentation contents file for Qt Assistant.

The Qt Assistant Document Profile adds a profile tag, containing property tags, to the format. Using a profile, the documentation writer can change several of Qt Assistant's properties, for example its window title and start page.

/documentation/simpletextviewer.adp

 <!DOCTYPE DCF>

 <assistantconfig version="3.2.0">

 <profile>
     <property name="name">simpletextviewer</property>
     <property name="title">Simple Text Viewer</property>
     <property name="applicationicon">images/handbook.png</property>
     <property name="startpage">index.html</property>
     <property name="aboutmenutext">About Simple Text Viewer</property>
     <property name="abouturl">about.txt</property>
     <property name="assistantdocs">.</property>
 </profile>

 <DCF ref="index.html" icon="images/handbook.png" title="Simple Text Viewer">
         <section ref="./findfile.html" title="Find File">
             <keyword ref="./index.html">Display</keyword>
             <keyword ref="./index.html">Rich text</keyword>
             <keyword ref="./index.html">Plain text</keyword>
             <keyword ref="./findfile.html">Find</keyword>
             <keyword ref="./findfile.html">File menu</keyword>
             <keyword ref="./filedialog.html">File name</keyword>
             <keyword ref="./filedialog.html">File dialog</keyword>
             <keyword ref="./wildcardmatching.html">File globbing</keyword>
             <keyword ref="./wildcardmatching.html">Wildcard matching</keyword>
             <keyword ref="./wildcardmatching.html">Wildcard syntax</keyword>
             <keyword ref="./browse.html">Browse</keyword>
             <keyword ref="./browse.html">Directory</keyword>
             <keyword ref="./openfile.html">Open</keyword>
             <keyword ref="./openfile.html">Select</keyword>

             <section ref="./filedialog.html" title="File Dialog" />
             <section ref="./wildcardmatching.html" title="Wildcard Matching" />
             <section ref="./browse.html" title="Browse" />
         </section>
         <section ref="./openfile.html" title="Open File" />
 </DCF>

 </assistantconfig>

The simpletextviewer.adp file quoted above, describes the Simple Text Viewer application's documentation and consists of two sections: One enclosed by the profile tag, and another delimited by the DCF (Documentation Content File) tag. The latter section describes the documentation content, and defines the keywords that appear in the Index tab in Qt Assistant's sidebar. The profile section describes the properties of our application's instance of Qt Assistant. Within the profile tag you might, for example, want to set the startpage which is the page that Qt Assistant displays by default, the assistantdocs which describes the location of the documentation (relative to the location of the .adp file) used when the user requests help from the Search tab, and the title property used to specify a window title for Qt Assistant.

 void MainWindow::open()
 {
     FindFileDialog dialog(textViewer, assistantClient);
     dialog.exec();
 }

When the user choose the Open entry in the File menu, it triggers the open() slot which will pop up a find file dialog. We have two options of providing help during the dialog's execution: We can either create a new QAssistantClient object within the dialog, or pass the current object to its constructor. By choosing the latter solution, we delimit the number of running Qt Assistant instances to one.

Along with the QAssistantClient object, we also pass the current QTextEdit object to the FindFileDialog contructor to be able to display the selected file. Then we call the newly created dialog's exec() function, showing the dialog as a modal dialog (i.e. blocking until the user closes the dialog).

 void MainWindow::closeEvent(QCloseEvent *)
 {
     if (assistantClient)
         assistantClient->closeAssistant();
 }

When launching Qt Assistant using the QAssistantClient, the application is run in its own process. For that reason we must reimplement the QWidget::closeEvent() event handler to ensure that the Qt Assistant process is terminated properly before we close the application.

FindFileDialog Class Definition

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.

 class FindFileDialog : public QDialog
 {
     Q_OBJECT

 public:
     FindFileDialog(QTextEdit *editor, QAssistantClient *assistant,
                    QWidget *parent = 0);

 private slots:
     void browse();
     void help();
     void openFile(QTreeWidgetItem *item = 0);
     void update();

 private:
     void findFiles();
     void showFiles(const QStringList &files);

     void createButtons();
     void createComboBoxes();
     void createFilesTree();
     void createLabels();
     void createLayout();

     QAssistantClient *currentAssistantClient;
     QTextEdit *currentEditor;
     QTreeWidget *foundFilesTree;

     QComboBox *directoryComboBox;
     QComboBox *fileNameComboBox;

     QLabel *directoryLabel;
     QLabel *fileNameLabel;

     QDialogButtonBox *buttonBox;

     QToolButton *browseButton;
 };

The only relevant members to observe in the FindFileDialog class definition is the private help() slot. The slot is connected to the dialog's Help button, and brings the current Qt Assistant instance to the foreground showing the documentation for the dialog.

FindFileDialog Class Implementation

 FindFileDialog::FindFileDialog(QTextEdit *editor, QAssistantClient *assistant,
                                QWidget *parent)
     : QDialog(parent)
 {
     currentAssistantClient = assistant;
     currentEditor = editor;
     ...
 }

In the constructor we save the references to the QAssistantClient and QTextEdit objects passed as arguments. The QAssistantClient object will be used in the FindFileDialog's help() slot as we will see shortly, while the QTextEdit will be used in the dialog's openFile() slot to display the chosen file.

 void FindFileDialog::help()
 {
     currentAssistantClient->showPage(QLibraryInfo::location(QLibraryInfo::ExamplesPath) +
             QDir::separator() +  "assistant/simpletextviewer/documentation/filedialog.html");
 }

The help() slot is called when the user clicks the dialog's Help button. It brings the current Qt Assistant instance to the foreground and shows the application's manual page, using the QAssistantClient::showPage() function.

Summary

In order to make Qt Assistant act as a customized help tool for your application, you must provide your application with a QAssistantClient object in addition to a Qt Assistant Document Profile (.adp file) and documentation for the application.

Trademarks

Qt 4.2.3