El marco Qt Help

Visión general

El sistema de ayuda Qt incluye herramientas para generar y visualizar archivos de ayuda Qt. Además, proporciona clases para acceder a los contenidos de ayuda mediante programación para poder integrar la ayuda en línea en las aplicaciones Qt.

Los datos de ayuda propiamente dichos, es decir, la tabla de contenidos, las palabras clave del índice o los documentos HTML, están contenidos en archivos de ayuda comprimidos en Qt. Así, un archivo de ayuda de este tipo representa normalmente un manual o conjunto de documentación. Dado que la mayoría de los productos son más completos y constan de varias herramientas, un manual rara vez es suficiente. En su lugar, existen más manuales, que deberían ser accesibles al mismo tiempo. Idealmente, también debería ser posible referenciar ciertos puntos de interés de un manual a otro. Por ello, el sistema de ayuda de Qt funciona con archivos de colección de ayuda, que incluyen cualquier número de archivos de ayuda comprimidos.

Sin embargo, disponer de ficheros de colección para fusionar muchos conjuntos de documentación puede acarrear algunos problemas. Por ejemplo, una palabra clave de índice puede estar definida en diferentes conjuntos de documentación. Por lo tanto, cuando sólo se ve una palabra clave en el índice y se activa, no se puede estar seguro de que se mostrará la documentación esperada. Por ello, el sistema de ayuda Qt ofrece la posibilidad de filtrar el contenido de la ayuda en función de ciertos atributos. Esto requiere, sin embargo, que los atributos hayan sido asignados a los contenidos de la ayuda antes de la generación del fichero de ayuda comprimido.

Como ya se ha mencionado, el archivo de ayuda comprimido de Qt contiene todos los datos, por lo que ya no es necesario enviar todos los archivos HTML individuales. En su lugar, sólo hay que distribuir el archivo de ayuda comprimido y, opcionalmente, el archivo de colección. El archivo de colección es opcional, ya que se puede utilizar cualquier archivo de colección existente, por ejemplo, de una versión anterior.

Así que, en general, hay cuatro archivos que interactúan con el sistema de ayuda, dos utilizados para generar la ayuda de Qt y dos destinados a la distribución:

Generación de Qt Help

La generación de archivos de ayuda para el sistema de ayuda Qt asume que los archivos de documentación HTML ya existen.

Una vez que los documentos HTML están en su lugar, un archivo de proyectoQt Help , con una extensión de .qhp, tiene que ser creado. Después de especificar toda la información relevante en este archivo, es necesario compilarlo llamando a:

qhelpgenerator doc.qhp -o doc.qch

El archivo doc.qch contiene todos los archivos HTML comprimidos junto con el índice y las palabras clave del índice. Para comprobar si el archivo generado es correcto, abra Qt Assistant e instale el archivo en Settings > Documentation.

Para la compilación estándar del código fuente de Qt, el archivo .qhp se genera y se coloca en el mismo directorio que las páginas HTML.

Creación de una colección Qt Help

El primer paso es crear un archivo de proyecto de colección Qt Help. Dado que una colección de ayuda Qt almacena principalmente referencias a archivos de ayuda comprimidos, el archivo de proyecto mycollection.qhcp tiene un aspecto sorprendentemente sencillo:

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

Para crear realmente la llamada de archivo de colección:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Para generar tanto la ayuda comprimida como el archivo de colección de una sola vez, modifique el archivo de proyecto de la colección de ayuda para que indique al generador de ayuda que cree primero la ayuda comprimida:

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

Por supuesto, es posible especificar más de un archivo en la sección generate o register, por lo que se puede generar y registrar cualquier número de archivos de ayuda comprimidos de una sola vez.

Uso de la API de QHelpEngine

QHelpEngine permite incrustar el contenido de la ayuda directamente en una aplicación.

En lugar de mostrar la ayuda en una aplicación externa, como un navegador web, también es posible incrustar la ayuda en línea en la aplicación. Los contenidos pueden recuperarse a través de la clase QHelpEngine y mostrarse en casi cualquier formato. Mostrar la ayuda en QTextBrowser es probablemente la forma más común, pero incrustarla en What's This help también es perfectamente posible.

Recuperar los datos de ayuda del motor de archivos no implica mucho código. El primer paso es crear una instancia del motor de ayuda. A continuación, pedimos al motor los enlaces asignados al identificador, en este caso MyDialog::ChangeButton. Si se encuentra un enlace, lo que significa que existe al menos un documento de ayuda sobre este tema, obtenemos el contenido real de la ayuda llamando a QHelpEngineCore::fileData() y mostramos el documento al usuario.

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

// get all file references for the identifier
QList<QHelpLink> links =
    helpEngine.documentsForIdentifier(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()->url);
    // show the documentation to the user
    if (!helpData.isEmpty())
        displayHelp(helpData);
}

Para más información sobre cómo utilizar la API, echa un vistazo a la referencia de la clase QHelpEngine.