The Qt Help Framework
|
Name | Extension | Brief Description |
---|---|---|
Qt Help Project | .qhp | The input file for the help generator consisting of the table of contents, indices and references to the actual documentation files (*.html); it also defines a unique namespace for the documentation. |
Qt Compressed Help | .qch | The output file of the help generator. This binary file contains all information specified in the help project file along with all compressed documentation files. |
Qt Help Collection Project | .qhcp | The input file for the help collection generator. It contains references to compressed help files which should be included in the collection; it also may contain other information for customizing Qt Assistant. |
Qt Help Collection | .qhc | The output of the help collection generator. This is the file QHelpEngine operates on. It contains references to any number of compressed help files as well as additional information, such as custom filters. |
Building help files for the Qt help system assumes that the html documentation files already exist, i.e. the Qt help system does not offer the possibility to create html files like e.g. Doxygen.
Once the html documentents are in place, a Qt Help Project file has to be created. After specifying all relevant information in this file, it needs to be compiled by calling:
qhelpgenerator doc.qhp -o doc.qch
The file 'doc.qch' contains then all html files in compressed form along with the table of contents and index keywords. To test if the generated file is correct, open Qt Assistant and install the file via the Settings|Documentation page.
The first step is to create a Qt Help Collection Project file. Since a Qt help collection stores primarily references to compressed help files, the project 'mycollection.qhcp' file looks unsurprisingly simple:
<?xml version="1.0" encoding="utf-8" ?> <QHelpCollectionProject version="1.0"> <docFiles> <register> <file>doc.qch</file> </register> </docFiles> </QHelpCollectionProject>
For actually creating the collection file call:
qcollectiongenerator mycollection.qhcp -o mycollection.qhc
Instead of running two tools, one for generating the compressed help and one for generating the collection file, it is also possible to just run the qcollectiongenerator tool with a slightly modified project file instructing the generator to create the compressed help first.
... <docFiles> <generate> <file> <input>doc.qhp</input> <output>doc.qch</output> </file> </generate> <register> <file>doc.qch</file> </register> </docFiles> ...
Of course, it is possible to specify more than one file in the 'generate' or 'register' section, so any number of compressed help files can be generated and registered in one go.
Accessing the help contents can be done in two ways: Using Qt Assistant as documentation browser or using the QHelpEngine API for embedding the help contents directly in an application.
Qt Assistant operates on a collection file which can be specified before start up. If no collection file is given, a default one will be created and used. In either case, it is possible to register any Qt compressed help file and access the help contents.
When using Assistant as the help browser for an application, it would be desirable that it can be customized to fit better to the application and doesn't look like an independent, standalone help browser. To achieve this, several additional properties can be set in an Qt help collection file, to change e.g. the title or application icon of Qt Assistant. For more information on this topic have a look at the Qt Assistant manual.
Instead of showing the help in an external application like the Qt Assistant, it is also possible to embed the online help in the application. The contents can then be retrieved via the QHelpEngine class and can be displayed in nearly any form. Showing it in a QTextBrowser is probably the most common way, but embedding it in What's This help is also perfectly possible.
Retrieving help data from the file engine does not involve a lot of code. The first step is to create an instance of the help engine. Then we ask the engine for the links assigned to the identifier, in this case "MyDialog::ChangeButton". If a link was found, meaning at least one help document exists to this topic, we get the actual help contents by calling fileData() and display the document to the user.
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); }
For further information on how to use the API, have a look at the QHelpEngine class reference.
Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia. | Qt 4.6-snapshot | |
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD. | ||
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP ! |
Copyright © 2000-2012 - www.developpez.com