Personalización de Qt Assistant

Utilizar Qt Assistant como visor de ayuda personalizado requiere algo más que poder mostrar documentación personalizada. Es igualmente importante que la apariencia de Qt Assistant pueda personalizarse para que se vea 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 personalizada.

Otro requisito de un visor de ayuda personalizado es la capacidad de recibir acciones o comandos de la aplicación a la que proporciona ayuda. Esto es especialmente importante cuando la aplicación ofrece ayuda sensible al contexto. Cuando se utiliza de esta manera, el visor de ayuda puede necesitar cambiar su contenido dependiendo 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 Visor de texto simple utiliza las técnicas descritas en este documento para mostrar cómo utilizar Qt Assistant como visor de ayuda personalizado para una aplicación.

Qt Help Archivos de colección

El primer punto importante que hay que saber sobre Qt Assistant es que almacena todos los ajustes relacionados 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 completa separación de configuraciones hace posible desplegar Qt Assistant como un visor de ayuda personalizado para más de una aplicación en una máquina sin riesgo de interferencia entre diferentes instancias de Qt Assistant.

Para aplicar una determinada colección de ayuda a Qt Assistant, especifique el archivo de colección correspondiente en la línea de comandos al iniciarlo. Por ejemplo:

assistant -collectionFile mycollection.qhc

Sin embargo, almacenar todas las configuraciones en un 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 tenga permisos para modificar este fichero, lo que ocurriría cuando se almacenan los ajustes de usuario. Además, puede que ni siquiera sea posible dar al usuario permisos de escritura, por ejemplo cuando el archivo se encuentra en un soporte de sólo lectura como un CD-ROM.

Incluso si es posible dar a todo el mundo el derecho a almacenar sus configuraciones en un archivo de colección disponible globalmente, las configuraciones de un usuario serían sobrescritas por otro al salir de Qt Assistant.

Para resolver este dilema, Qt Assistant crea archivos de recopilación específicos para cada usuario que se copian más o menos del archivo de recopilación original. El archivo de colección específico del usuario se guardará en un subdirectorio de la ruta devuelta por QDesktopServices::AppDataLocation. El subdirectorio, o directorio caché dentro de esta ubicación específica del usuario, puede definirse 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í, al llamar a

assistant -collectionFile mycollection.qhc

Qt Assistant utiliza realmente el archivo de la colección:

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

No es necesario iniciar nunca Qt Assistant con el archivo de recopilación específico del usuario. En su lugar, siempre se debe utilizar el archivo de colección incluido con la aplicación. Además, cuando se añada o elimine 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 del usuario cuando la lista de documentación instalada haya cambiado.

Visualización de documentación personalizada

Antes de que Qt Assistant sea capaz de mostrar documentación, tiene que saber donde puede encontrar los archivos de documentación reales, lo que significa que tiene que saber la localización del archivo de ayuda comprimido Qt (*.qch). Como ya se ha mencionado, Qt Assistant almacena referencias a los archivos de ayuda comprimidos en el archivo de colección utilizado actualmente. Así, al crear un nuevo archivo de colección puede listar 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úa como visor de ayuda, es necesario añadir más documentación con el tiempo; por ejemplo, al instalar más componentes o plugins de la aplicación. Esto puede hacerse manualmente en Qt Assistant seleccionando Edición > Preferencias > Documentación. Sin embargo, este enfoque tiene la desventaja de que cada usuario tiene que hacerlo manualmente para tener acceso a la nueva documentación.

La forma preferida de añadir documentación a un archivo de colección ya existente es utilizar el indicador de línea de comandos -register de Qt Assistant. Al iniciar Qt Assistant con este indicador, se añadirá la documentación y Qt Assistant saldrá inmediatamente mostrando un mensaje si el registro se ha realizado correctamente o no.

La indexación de búsqueda sólo indexará sus archivos *.html, *.htm y *.txt personalizados.

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

La bandera -quiet puede pasarse a Qt Assistant para evitar que escriba el mensaje de estado.

Cambiar la apariencia de Qt Assistant

La apariencia de Qt Assistant puede cambiarse pasando diferentes opciones de línea de comandos al inicio. Sin embargo, estas opciones de línea de comandos sólo permiten mostrar u ocultar widgets específicos, como la vista de contenidos o de índice. Otras personalizaciones, como cambiar el título o el icono de la aplicación, o desactivar la función de filtro, pueden realizarse 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) utilizado por Qt Assistant se crea al ejecutar la herramienta qhelpgenerator en un archivo de proyecto de colección de ayuda (*.qhcp). El formato del archivo de proyecto es XML y admite las siguientes etiquetas:

Además de estas etiquetas específicas de Qt Assistant, se pueden utilizar las etiquetas para generar y registrar documentación. Consulte la documentación de Qt Help Archivos de colección para obtener más información.

A continuación se muestra un ejemplo de 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.qhc

Para probar el archivo de colección generado, inicie Qt Assistant de la siguiente manera:

assistant -collectionFile mycollection.qhc

Utilización remota de Qt Assistant

Aunque el visor de ayuda es una aplicación independiente, en la mayoría de los casos será lanzado por la aplicación a la que proporciona ayuda. Este enfoque ofrece a la aplicación la posibilidad de 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, puede solicitar que se muestren otros contenidos de ayuda en función del estado actual de la aplicación.

Asi que, para usar Qt Assistant como el visor de ayuda personalizado de tu aplicacion, simplemente crea un QProcess y especifica la ruta al ejecutable Qt Assistant. Para hacer 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 hacerlo:

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 se está ejecutando, puede enviar comandos utilizando el canal stdin del proceso. El siguiente fragmento de código muestra cómo indicar a Qt Assistant que muestre una determinada página de la documentación.

QByteArray ba;
ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n");
process->write(ba);

Los siguientes comandos se pueden utilizar para controlar Qt Assistant:

Si desea enviar varios comandos en un corto período de tiempo, se recomienda que escriba una sola línea en la entrada estándar del proceso en lugar de una línea por cada comando. Los comandos deben ir separados por punto y coma, 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);