Simple Text Viewer Example

Organizing Documentation for Qt Assistant

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 Qt Assistant, 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 Qt Assistant. 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.

 <?xml version="1.0" encoding="UTF-8"?>
 <QtHelpProject version="1.0">
   <namespace>com.trolltech.examples.simpletextviewer</namespace>
   <virtualFolder>doc</virtualFolder>

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 Qt Assistant, 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 Qt Assistant will hide the documentation.

Again, since we'll only have one documentation set, we do not need the filtering functionality of Qt Assistant and can therefore skip the filter attributes.

Now, we build up the table of contents. An item in the table is defined by the 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:

• Simple Text Viewer
  • Find File
    • File Dialog
    • Wildcard Matching
    • Browse
  • Open File

In the help project file, the outline is represented by:

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

After the table of contents is defined, we will list all index keywords:

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

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.

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

The help project file is now finished. If you want to see the resulting documentation in Qt Assistant, you have to generate a Qt compressed help file out of it and register it with the default help collection of Qt Assistant.

 qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
 assistant -register simpletextviewer.qch

If you start Qt Assistant 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 Qt Assistant.

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

     <startPage>qthelp://com.trolltech.examples.simpletextviewer/doc/index.html</startPage>

     <aboutMenuText>
         <text>About Simple Text Viewer</text>
     </aboutMenuText>
     <aboutDialog>
         <file>about.txt</file>
         <icon>images/icon.png</icon>
     </aboutDialog>

     <enableDocumentationManager>false</enableDocumentationManager>
     <enableAddressBar>false</enableAddressBar>
     <enableFilterFunctionality>false</enableFilterFunctionality>
 </assistant>

   <docFiles>
     <generate>
         <file>
             <input>simpletextviewer.qhp</input>
             <output>simpletextviewer.qch</output>
             </file>
         </generate>
     <register>
         <file>simpletextviewer.qch</file>
         </register>
     </docFiles>
 </QHelpCollectionProject>

 qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc

 assistant -collectionFile simpletextviewer.qhc

 bool Assistant::startAssistant()
 {
     if (!proc)
         proc = new QProcess();

     if (proc->state() != QProcess::Running) {
         QString app = QLibraryInfo::location(QLibraryInfo::BinariesPath) + QDir::separator();
 #if !defined(Q_OS_MAC)
         app += QLatin1String("assistant");
 #else
         app += QLatin1String("Assistant.app/Contents/MacOS/Assistant");
 #endif

         QStringList args;
         args << QLatin1String("-collectionFile")
             << QLibraryInfo::location(QLibraryInfo::ExamplesPath)
             + QLatin1String("/help/simpletextviewer/documentation/simpletextviewer.qhc")
             << QLatin1String("-enableRemoteControl");

         proc->start(app, args);

         if (!proc->waitForStarted()) {
             QMessageBox::critical(0, QObject::tr("Simple Text Viewer"),
                 QObject::tr("Unable to launch Qt Assistant (%1)").arg(app));
             return false;
         }
     }
     return true;
 }

 void Assistant::showDocumentation(const QString &page)
 {
     if (!startAssistant())
         return;

     QByteArray ba("SetSource ");
     ba.append("qthelp://com.trolltech.examples.simpletextviewer/doc/");

     proc->write(ba + page.toLocal8Bit() + '\n');
 }

 Assistant::~Assistant()
 {
     if (proc && proc->state() == QProcess::Running) {
         proc->terminate();
         proc->waitForFinished(3000);
     }
     delete proc;
 }

 MainWindow::MainWindow()
 {
     assistant = new Assistant;
     ...
 }

 void MainWindow::createActions()
 {
     assistantAct = new QAction(tr("Help Contents"), this);
     assistantAct->setShortcut(QKeySequence::HelpContents);
     connect(assistantAct, SIGNAL(triggered()), this, SLOT(showDocumentation()));
     ...
 }

 void MainWindow::showDocumentation()
 {
     assistant->showDocumentation("index.html");
 }

 void MainWindow::closeEvent(QCloseEvent *)
 {
     delete assistant;
 }

 FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant)
     : QDialog(editor)
 {
     currentAssistant = assistant;
     currentEditor = editor;
     ...
 }

 void FindFileDialog::help()
 {
     currentAssistant->showDocumentation("filedialog.html");
 }