En esta página

El marco de trabajo « Qt Help »

Descripción general

El sistema de Qt Help incluye herramientas para generar y visualizar archivos de Qt Help. Además, proporciona clases para acceder al contenido de la ayuda mediante programación, con el fin de poder integrar la ayuda en línea en las aplicaciones de Qt.

Los datos de ayuda propiamente dichos —es decir, la tabla de contenidos, las palabras clave del índice o los documentos HTML— se encuentran en archivos de ayuda comprimidos de Qt Help. Por lo tanto, uno de estos archivos de ayuda suele corresponder a un manual o conjunto de documentación. Dado que la mayoría de los productos son más completos y constan de varias herramientas, rara vez basta con un solo manual. En su lugar, existen varios manuales, a los que se debe poder acceder al mismo tiempo. Lo ideal sería que también fuera posible hacer referencia a determinados puntos de interés de un manual desde otro. Por ello, el sistema Qt Help opera con archivos de colección de ayuda, que incluyen cualquier número de archivos de ayuda comprimidos.

Sin embargo, disponer de archivos de colección para fusionar muchos conjuntos de documentación puede dar lugar a algunos problemas. Por ejemplo, una palabra clave del índice puede estar definida en diferentes conjuntos de documentación. Así pues, al ver únicamente una palabra clave en el índice y activarla, no se puede estar seguro de que se muestre la documentación esperada. Por ello, el sistema Qt Help ofrece la posibilidad de filtrar los contenidos de ayuda según determinados atributos. Sin embargo, esto requiere que los atributos se hayan asignado a los contenidos de ayuda antes de la generación del archivo 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 distribuir todos los archivos HTML individuales. En su lugar, solo hay que distribuir el archivo de ayuda comprimido y, opcionalmente, el archivo de recopilación. El archivo de recopilación es opcional, ya que se podría utilizar cualquier archivo de recopilación existente, por ejemplo, de una versión anterior.

Nota: Los archivos de ayuda comprimidos de Qt (.qch) solo deben cargarse desde fuentes de confianza.

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

NombreExtensiónBreve descripción
Qt Help Proyecto.qhpContiene el índice, los índices temáticos y las referencias a los archivos de documentación propiamente dichos (*.html). También define un espacio de nombres único para la documentación. Este archivo se pasa al generador de ayuda para crear un archivo de ayuda comprimido.
Ayuda comprimida de Qt Help.qchContiene toda la información especificada en el archivo de proyecto de ayuda, junto con todos los archivos de documentación comprimidos.
Qt Help Proyecto de colección.qhcpUn archivo XML que contiene referencias a los archivos de ayuda comprimidos que deben incluirse en la colección de ayuda. Este archivo puede pasarse al generador de ayuda para crear un archivo de colección de ayuda.
Qt Help Colección.qhcEl archivo de colección de ayuda sobre el que opera QHelpEngine. Puede contener referencias a cualquier número de archivos de ayuda comprimidos, así como información adicional.

Generación Qt Help

La creación de archivos de ayuda para el sistema de ayuda de Qt Help presupone que los archivos de documentación HTML ya existen.

Una vez que los documentos HTML estén en su sitio, hay que crear un archivo de proyecto «Qt Help », con la extensión .qhp. Tras especificar toda la información pertinente en este archivo, hay que compilarlo ejecutando:

qhelpgenerator doc.qhp -o doc.qch

El archivo doc.qch contiene todos los archivos HTML en formato comprimido, junto con la tabla de contenidos y las palabras clave del índice. Para comprobar si el archivo generado es correcto, abre Qt Assistant e instala el archivo en Settings > Documentation.

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

Creación de una colección de Qt Help

El primer paso consiste en crear un archivo de proyecto de colección « Qt Help ». Dado que una colección de ayuda de Qt Help almacena principalmente referencias a archivos de ayuda comprimidos, el archivo de proyecto mycollection.qhcp tiene un aspecto, como era de esperar, muy sencillo:

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

Para crear realmente el archivo de la colección, ejecuta:

qhelpgenerator mycollection.qhcp -o mycollection.qhc

Para generar tanto la ayuda comprimida como el archivo de recopilación de una sola vez, modifica el archivo de proyecto de recopilació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 integrar 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 integrar la ayuda en línea en la propia aplicación. El contenido se puede recuperar a través de la clase ` QHelpEngine ` y se puede mostrar prácticamente en cualquier formato. Mostrar la ayuda en una ventana de ayuda de tipo « QTextBrowser » es probablemente la forma más habitual, pero también es perfectamente posible integrarla en la ayuda «What's This».

Recuperar datos de ayuda del motor de archivos no requiere mucho código. El primer paso es crear una instancia del motor de ayuda. A continuación, solicitamos 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 obtener más información sobre cómo utilizar la API, consulta la referencia de la clase QHelpEngine.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.