Simple Text Viewer Example

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.

 <!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>

 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.