Ejemplo de visor de texto sencillo
Uso de Qt Assistant como visor de ayuda personalizado para tu aplicación.

Este ejemplo muestra cómo utilizar Qt Assistant como visor de ayuda personalizado en una aplicación propia. Esto se lleva a cabo en dos fases. En primer lugar, se crea la documentación y se personaliza Qt Assistant; en segundo lugar, se añade a la aplicación la funcionalidad para iniciar y controlar Qt Assistant.
La aplicación «Simple Text Viewer» permite al usuario seleccionar y visualizar archivos existentes. La aplicación proporciona su propia documentación personalizada, a la que se puede acceder desde el menú «Ayuda» de la barra de menús de la ventana principal o haciendo clic en el botón «Ayuda» del cuadro de diálogo de búsqueda de archivos de la aplicación.
El ejemplo consta de cuatro clases:
Assistantproporciona la funcionalidad para iniciar Qt Assistant.MainWindowes la ventana principal de la aplicación.FindFileDialogpermite al usuario buscar archivos utilizando comodines.TextEditproporciona un navegador de texto enriquecido que garantiza que las imágenes a las que se hace referencia en los documentos HTML se muestren correctamente.
Nota: Solocomentaremos las partes de la implementación que son relevantes para el tema principal, es decir, hacer que Qt Assistant actúe como un visor de ayuda personalizado para nuestra aplicación Simple Text Viewer.
Creación de documentación y personalización Qt Assistant
La forma de crear la documentación propiamente dicha en forma de páginas HTML queda fuera del alcance de este ejemplo. En general, las páginas HTML pueden escribirse a mano o generarse con la ayuda de herramientas de documentación como qdoc o Doxygen. A efectos de este ejemplo, suponemos que los archivos HTML ya se han creado. Por lo tanto, lo único que queda por hacer es indicar a Qt Assistant cómo estructurar y mostrar la información de ayuda.
Organización de la documentación para Qt Assistant
Los archivos HTML sin formato solo contienen texto o documentación sobre temas específicos, pero normalmente no incluyen información sobre cómo se relacionan entre sí los distintos documentos HTML ni en qué orden deben leerse. Lo que falta es una tabla de contenidos junto con un índice que permita acceder rápidamente a determinados contenidos de ayuda, sin tener que hojear un montón de documentos para encontrar una información concreta.
Para organizar la documentación y ponerla a disposición de Qt Assistant, debemos crear un archivo de proyecto de Qt Help (.qhp). La primera y más importante parte del archivo de proyecto es la definición del espacio de nombres. El espacio de nombres debe ser único y será la primera parte de la URL de la página en Qt Assistant. Además, debemos configurar una carpeta virtual que actúe como carpeta común para los conjuntos de documentación. Esto significa que dos conjuntos de documentación identificados por dos espacios de nombres diferentes pueden hacer referencias cruzadas a archivos HTML, ya que dichos archivos se encuentran en una gran carpeta virtual. Sin embargo, para este ejemplo, solo dispondremos de un conjunto de documentación, por lo que el nombre y la funcionalidad de la carpeta virtual no son importantes.
<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>org.qt-project.examples.simpletextviewer</namespace>
<virtualFolder>doc</virtualFolder>El siguiente paso es definir la sección de filtro. Una sección de filtro contiene la tabla de contenidos, los índices y una lista completa de todos los archivos de documentación, y se le puede asignar cualquier número de atributos de filtro. Un atributo de filtro es una cadena de caracteres normal que se puede elegir libremente. Más adelante, en Qt Assistant, los usuarios podrán definir un filtro personalizado que haga referencia a esos atributos. Si los atributos de una sección de filtro coinciden con los del filtro personalizado, se mostrará la documentación; de lo contrario, Qt Assistant ocultará la documentación.
De nuevo, dado que solo tendremos un conjunto de documentación, no necesitamos la funcionalidad de filtrado de Qt Assistant y, por lo tanto, podemos omitir los atributos de filtro.
Ahora, creamos la tabla de contenidos. Cada elemento de la tabla se define mediante la etiqueta section, que contiene los atributos del título del elemento, así como el enlace a la página correspondiente. Las etiquetas de sección se pueden anidar infinitamente, pero por razones prácticas no se recomienda anidarlas a más de tres o cuatro niveles de profundidad. Para nuestro ejemplo, queremos utilizar el siguiente esquema para la tabla de contenidos:
- Visor de texto sencillo
- Buscar archivo
- Cuadro de diálogo de archivos
- Coincidencia con comodines
- Explorar
- Abrir archivo
- Buscar archivo
En el archivo del proyecto de ayuda, el índice se representa de la siguiente manera:
<filterSection>
<toc>
<section title="Simple Text Viewer" ref="index.html">
<section title="Find File" ref="findfile.html">
<section title="File Dialog" ref="filedialog.html"/>
<section title="Wildcard Matching" ref="wildcardmatching.html"/>
<section title="Browse" ref="browse.html"/>
</section>
<section title="Open File" ref="openfile.html"/>
</section>
</toc>Una vez definido el índice, enumeraremos todas las palabras clave del índice:
<keywords>
<keyword name="Display" ref="index.html"/>
<keyword name="Rich text" ref="index.html"/>
<keyword name="Plain text" ref="index.html"/>
<keyword name="Find" ref="findfile.html"/>
<keyword name="File menu" ref="findfile.html"/>
<keyword name="File name" ref="filedialog.html"/>
<keyword name="File dialog" ref="filedialog.html"/>
<keyword name="File globbing" ref="wildcardmatching.html"/>
<keyword name="Wildcard matching" ref="wildcardmatching.html"/>
<keyword name="Wildcard syntax" ref="wildcardmatching.html"/>
<keyword name="Browse" ref="browse.html"/>
<keyword name="Directory" ref="browse.html"/>
<keyword name="Open" ref="openfile.html"/>
<keyword name="Select" ref="openfile.html"/>
</keywords>Como último paso, debemos enumerar todos los archivos que componen la documentación. Es importante tener en cuenta que deben incluirse todos los archivos, incluidos los de imágenes e incluso las hojas de estilo, si se utilizan.
<files>
<file>browse.html</file>
<file>filedialog.html</file>
<file>findfile.html</file>
<file>index.html</file>
<file>intro.html</file>
<file>openfile.html</file>
<file>wildcardmatching.html</file>
<file>images/browse.png</file>
<file>images/fadedfilemenu.png</file>
<file>images/filedialog.png</file>
<file>images/handbook.png</file>
<file>images/mainwindow.png</file>
<file>images/open.png</file>
<file>images/wildcard.png</file>
</files>
</filterSection>
</QtHelpProject>El archivo del proyecto de ayuda ya está terminado. Si quieres ver la documentación resultante en Qt Assistant, tienes que generar a partir de él un archivo de ayuda comprimido de Qt XML y registrarlo en la colección de ayuda predeterminada de Qt Assistant.
qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch
assistant -register simpletextviewer.qchSi abres ahora Qt Assistant, verás la documentación de Simple Text Viewer junto a la documentación de Qt. Esto está bien a efectos de prueba, pero para la versión final queremos que solo aparezca la documentación de Simple Text Viewer en Qt Assistant.
Personalización Qt Assistant
La forma más sencilla de conseguir que Qt Assistant muestre únicamente la documentación de Simple Text Viewer es crear nuestro propio archivo de colección de ayuda. Un archivo de colección se almacena en formato binario, similar al archivo de ayuda comprimido, y se genera a partir de un archivo de proyecto de colección de ayuda (*.qhcp). Con la ayuda de un archivo de colección, podemos personalizar el aspecto e incluso algunas de las funcionalidades que ofrece Qt Assistant.
En primer lugar, cambiamos el título y el icono de la ventana. En lugar de mostrar «Qt Assistant », mostrará «Simple Text Viewer», de modo que quede mucho más claro para el usuario que el visor de ayuda pertenece realmente a nuestra aplicación.
<?xml version="1.0" encoding="UTF-8"?>
<QHelpCollectionProject version="1.0">
<assistant>
<title>Simple Text Viewer</title>
<applicationIcon>images/handbook.png</applicationIcon>
<cacheDirectory>QtProject/SimpleTextViewer</cacheDirectory>La etiqueta cacheDirectory especifica un subdirectorio del directorio de datos del usuario (véase «Archivos de colección deQt Help ») donde se almacenará el archivo de caché para la búsqueda de texto completo o el archivo de configuración.
A continuación, configuramos la página que mostrará Qt Assistant al iniciarse por primera vez con su nueva configuración. La URL consta del espacio de nombres y la carpeta virtual definidos en el archivo de proyecto de Qt Help, seguidos del nombre real del archivo de la página.
<startPage>qthelp://org.qt-project.examples.simpletextviewer/doc/index.html</startPage>A continuación, cambiamos el nombre del elemento de menú «Acerca de» por «Acerca de Simple Text Viewer». El contenido del cuadro de diálogo «Acerca de» también se modifica especificando un archivo del que se extrae el texto o el icono de «Acerca de».
<aboutMenuText>
<text>About Simple Text Viewer</text>
</aboutMenuText>
<aboutDialog>
<file>about.txt</file>
<icon>images/icon.png</icon>
</aboutDialog>Qt Assistant Ofrece la posibilidad de añadir o eliminar documentación a través de su cuadro de diálogo de preferencias. Esta funcionalidad resulta útil cuando se utiliza Qt Assistant como visor de ayuda central para varias aplicaciones, pero en nuestro caso queremos evitar que el usuario elimine la documentación. Por lo tanto, ocultamos la pestaña «Documentación» en el cuadro de diálogo «Preferencias ».
Dado que la barra de direcciones no es realmente relevante en un conjunto de documentación tan pequeño, también la desactivamos. Al tener solo una sección de filtro, sin ningún atributo de filtro, también podemos desactivar la funcionalidad de filtro de Qt Assistant, lo que significa que la página de filtro y la barra de herramientas de filtro no estarán disponibles.
<enableDocumentationManager>false</enableDocumentationManager>
<enableAddressBar>false</enableAddressBar>
<enableFilterFunctionality>false</enableFilterFunctionality>
</assistant>A efectos de prueba, ya hemos generado el archivo de ayuda comprimido y lo hemos registrado en la colección de ayuda predeterminada de Qt Assistant. Con las siguientes líneas conseguimos el mismo resultado. La única y importante diferencia es que registramos el archivo de ayuda comprimido, no en la colección predeterminada, sino en nuestro propio archivo de colección.
<docFiles>
<generate>
<file>
<input>simpletextviewer.qhp</input>
<output>simpletextviewer.qch</output>
</file>
</generate>
<register>
<file>simpletextviewer.qch</file>
</register>
</docFiles>
</QHelpCollectionProject>Como último paso, debemos generar el archivo de colección binario a partir del archivo de proyecto de la colección de ayuda. Para ello, ejecutamos la herramienta qhelpgenerator.
qhelpgenerator simpletextviewer.qhcp -o simpletextviewer.qhcPara probar todas las personalizaciones que hemos realizado en Qt Assistant, añadimos el nombre del archivo de colección a la línea de comandos:
assistant -collectionFile simpletextviewer.qhcControl de Qt Assistant mediante la clase Assistant
En primer lugar, veremos cómo iniciar y manejar Qt Assistant desde una aplicación remota. Para ello, creamos una clase llamada Assistant.
Esta clase proporciona una función pública que se utiliza para mostrar páginas de la documentación y una función auxiliar privada para asegurarnos de que Qt Assistant está en funcionamiento.
El inicio de Qt Assistant se realiza en la función startAssistant() simplemente creando e iniciando un QProcess. Si el proceso ya está en ejecución, la función devuelve un valor inmediatamente. De lo contrario, hay que configurar e iniciar el proceso.
bool Assistant::startAssistant()
{
if (!m_process) {
m_process = std::make_unique<QProcess>();
QObject::connect(m_process.get(), &QProcess::finished,
m_process.get(), [this](int exitCode, QProcess::ExitStatus status) {
finished(exitCode, status);
});
}
if (m_process->state() != QProcess::Running) {
QString app = QLibraryInfo::path(QLibraryInfo::BinariesPath);
#ifndef Q_OS_DARWIN
app += "/assistant"_L1;
#else
app += "/Assistant.app/Contents/MacOS/Assistant"_L1;
#endif
const QString collectionDirectory = documentationDirectory();
if (collectionDirectory.isEmpty()) {
showError(tr("The documentation directory cannot be found"));
return false;
}
const QStringList args{"-collectionFile"_L1,
collectionDirectory + "/simpletextviewer.qhc"_L1,
"-enableRemoteControl"_L1};
m_process->start(app, args);
if (!m_process->waitForStarted(3000)) {
showError(tr("Unable to launch Qt Assistant (%1): %2")
.arg(QDir::toNativeSeparators(app), m_process->errorString()));
return false;
}
}
return true;
}Para iniciar el proceso necesitamos el nombre del ejecutable de Qt Assistant, así como los argumentos de línea de comandos para ejecutar Qt Assistant en un modo personalizado. El nombre del ejecutable es un poco complicado, ya que depende de la plataforma, pero, afortunadamente, solo varía en macOS.
La documentación que se muestra puede modificarse utilizando el argumento de línea de comandos « -collectionFile » al iniciar Qt Assistant. Cuando se inicia sin opciones, Qt Assistant muestra un conjunto predeterminado de documentación. Cuando Qt está instalado, el conjunto de documentación predeterminado en Qt Assistant contiene la documentación de referencia de Qt, así como las herramientas que vienen con Qt, como Qt Designer y qmake.
En nuestro ejemplo, sustituimos el conjunto de documentación predeterminado por nuestra documentación personalizada pasando nuestro archivo de colección específico de la aplicación a las opciones de la línea de comandos del proceso.
Como último argumento, añadimos -enableRemoteControl, lo que hace que Qt Assistant escuche en su canal stdin los comandos, como los que sirven para mostrar una página concreta de la documentación. A continuación, iniciamos el proceso y esperamos a que se esté ejecutando realmente. Si, por alguna razón, Qt Assistant no se puede iniciar, startAssistant() devolverá «false».
La implementación de showDocumentation() es ahora muy sencilla. En primer lugar, nos aseguramos de que Qt Assistant esté en ejecución; a continuación, enviamos la solicitud para mostrar page a través del canal stdin del proceso. Es muy importante que el comando termine con un carácter de fin de línea para vaciar el canal.
void Assistant::showDocumentation(const QString &page)
{
if (!startAssistant())
return;
QByteArray ba("SetSource ");
ba.append("qthelp://org.qt-project.examples.simpletextviewer/doc/");
m_process->write(ba + page.toLocal8Bit() + '\n');
}Por último, nos aseguramos de que Qt Assistant se cierre correctamente en caso de que se cierre la aplicación. El destructor de QProcess termina el proceso, lo que significa que la aplicación no tiene la posibilidad de realizar acciones como guardar la configuración del usuario, lo que provocaría que los archivos de configuración quedaran dañados. Para evitarlo, solicitamos a Qt Assistant que se cierre en el destructor de la clase Assistant.
Assistant::~Assistant()
{
if (m_process && m_process->state() == QProcess::Running) {
QObject::disconnect(m_process.get(), &QProcess::finished, nullptr, nullptr);
m_process->terminate();
m_process->waitForFinished(3000);
}
}Clase MainWindow

