The Qt Help Framework

Overview

The Qt help system includes tools for generating and viewing Qt help files. In addition it provides classes for accessing help contents programatically to be able to integrate online help into Qt applications.

The actual help data, meaning the table of contents, index keywords or html documents, is contained in Qt compressed help files. So, one such a help file represents usually one manual or documentation set. Since most products are more comprehensive and consist of a number of tools, one manual is rarely enough. Instead, more manuals which should be accessible at the same time, exist. Ideally, it should also be possible to reference certain points of interest of one manual to another. Therefore, the Qt help system operates on help collection files which include any number of compressed help files.

However, having collection files to merge many documentation sets may lead to some problems. For example, one index keyword may be defined in different documentations. So, when only seeing it in the index and activating it, you cannot be sure that the expected documentation will be shown. Therefore, the Qt help system offers the possibiltiy to filter the help contents after certain attributes. This requires however, that the attributes have been assigned to the help contents before the generation of the compressed help file.

As already mentioned, the Qt compressed help file contains all data, so there is no need any longer to ship all single html files. Instead, only the compressed help file and optionally the collection file has to be distributed. The collection file is optional since any existing collection file, e.g. from an older release could be used.

So, in general, there are four files interacting with the help system, two used for generating Qt help and two meant for distribution:

 qhelpgenerator doc.qhp -o doc.qch

 <?xml version="1.0" encoding="utf-8" ?>
 <QHelpCollectionProject version="1.0">
     <docFiles>
         <register>
             <file>doc.qch</file>
         </register>
     </docFiles>
 </QHelpCollectionProject>

 qcollectiongenerator mycollection.qhcp -o mycollection.qhc

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

 QHelpEngineCore helpEngine("mycollection.qhc");
 ...

 // get all file references for the identifier
 QMap<QString, QUrl> links =
     helpEngine.linksForIdentifier(QLatin1String("MyDialog::ChangeButton"));

 // If help is available for this keyword, get the help data
 // of the first file reference.
 if (links.count()) {
     QByteArray helpData = helpEngine->fileData(links.constBegin().value());
     // show the documentation to the user
     if (!helpData.isEmpty())
         displayHelp(helpData);
 }