Personalización Qt Assistant
Para utilizar Qt Assistant como visor de ayuda personalizado, no basta con poder mostrar documentación personalizada. Es igualmente importante que se pueda personalizar el aspecto de Qt Assistant para que se perciba como un visor de ayuda específico de la aplicación, en lugar de Qt Assistant. Esto se consigue cambiando el título o el icono de la ventana, así como algunos textos y acciones del menú específicos de la aplicación. Para obtener una lista completa de las posibles personalizaciones, consulte Creación de un archivo de colección de ayuda personalizado.
Otro requisito de un visor de ayuda personalizado es la capacidad de recibir acciones o comandos de la aplicación para la que proporciona ayuda. Esto es especialmente importante cuando la aplicación ofrece ayuda contextual. Cuando se utiliza de esta forma, es posible que el visor de ayuda tenga que modificar su contenido en función del estado en el que se encuentre la aplicación en ese momento. Esto significa que la aplicación tiene que comunicar el estado actual al visor de ayuda. Para obtener más información, consulte «Uso de Qt Assistant de forma remota».
El ejemplo «Simple Text Viewer» utiliza las técnicas descritas en este documento para mostrar cómo utilizar Qt Assistant como visor de ayuda personalizado para una aplicación.
Advertencia: Para poder incluir « Qt Assistant » en su aplicación, es imprescindible que incluya el complemento sqlite. Para obtener más información sobre cómo incluir complementos en su aplicación, consulte la documentación de implementación.
Qt Help Archivos de colección
Lo primero que hay que saber sobre Qt Assistant es que almacena toda la configuración relacionada con su apariencia y una lista de la documentación instalada en un archivo de colección de ayuda. Esto significa que, al iniciar Qt Assistant con diferentes archivos de colección, Qt Assistant puede tener un aspecto totalmente diferente. Esta separación completa de la configuración permite implementar Qt Assistant como un visor de ayuda personalizado para más de una aplicación en un mismo equipo sin riesgo de interferencias entre las diferentes instancias de Qt Assistant.
Para aplicar una determinada colección de ayuda a Qt Assistant, especifica el archivo de colección correspondiente en la línea de comandos al iniciarlo. Por ejemplo:
assistant -collectionFile mycollection.qhcSin embargo, almacenar toda la configuración en un único archivo de colección plantea algunos problemas. El archivo de colección suele instalarse en el mismo directorio que la propia aplicación, o en uno de sus subdirectorios. Dependiendo del directorio y del sistema operativo, es posible que el usuario no disponga de permisos para modificar este archivo, lo que ocurriría si se almacenaran los ajustes del usuario. Además, puede que ni siquiera sea posible conceder al usuario permisos de escritura, por ejemplo, cuando el archivo se encuentra en un soporte de solo lectura, como un CD-ROM.
Incluso si fuera posible conceder a todos el derecho a guardar su configuración en un archivo de configuración disponible para todos, la configuración de un usuario quedaría sobrescrita por la de otro al salir de Qt Assistant.
Para resolver este dilema, Qt Assistant crea archivos de recopilación específicos para cada usuario que, en mayor o menor medida, se copian del archivo de recopilación original. El archivo de recopilación específico del usuario se guardará en un subdirectorio de la ruta devuelta por QDesktopServices::AppDataLocation. El subdirectorio, o directorio de caché, dentro de esta ubicación específica del usuario, se puede definir en el archivo de proyecto de la colección de ayuda. Por ejemplo:
<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
<assistant>
<title>My Application Help</title>
<cacheDirectory>mycompany/myapplication</cacheDirectory>
...
</assistant>
</QHelpCollectionProject>Así pues, al llamar a
assistant -collectionFile mycollection.qhcQt Assistant utiliza realmente el archivo de recopilación:
%QDesktopServices::AppDataLocation%/mycompany/myapplication/mycollection.qhcNo es necesario en ningún caso iniciar Qt Assistant con el archivo de colección específico del usuario. En su lugar, siempre debe utilizarse el archivo de colección incluido con la aplicación. Asimismo, al añadir o eliminar documentación del archivo de colección (véase la siguiente sección), utilice siempre el archivo de colección normal. Qt Assistant se encargará de sincronizar los archivos de colección de los usuarios cuando cambie la lista de documentación instalada.
Visualización de documentación personalizada
Para que Qt Assistant pueda mostrar la documentación, debe saber dónde encontrar los archivos de documentación propiamente dichos, lo que significa que debe conocer la ubicación del archivo de ayuda comprimido de Qt (*.qch). Como ya se ha mencionado, Qt Assistant almacena referencias a los archivos de ayuda comprimidos en el archivo de colección que se está utilizando actualmente. Así pues, al crear un nuevo archivo de colección, puedes enumerar todos los archivos de ayuda comprimidos que Qt Assistant debe mostrar.
<?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>A veces, dependiendo de la aplicación para la que Qt Assistant actúe como visor de ayuda, es necesario añadir más documentación con el tiempo; por ejemplo, al instalar más componentes de la aplicación o complementos. Esto se puede hacer manualmente en Qt Assistant seleccionando Edición > Preferencias > Documentación. Sin embargo, este método tiene el inconveniente de que cada usuario tiene que hacerlo manualmente para poder acceder a la nueva documentación.
La forma recomendada de añadir documentación a un archivo de colección ya existente es utilizar el indicador de línea de comandos de -register de Qt Assistant. Al iniciar Qt Assistant con este indicador, se añadirá la documentación y Qt Assistant se cerrará inmediatamente mostrando un mensaje que indicará si el registro se ha realizado correctamente o no.
Nota: Los archivos de ayuda comprimidos de Qt (.qch) solo deben cargarse desde fuentes de confianza.
La indexación de búsqueda solo indexará tus archivos personalizados *.html, *.htm y *.txt.
assistant -collectionFile mycollection.qhc -register myapplication-manual.qchEl indicador « -quiet » se puede pasar a « Qt Assistant » para evitar que muestre el mensaje de estado.
Nota: « Qt Assistant » muestra la documentación en la vista «Contenido» en el mismo orden en que se registró.
Cambiar la apariencia de Qt Assistant
La apariencia de Qt Assistant se puede modificar pasando diferentes opciones de línea de comandos al iniciarlo. Sin embargo, estas opciones de línea de comandos solo permiten mostrar u ocultar elementos específicos, como la vista de contenido o el índice. Otras personalizaciones, como cambiar el título o el icono de la aplicación, o desactivar la función de filtro, se pueden realizar creando un archivo de colección de ayuda personalizado.
Creación de un archivo de colección de ayuda personalizado
El archivo de colección de ayuda (*.qhc) que utiliza Qt Assistant se crea al ejecutar la herramienta « qhelpgenerator » sobre un archivo de proyecto de colección de ayuda (*.qhcp). El formato del archivo de proyecto es XML y admite las siguientes etiquetas:
| Etiqueta | Breve descripción |
|---|---|
<title> | Especifica el título de la ventana de Qt Assistant. |
<homePage> | Especifica la página que se mostrará al seleccionar «Inicio» en la ventana principal de Qt Assistant. |
<startPage> | Especifica la página que se mostrará inicialmente al utilizar la colección de ayuda. |
<currentFilter> | Especifica el filtro que se utiliza inicialmente. Si no se especifica este filtro, la documentación no se filtrará. Esto no tiene ningún efecto si solo hay un conjunto de documentación instalado. |
<applicationIcon> | Describe un icono que se utilizará en lugar del icono normal de la aplicación « Qt Assistant ». Se especifica como una ruta relativa desde el directorio que contiene el archivo de la colección. |
<enableFilterFunctionality> | Activa o desactiva la funcionalidad de filtrado accesible para el usuario, lo que permite impedir que el usuario modifique ningún filtro al ejecutar Qt Assistant. Esto no significa que la funcionalidad de filtrado interna esté completamente desactivada. Establece el valor en false si deseas desactivar el filtrado. Si la barra de herramientas de filtrado debe mostrarse de forma predeterminada, establece el atributo visible en true. |
<enableDocumentationManager> | Muestra u oculta la pestaña «Documentación» en el cuadro de diálogo «Preferencias ». Desactivar la pestaña «Documentación» te permite limitar Qt Assistant para que muestre un conjunto específico de documentación o impedir que el usuario final elimine o instale documentación de forma accidental. Para ocultar la pestaña «Documentación», establece el valor de la etiqueta en false. |
<enableAddressBar> | Activa o desactiva la funcionalidad de la barra de direcciones. De forma predeterminada, está activada. Para desactivarla, establece el valor de la etiqueta en false. Si la funcionalidad de la barra de direcciones está activada, esta se puede mostrar estableciendo el atributo de la etiqueta visible en true. |
<aboutMenuText>, <text> | Enumera las versiones localizadas para la opción «Acerca de» del menú «Ayuda ». Por ejemplo, «Acerca de la aplicación». El texto se especifica entre las etiquetas text. El atributo language toma el nombre del idioma de dos letras. El texto se utiliza como texto predeterminado si no se especifica ningún atributo de idioma. |
<aboutDialog>, <file>, <icon> | Especifica el texto del cuadro de diálogo «Acerca de» que se puede abrir desde el menú «Ayuda ». El texto se extrae del archivo entre las etiquetas file. Es posible especificar un archivo diferente o cualquier idioma. El icono definido por las etiquetas icon se aplica a cualquier idioma. |
<cacheDirectory>, <cacheDirectory base="collection"> | Especifica el directorio de caché que se utiliza para almacenar los archivos de índice necesarios para la búsqueda de texto completo y una copia del archivo de colección. La copia es necesaria porque Qt Assistant almacena toda su configuración en el archivo de colección y, por lo tanto, debe ser escribible para el usuario. El directorio se especifica como una ruta relativa. Si el atributo base se establece en «collection», la ruta es relativa al directorio en el que reside el archivo de colección. Si el atributo se establece en «default» o si no se especifica, la ruta es relativa al directorio indicado por QDesktopServices::AppDataLocation. La primera forma resulta útil para colecciones que se utilizan de forma portátil, como las que se llevan en una memoria USB. |
<enableFullTextSearchFallback> | Activa o desactiva la posibilidad de recurrir a la búsqueda de texto completo si no se encuentra una palabra clave en el índice. Esta funcionalidad se puede utilizar durante el control remoto de Qt Assistant. Para que esté disponible para el control remoto, establece el valor de la etiqueta en true. |
Además de esas etiquetas específicas de Qt Assistant, se pueden utilizar las etiquetas para generar y registrar documentación. Consulte la documentación de los archivos de colección deQt Help para obtener más información.
A continuación se muestra un ejemplo de un archivo de colección de ayuda que utiliza todas las etiquetas disponibles:
<?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>Para crear el archivo de colección binario, ejecute la herramienta qhelpgenerator:
qhelpgenerator mycollection.qhcp -o mycollection.qhcPara probar el archivo de recopilación generado, inicie Qt Assistant de la siguiente manera:
assistant -collectionFile mycollection.qhcUso remoto de « Qt Assistant »
Aunque el visor de ayuda es una aplicación independiente, normalmente la iniciará la propia aplicación para la que proporciona ayuda. Este enfoque permite a la aplicación solicitar que se muestren contenidos de ayuda específicos tan pronto como se inicie el visor de ayuda. Otra ventaja de este enfoque es que la aplicación puede comunicarse con el proceso del visor de ayuda y, por lo tanto, solicitar que se muestren otros contenidos de ayuda en función del estado actual de la aplicación.
Así pues, para utilizar Qt Assistant como visor de ayuda personalizado de tu aplicación, basta con crear un QProcess y especificar la ruta al ejecutable Qt Assistant. Para que Qt Assistant «escuche» a tu aplicación, activa su funcionalidad de control remoto pasando la opción de línea de comandos -enableRemoteControl.
El siguiente ejemplo muestra cómo se puede hacer esto:
QProcess *process = new QProcess;
QStringList args;
args << QLatin1String("-collectionFile")
<< QLatin1String("mycollection.qhc")
<< QLatin1String("-enableRemoteControl");
process->start(QLatin1String("assistant"), args);
if (!process->waitForStarted())
return;Una vez que Qt Assistant esté en ejecución, puedes enviar comandos utilizando el canal stdin del proceso. El fragmento de código que aparece a continuación muestra cómo indicar a Qt Assistant que muestre una página concreta de la documentación.
QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);Nota: El carácter de nueva línea al final es necesario para marcar el final de la entrada.
Se pueden utilizar los siguientes comandos para controlar Qt Assistant:
| Comando | Breve descripción |
|---|---|
show <Widget> | Muestra la ventana de la barra lateral (widget acoplado) especificada por <Widget>. Si el widget ya está visible y se envía este comando de nuevo, el widget se activará, lo que significa que se mostrará en primer plano y recibirá el foco de entrada. Los valores posibles para <Widget> son «contents», «index», «bookmarks» o «search». |
hide <Widget> | Oculta el widget de dock especificado por <Widget>. Los valores posibles para <Widget> son «contents», «index», «bookmarks» y «search». |
setSource <Url> | Muestra la <URL> indicada. La URL puede ser absoluta o relativa a la página que se muestra actualmente. Si la URL es absoluta, debe ser una URL válida del sistema Qt Help. Es decir, debe comenzar por «qthelp://». |
activateKeyword <Keyword> | Inserta la <palabra clave> especificada en el campo de edición de línea del widget del dock de índice y activa el elemento correspondiente en la lista de índice. Si dicho elemento tiene más de un enlace asociado, se mostrará un selector de temas. |
activateIdentifier <Id> | Muestra el contenido de ayuda correspondiente al <Id> indicado. Un ID es único en cada espacio de nombres y solo tiene un enlace asociado, por lo que el selector de temas nunca aparecerá. |
syncContents | Selecciona el elemento del widget de contenido que corresponde a la página que se muestra actualmente. |
setCurrentFilter <filter> | Selecciona el filtro especificado y actualiza la representación visual en consecuencia. |
expandToc <Depth> | Expande el árbol de la tabla de contenidos hasta la profundidad indicada. Si la profundidad es 0, el árbol se contraerá por completo. Si la profundidad es -1, el árbol se expandirá por completo. |
register <help file> | Añade el archivo de ayuda comprimido de Qt especificado a la colección. |
unregister <help file> | Elimina el archivo de ayuda comprimido de Qt especificado de la colección. |
Si deseas enviar varios comandos en un breve periodo de tiempo, se recomienda escribir una sola línea en la entrada estándar (stdin) del proceso, en lugar de una línea por cada comando. Los comandos deben separarse con un punto y coma, tal y como se muestra en el siguiente ejemplo:
QByteArray ba;
ba.append("hide bookmarks;");
ba.append("hide index;");
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);© 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.