La clase ` MainWindow ` proporciona a la ventana principal de la aplicación dos menús: el menú «Archivo» permite al usuario abrir y visualizar un archivo existente, mientras que el menú «Ayuda» ofrece información sobre la aplicación y sobre Qt, y permite al usuario abrir ` Qt Assistant ` para mostrar la documentación de la aplicación.
Para poder acceder a la funcionalidad de ayuda, inicializamos el objeto ` Assistant ` en el constructor de ` MainWindow`.
MainWindow::MainWindow()
: textViewer(new TextEdit)
, assistant(new Assistant)
{
...
}A continuación, creamos todas las acciones para la aplicación «Simple Text Viewer». Resulta de especial interés la acción « assistantAct », a la que se accede mediante el atajo F1 o la opción de menú «Ayuda > Contenido de la ayuda ». Esta acción está conectada a la ranura « showDocumentation() » de la clase « MainWindow ».
void MainWindow::createActions()
{
assistantAct = new QAction(tr("Help Contents"), this);
assistantAct->setShortcut(QKeySequence::HelpContents);
connect(assistantAct, &QAction::triggered, this, &MainWindow::showDocumentation);
...
}En el slot « showDocumentation() », llamamos a la función « showDocumentation() » de la clase « Assistant » con la URL de la página de inicio de la documentación.
void MainWindow::showDocumentation()
{
assistant->showDocumentation("index.html");
}Por último, debemos reimplementar el controlador de eventos protegido QWidget::closeEvent() para garantizar que la instancia de Qt Assistant de la aplicación se cierre correctamente antes de terminar la aplicación.
void MainWindow::closeEvent(QCloseEvent *)
{
delete assistant;
}Clase FindFileDialog

