Using Qt Assistant as a Custom Help Viewer

Qt Help Collection Files

The first important point to know about Qt Assistant is that it stores all settings related to its appearance and a list of installed documentation in a help collection file. This means, when starting Qt Assistant with different collection files, Qt Assistant may look totally different. This complete separation of settings makes it possible to deploy Qt Assistant as a custom help viewer for more than one application on one machine without risk of interference between different instances of Qt Assistant.

To apply a certain help collection to Qt Assistant, specify the respective collection file on the command line when starting it. For example:

 assistant -collectionFile mycollection.qhc

However, storing all settings in one collection file raises some problems. The collection file is usually installed in the same directory as the application itself, or one of its subdirectories. Depending on the directory and the operating system, the user may not have any permissions to modify this file which would happen when the user settings are stored. Also, it may not even be possible to give the user write permissions; e.g., when the file is located on a read-only medium like a CD-ROM.

Even if it is possible to give everybody the right to store their settings in a globally available collection file, the settings from one user would be overwritten by another user when exiting Qt Assistant.

To solve this dilemma, Qt Assistant creates user specific collection files which are more or less copied from the original collection file. The user-specific collection file will be saved in a subdirectory of the path returned by QDesktopServices::DataLocation. The subdirectory, or cache directory within this user-specific location, can be defined in the help collection project file. For example:

 <?xml version="1.0" encoding="utf-8" ?>
 <QHelpCollectionProject version="1.0">
     <assistant>
         <title>My Application Help</title>
         <cacheDirectory>mycompany/myapplication</cacheDirectory>
         ...
     </assistant>
 </QHelpCollectionProject>

So, when calling

 assistant -collectionFile mycollection.qhc

Qt Assistant actually uses the collection file:

 %QDesktopServices::DataLocation%/mycompany/myapplication/mycollection.qhc

There is no need ever to start Qt Assistant with the user specific collection file. Instead, the collection file shipped with the application should always be used. Also, when adding or removing documentation from the collection file (see next section) always use the normal collection file. Qt Assistant will take care of synchronizing the user collection files when the list of installed documentation has changed.

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

 assistant -collectionFile mycollection.qhc -register myapplication-manual.qch

 <?xml version="1.0" encoding="utf-8" ?>
 <QHelpCollectionProject version="1.0">
     <assistant>
         <title>My Application Help</title>
         <startPage>qthelp://com.mycompany.1_0_0/doc/index.html</startPage>
         <currentFilter>myfilter</currentFilter>
         <applicationIcon>application.png</applicationIcon>
         <enableFilterFunctionality>false</enableFilterFunctionality>
         <enableDocumentationManager>false</enableDocumentationManager>
         <enableAddressBar visible="true">true</enableAddressBar>
         <cacheDirectory>mycompany/myapplication</cacheDirectory>
         <aboutMenuText>
             <text>About My Application</text>
             <text language="de">Über meine Applikation...</text>
         </aboutMenuText>
         <aboutDialog>
             <file>about.txt</file>
             <file language="de">ueber.txt</file>
             <icon>about.png</icon>
         </aboutDialog>
     </assistant>
     <docFiles>
         <generate>
             <file>
                 <input>myapplication-manual.qhp</input>
                 <output>myapplication-manual.qch</output>
             </file>
         </generate>
         <register>
             <file>myapplication-manual.qch</file>
         </register>
     </docFiles>
 </QHelpCollectionProject>

 qcollectiongenerator mycollection.qhcp -o mycollection.qhc

 assistant -collectionFile mycollection.qhc

 QProcess *process = new QProcess;
 QStringList args;
 args << QLatin1String("-collectionFile")
     << QLatin1String("mycollection.qhc")
     << QLatin1String("-enableRemoteControl");
 process->start(QLatin1String("assistant"), args);
 if (!process->waitForStarted())
     return;

 QTextStream str(process);
 str << QLatin1String("setSource qthelp://com.mycompany.1_0_0/doc/index.html\0") << endl;

 QTextStream str(process);
 str << QLatin1String("hide bookmarks;")
     << QLatin1String("hide index;")
     << QLatin1String("setSource qthelp://com.mycompany.1_0_0/doc/index.html\0")
     << endl;