Редактирование: Qt:Документация 4.3.2/assistant-simpletextviewer

{{Qt4.3.2_header}}

=Simple Text Viewer Example<br />=
Files:

*[[Qt:Документация 4.3.2/assistant-simpletextviewer-findfiledialog-cpp | assistant/simpletextviewer/findfiledialog.cpp]]
*[[Qt:Документация 4.3.2/assistant-simpletextviewer-findfiledialog-h | assistant/simpletextviewer/findfiledialog.h]]
*[[Qt:Документация 4.3.2/assistant-simpletextviewer-mainwindow-cpp | assistant/simpletextviewer/mainwindow.cpp]]
*[[Qt:Документация 4.3.2/assistant-simpletextviewer-mainwindow-h | assistant/simpletextviewer/mainwindow.h]]
*[[Qt:Документация 4.3.2/assistant-simpletextviewer-main-cpp | 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 [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] class combined with a [[Qt:Документация 4.3.2/assistant-manual#profiles | Qt Assistant Document Profile]].

[[Image:simpletextviewer-example.png|center]]

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 <tt>documentation</tt> subdirectory.

The example consists of two classes:

*<tt>MainWindow</tt> is the main application window.
*<tt>FindFileDialog</tt> allows the user to search for files using wildcard matching.

First we will take a look at how the [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] is implemented in the <tt>MainWindow</tt> class. At the same time we will see how we can make the Qt Assistant display custom documentation using the Qt Assistant Document Profile (<tt>.adp</tt>) format. Then we will review the <tt>FindFileDialog</tt> 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.
<div id="mainwindow-class-definition"></div>
==MainWindow Class Definition==
[[Image:simpletextviewer-mainwindow.png|center]]

The <tt>MainWindow</tt> 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 <tt>MainWindow</tt> class definition:
<source lang="cpp-qt">     QAssistantClient *assistantClient;</source> 
To use Qt Assistant as an application's help tool, we must provide the application with a [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object. An instance of the [[Qt:Документация 4.3.2/qassistantclient | 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&#x2e; it is a one to one relationship between a [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object and an instance of the Qt Assistant application).

Note that the [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] class is not included in the Qt library. To use it you must add <tt>CONFIG += assistant</tt> to your pro file.
<source lang="cpp-qt">     void initializeAssistant();</source> 
We declare the private <tt>initializeAssistant()</tt> function to create and initialize the application's [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object. It is a convenience function used when constructing the main window widget.
<source lang="cpp-qt">     void assistant();</source> 
To facilitate the '''Open Assistant''' menu entry in the '''Help''' menu we declare a private <tt>assistant()</tt> slot which will open the application's instance of Qt Assistant on user requests.
<source lang="cpp-qt">     void closeEvent(QCloseEvent *event);</source> 
Finally, we must reimplement the protected [[Qt:Документация 4.3.2/qwidget#closeEvent | QWidget::closeEvent]]() event handler to ensure that the application's Qt Assistant instance is properly closed before we terminate the application.
<div id="mainwindow-class-implementation"></div>
==MainWindow Class Implementation==
The <tt>MainWindow</tt> constructor is straight forward. We create the required actions and menus, and initialize the application's [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object:
<source lang="cpp-qt"> 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);
 }</source> 
When the user select the '''Open Assistant''' entry in the main window's '''Help''' menu, it triggers the <tt>assistant()</tt> slot.
<source lang="cpp-qt"> void MainWindow::assistant()
 {
     assistantClient->showPage(QLibraryInfo::location(QLibraryInfo::ExamplesPath) +
                                               QDir::separator() +
                                               "assistant/simpletextviewer/documentation/index.html");
 }</source> 
In this slot we use the [[Qt:Документация 4.3.2/qassistantclient#showPage | 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 [[Qt:Документация 4.3.2/qlibraryinfo#location | QLibraryInfo::location]]() to determine the location of Qt's example path ([[Qt:Документация 4.3.2/qlibraryinfo#LibraryLocation-enum | 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 <tt>qmake</tt>.

In our example, we replace the default documentation set with our custom documentation in the <tt>initializeAssistant()</tt> function called from the constructor:
<source lang="cpp-qt"> 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);
 }</source> 
First we create the [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object, then we set the command line arguments that are applied when Qt Assistant is started, using the [[Qt:Документация 4.3.2/qassistantclient#setArguments | QAssistantClient::setArguments]]() function: The <tt>-profile documentation/simpletextviewer.adp</tt> arguments tell Qt Assistant to use the documentation set specified by the given <tt>.adp</tt> file. The <tt>.adp</tt> file extension is an abbreviation for [[Qt:Документация 4.3.2/assistant-manual#profiles | Qt Assistant Document Profile]].


{|  align="center" cellpadding="2" cellspacing="1" border="0"
|- valign="top" class="qt-style" | 
!Qt Assistant Document Profile
|- valign="top" class="odd" | 
|The [[Qt:Документация 4.3.2/assistant-manual#profiles | Qt Assistant Document Profile]] is an extension of the [[Qt:Документация 4.3.2/assistant-manual#documentation-content-file-format | 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:Документация 4.3.2/assistant-manual | Qt Assistant Manual]] for a more detailed description of how to write and use documentation contents file for Qt Assistant.

The [[Qt:Документация 4.3.2/assistant-manual#profiles | 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.

====<center>/documentation/simpletextviewer.adp</center>====<source lang="cpp-qt"> <!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></source> 
The <tt>simpletextviewer.adp</tt> file quoted above, describes the Simple Text Viewer application's documentation and consists of two sections: One enclosed by the <tt>profile</tt> tag, and another delimited by the <tt>DCF</tt> (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 <tt>profile</tt> section describes the properties of our application's instance of Qt Assistant. Within the profile tag you might, for example, want to set the <tt>startpage</tt> which is the page that Qt Assistant displays by default, the <tt>assistantdocs</tt> which describes the location of the documentation (relative to the location of the <tt>.adp</tt> file) used when the user requests help from the '''Search''' tab, and the <tt>title</tt> property used to specify a window title for Qt Assistant.

|}
<source lang="cpp-qt"> void MainWindow::open()
 {
     FindFileDialog dialog(textViewer, assistantClient);
     dialog.exec();
 }</source> 
When the user choose the '''Open''' entry in the '''File''' menu, it triggers the <tt>open()</tt> 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 [[Qt:Документация 4.3.2/qassistantclient | 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 [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object, we also pass the current [[Qt:Документация 4.3.2/qtextedit | QTextEdit]] object to the <tt>FindFileDialog</tt> contructor to be able to display the selected file. Then we call the newly created dialog's [[Qt:Документация 4.3.2/qdialog#exec | exec()]] function, showing the dialog as a [[Qt:Документация 4.3.2/qdialog#modal-dialogs | modal dialog]] (i.e&#x2e; blocking until the user closes the dialog).
<source lang="cpp-qt"> void MainWindow::closeEvent(QCloseEvent *)
 {
     if (assistantClient)
         assistantClient->closeAssistant();
 }</source> 
When launching Qt Assistant using the [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]], the application is run in its own process. For that reason we must reimplement the [[Qt:Документация 4.3.2/qwidget#closeEvent | QWidget::closeEvent]]() event handler to ensure that the Qt Assistant process is terminated properly before we close the application.
<div id="findfiledialog-class-definition"></div>
==FindFileDialog Class Definition==
[[Image:simpletextviewer-findfiledialog.png|center]]

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.
<source lang="cpp-qt"> 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 &amp;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;
 };</source> 
The only relevant members to observe in the <tt>FindFileDialog</tt> class definition is the private <tt>help()</tt> 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.
<div id="findfiledialog-class-implementation"></div>
==FindFileDialog Class Implementation==<source lang="cpp-qt"> FindFileDialog::FindFileDialog(QTextEdit *editor, QAssistantClient *assistant,
                                QWidget *parent)
     : QDialog(parent)
 {
     currentAssistantClient = assistant;
     currentEditor = editor;
     ...
 }</source> 
In the constructor we save the references to the [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] and [[Qt:Документация 4.3.2/qtextedit | QTextEdit]] objects passed as arguments. The [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object will be used in the <tt>FindFileDialog</tt>'s <tt>help()</tt> slot as we will see shortly, while the [[Qt:Документация 4.3.2/qtextedit | QTextEdit]] will be used in the dialog's <tt>openFile()</tt> slot to display the chosen file.
<source lang="cpp-qt"> void FindFileDialog::help()
 {
     currentAssistantClient->showPage(QLibraryInfo::location(QLibraryInfo::ExamplesPath) +
             QDir::separator() +  "assistant/simpletextviewer/documentation/filedialog.html");
 }</source> 
The <tt>help()</tt> 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 [[Qt:Документация 4.3.2/qassistantclient#showPage | QAssistantClient::showPage]]() function.
<div id="summary"></div>
==Summary==
In order to make Qt Assistant act as a customized help tool for your application, you must provide your application with a [[Qt:Документация 4.3.2/qassistantclient | QAssistantClient]] object in addition to a [[Qt:Документация 4.3.2/assistant-manual#profiles | Qt Assistant Document Profile]] (<tt>.adp</tt> file) and documentation for the application.

{{Qt4.3.2_footer}}