La aplicación «Simple Text Viewer» proporciona un cuadro de diálogo de búsqueda de archivos que permite al usuario buscar archivos utilizando comodines. La búsqueda se realiza dentro del directorio especificado, y el usuario tiene la opción de explorar el sistema de archivos existente para encontrar el directorio correspondiente.
En el constructor guardamos las referencias a los objetos ` Assistant ` y ` QTextEdit ` pasados como argumentos. El objeto ` Assistant ` se utilizará en la ranura ` help() ` de ` FindFileDialog`, como veremos en breve, mientras que el `QTextEdit` se utilizará en la ranura ` openFile() ` del cuadro de diálogo para mostrar el archivo seleccionado.
FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant)
: QDialog(editor)
, currentEditor(editor)
, currentAssistant(assistant)
{
...
}El miembro más relevante a tener en cuenta en la clase ` FindFileDialog ` es la ranura privada ` help() `. Esta ranura está conectada al botón «Ayuda» del cuadro de diálogo y lleva la instancia actual de ` Qt Assistant ` al primer plano con la documentación del cuadro de diálogo, llamando a la función ` showDocumentation() ` de ` Assistant`.
void FindFileDialog::help()
{
currentAssistant->showDocumentation("filedialog.html");
}Resumen
Para que Qt Assistant actúe como una herramienta de ayuda personalizada para su aplicación, debe proporcionar a su aplicación un proceso que controle Qt Assistant, además de un archivo de colección de ayuda personalizada que incluya archivos de ayuda comprimidos de Qt.
Para obtener más información sobre las opciones y configuraciones disponibles para las aplicaciones que utilizan Qt Assistant como visor de ayuda personalizado, consulta Personalización de Qt Assistant.
© 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.