Материал из Wiki.crossplatform.ru

Внимание: Актуальная версия перевода документации находится здесь

__NOTOC__

[править] Simple Text Viewer Example

Files:

• assistant/simpletextviewer/findfiledialog.cpp
• assistant/simpletextviewer/findfiledialog.h
• assistant/simpletextviewer/mainwindow.cpp
• assistant/simpletextviewer/mainwindow.h
• assistant/simpletextviewer/main.cpp

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.

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