QHelpEngineCore Class
La clase QHelpEngineCore proporciona la funcionalidad básica del sistema de ayuda. Más información...
| Encabezado: | #include <QHelpEngineCore> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Help) target_link_libraries(mytarget PRIVATE Qt6::Help) |
| qmake: | QT += help |
| Heredado de: | QObject |
| Heredado por: |
Propiedades
- autoSaveFilter : bool
- collectionFile : QString
(since 6.0)readOnly : bool
Funciones públicas
| QHelpEngineCore(const QString &collectionFile, QObject *parent = nullptr) | |
| virtual | ~QHelpEngineCore() |
| bool | autoSaveFilter() const |
| QString | collectionFile() const |
| bool | copyCollectionFile(const QString &fileName) |
| QVariant | customValue(const QString &key, const QVariant &defaultValue = {}) const |
| QString | documentationFileName(const QString &namespaceName) |
| QList<QHelpLink> | documentsForIdentifier(const QString &id) const |
| QList<QHelpLink> | documentsForIdentifier(const QString &id, const QString &filterName) const |
| QList<QHelpLink> | documentsForKeyword(const QString &keyword) const |
| QList<QHelpLink> | documentsForKeyword(const QString &keyword, const QString &filterName) const |
| QString | error() const |
| QByteArray | fileData(const QUrl &url) const |
| QList<QUrl> | files(const QString namespaceName, const QString &filterName, const QString &extensionFilter = {}) |
| QHelpFilterEngine * | filterEngine() const |
| QUrl | findFile(const QUrl &url) const |
| bool | isReadOnly() const |
| bool | registerDocumentation(const QString &documentationFileName) |
| QStringList | registeredDocumentations() const |
| bool | removeCustomValue(const QString &key) |
| void | setAutoSaveFilter(bool save) |
| void | setCollectionFile(const QString &fileName) |
| bool | setCustomValue(const QString &key, const QVariant &value) |
| void | setReadOnly(bool enable) |
| void | setUsesFilterEngine(bool uses) |
| bool | setupData() |
| bool | unregisterDocumentation(const QString &namespaceName) |
| bool | usesFilterEngine() const |
Señales
| void | setupFinished() |
| void | setupStarted() |
| void | warning(const QString &msg) |
Miembros públicos estáticos
| QVariant | metaData(const QString &documentationFileName, const QString &name) |
| QString | namespaceName(const QString &documentationFileName) |
Descripción detallada
Antes de poder utilizar el motor de ayuda, es necesario inicializarlo llamando a ` setupData()`. Al inicio del proceso de configuración se emite la señal ` setupStarted()`. Desde ese momento y hasta que se emita la señal ` setupFinished()`, los datos de ayuda se encuentran en un estado indefinido, lo que significa que no se pueden utilizar.
El motor de ayuda principal puede utilizarse para realizar diferentes tareas. Al llamar a documentsForIdentifier(), el motor devuelve direcciones URL que especifican la ubicación de los archivos dentro del sistema de ayuda. A continuación, los datos reales de los archivos pueden recuperarse llamando a fileData().
El motor de ayuda puede contener cualquier número de filtros personalizados. La gestión de los filtros —incluida la adición de nuevos filtros, la modificación de definiciones de filtros o la eliminación de filtros existentes— se realiza a través de la clase ` QHelpFilterEngine `, a la que se puede acceder mediante el método ` filterEngine()`.
Nota: ` QHelpFilterEngine ` sustituye a la antigua API de filtros, que quedó obsoleta a partir de Qt 5.13. Llama a ` setUsesFilterEngine()` con ` true ` para habilitar la nueva funcionalidad.
El motor de ayuda principal tiene dos modos:
- Modo de solo lectura, en el que el archivo de la colección de ayuda no se modifica a menos que se solicite explícitamente. Esto también funciona si el archivo de la colección se encuentra en una ubicación de solo lectura, y es el modo predeterminado.
- Modo totalmente grabable, que requiere que el archivo de la colección de ayuda sea grabable.
El modo se puede cambiar llamando al método setReadOnly(), antes de llamar a setupData().
El motor de ayuda también ofrece la posibilidad de establecer y leer valores de forma persistente, de manera similar a los archivos INI o a las entradas del Registro de Windows. Para obtener más información, consulta setCustomValue() o customValue().
Esta clase no ofrece ningún componente de interfaz gráfica de usuario ni funcionalidad para índices o contenidos. Si necesitas alguno de ellos, utiliza en su lugar QHelpEngine.
Documentación de propiedades
autoSaveFilter : bool
Esta propiedad se mantiene independientemente de si QHelpEngineCore se encuentra en modo de guardado automático de filtros o no.
Si QHelpEngineCore está en modo de filtro de guardado automático, el filtro actual se guarda automáticamente cuando se modifica mediante la función QHelpFilterEngine::setActiveFilter(). El filtro se guarda de forma permanente en el archivo de la colección de ayuda.
De forma predeterminada, este modo está activado.
Funciones de acceso:
| bool | autoSaveFilter() const |
| void | setAutoSaveFilter(bool save) |
collectionFile : QString
Esta propiedad contiene el nombre de archivo absoluto del archivo de colección que se está utilizando actualmente.
Al establecer esta propiedad, el motor de ayuda queda en un estado no válido. Es importante llamar a ` setupData()` o a cualquier función getter para volver a configurar el motor de ayuda.
Funciones de acceso:
| QString | collectionFile() const |
| void | setCollectionFile(const QString &fileName) |
[since 6.0] readOnly : bool
Esta propiedad indica si el motor de ayuda está en modo de solo lectura.
En modo de solo lectura, el usuario puede utilizar el motor de ayuda con un archivo de colección instalado en una ubicación de solo lectura. En este caso, no se podrá acceder a algunas funciones, como registrar documentación adicional, editar filtros o cualquier acción que requiera cambios en el archivo de colección. Al establecerla en « false », se habilita toda la funcionalidad del motor de ayuda.
Por defecto, esta propiedad está configurada en « true ».
Esta enumeración se introdujo en Qt 6.0.
Funciones de acceso:
| bool | isReadOnly() const |
| void | setReadOnly(bool enable) |
Documentación de las funciones miembro
[explicit] QHelpEngineCore::QHelpEngineCore(const QString &collectionFile, QObject *parent = nullptr)
Crea un nuevo motor de ayuda principal con un archivo « parent ». El motor de ayuda utiliza la información almacenada en el archivo « collectionFile » para proporcionar ayuda. Si el archivo de recopilación aún no existe, se creará.
[virtual noexcept] QHelpEngineCore::~QHelpEngineCore()
Elimina el motor de ayuda.
bool QHelpEngineCore::copyCollectionFile(const QString &fileName)
Crea el archivo « fileName » y copia todo el contenido del archivo de colección actual al archivo recién creado; devuelve «true» si la operación se realiza correctamente; en caso contrario, devuelve «false».
El proceso de copia garantiza que las referencias a los archivos de la colección Qt (.qch) se actualicen como corresponde.
QVariant QHelpEngineCore::customValue(const QString &key, const QVariant &defaultValue = {}) const
Devuelve el valor asignado a ` key`. Si la clave solicitada no existe, se devuelve el valor de ` defaultValue ` especificado.
Véanse también setCustomValue() y removeCustomValue().
QString QHelpEngineCore::documentationFileName(const QString &namespaceName)
Devuelve el nombre de archivo absoluto del archivo de ayuda comprimido de Qt (.qch) identificado por el namespaceName. Si no hay ningún archivo de ayuda comprimido de Qt registrado con el espacio de nombres especificado, se devuelve una cadena vacía.
Véase también namespaceName().
QList<QHelpLink> QHelpEngineCore::documentsForIdentifier(const QString &id) const
Devuelve una lista con todos los enlaces a documentos encontrados para « id ». El contenido de la lista devuelta depende del filtro actual y, por lo tanto, solo se mostrarán las palabras clave registradas para dicho filtro.
QList<QHelpLink> QHelpEngineCore::documentsForIdentifier(const QString &id, const QString &filterName) const
Devuelve una lista con los enlaces a documentos encontrados para « id », filtrados por « filterName ». El contenido de la lista devuelta depende del filtro pasado; por lo tanto, solo se devolverán las palabras clave registradas para este filtro. Si deseas obtener todos los resultados sin filtrar, pasa una cadena vacía como « filterName ».
QList<QHelpLink> QHelpEngineCore::documentsForKeyword(const QString &keyword) const
Devuelve una lista con todos los enlaces a documentos encontrados para keyword. El contenido de la lista devuelta depende del filtro actual y, por lo tanto, solo se mostrarán las palabras clave registradas para dicho filtro.
QList<QHelpLink> QHelpEngineCore::documentsForKeyword(const QString &keyword, const QString &filterName) const
Devuelve una lista con los enlaces a documentos encontrados para « keyword », filtrados por « filterName ». El contenido de la lista devuelta depende del filtro pasado; por lo tanto, solo se devolverán las palabras clave registradas para este filtro. Si deseas obtener todos los resultados sin filtrar, pasa una cadena vacía como « filterName ».
QString QHelpEngineCore::error() const
Devuelve una descripción del último error que se ha producido.
QByteArray QHelpEngineCore::fileData(const QUrl &url) const
Devuelve los datos del archivo especificado mediante ` url`. Si el archivo no existe, se devuelve un objeto ` QByteArray ` vacío.
Véase también findFile().
QList<QUrl> QHelpEngineCore::files(const QString namespaceName, const QString &filterName, const QString &extensionFilter = {})
Devuelve una lista de los archivos contenidos en el archivo de ayuda comprimido de Qt correspondiente a namespaceName. Los archivos se pueden filtrar por filterName, así como por su extensión extensionFilter (por ejemplo, «html»).
QHelpFilterEngine *QHelpEngineCore::filterEngine() const
Devuelve el motor de filtrado asociado a este motor de ayuda. El motor de filtrado permite añadir, modificar y eliminar filtros existentes para este motor de ayuda. Para utilizar el motor, también debes llamar a la función ` setUsesFilterEngine()` con el valor ` true`.
QUrl QHelpEngineCore::findFile(const QUrl &url) const
Devuelve la URL corregida para url, que puede hacer referencia a un espacio de nombres diferente definido por la carpeta virtual definida como parte de url. Si la carpeta virtual coincide con el espacio de nombres de url, el método simplemente comprueba si el archivo existe y devuelve la misma url. Cuando la carpeta virtual no coincide con el espacio de nombres de url, intenta encontrar el espacio de nombres que mejor se ajuste según el filtro activo. Una vez encontrado el espacio de nombres, devuelve la URL corregida si el archivo existe; de lo contrario, devuelve una URL no válida.
[static] QVariant QHelpEngineCore::metaData(const QString &documentationFileName, const QString &name)
Devuelve los metadatos del archivo de ayuda comprimido de Qt documentationFileName. Si no hay datos disponibles para name, se devuelve un QVariant() no válido. Los metadatos se definen al crear el archivo de ayuda comprimido de Qt y no se pueden modificar posteriormente. Entre los metadatos habituales se incluye, por ejemplo, el autor de la documentación.
[static] QString QHelpEngineCore::namespaceName(const QString &documentationFileName)
Devuelve el nombre del espacio de nombres definido para el archivo de ayuda comprimido de Qt (.qch) especificado mediante su ` documentationFileName`. Si el archivo no es válido, se devuelve una cadena vacía.
Véase también documentationFileName().
bool QHelpEngineCore::registerDocumentation(const QString &documentationFileName)
Registra el archivo de ayuda comprimido de Qt (.qch) contenido en el archivo documentationFileName. Un archivo de ayuda comprimido, identificado de forma única por su espacio de nombres, solo puede registrarse una vez. Se devuelve «True» si el registro se ha realizado correctamente; en caso contrario, se devuelve «False».
Véase también unregisterDocumentation() y error().
QStringList QHelpEngineCore::registeredDocumentations() const
Devuelve una lista de todos los archivos de ayuda comprimidos de Qt registrados en el archivo de colección actual. Los nombres devueltos son los espacios de nombres de los archivos de ayuda comprimidos de Qt registrados (.qch).
bool QHelpEngineCore::removeCustomValue(const QString &key)
Elimina el parámetro « key » de la sección de configuración del archivo de recopilación. Devuelve «true» si el valor se ha eliminado correctamente; en caso contrario, devuelve «false».
Véase también customValue() y setCustomValue().
bool QHelpEngineCore::setCustomValue(const QString &key, const QVariant &value)
Guarda el objeto ` value ` bajo la clave ` key`. Si la clave ya existe, se sobrescribirá el valor. Devuelve «true» si el valor se ha guardado correctamente; en caso contrario, devuelve «false».
Véase también customValue() y removeCustomValue().
void QHelpEngineCore::setUsesFilterEngine(bool uses)
Activa o desactiva la nueva funcionalidad del motor de filtrado dentro del motor de ayuda, según el parámetro uses que se le pase.
Véase también usesFilterEngine() y filterEngine().
bool QHelpEngineCore::setupData()
Configura el motor de ayuda procesando la información que se encuentra en el archivo de recopilación y devuelve «true» si se realiza correctamente; en caso contrario, devuelve «false».
Al llamar a esta función, se obliga al motor de ayuda a inicializarse inmediatamente. En la mayoría de los casos, no es necesario llamar a esta función de forma explícita, ya que las funciones getter que dependen de un motor de ayuda correctamente configurado lo hacen por sí mismas.
Nota: Es necesario implementarqsqlite4.dll junto con la aplicación, ya que el sistema de ayuda utiliza el controlador sqlite al cargar las colecciones de ayuda.
[signal] void QHelpEngineCore::setupFinished()
Esta señal se emite cuando la configuración ha finalizado.
[signal] void QHelpEngineCore::setupStarted()
Esta señal se emite al iniciar la configuración.
bool QHelpEngineCore::unregisterDocumentation(const QString &namespaceName)
Elimina de la colección de ayuda el archivo de ayuda comprimido de Qt (.qch) identificado por su namespaceName. Devuelve «true» si se realiza correctamente; en caso contrario, devuelve «false».
Véase también registerDocumentation() y error().
bool QHelpEngineCore::usesFilterEngine() const
Indica si el motor de ayuda utiliza la nueva funcionalidad de filtrado.
Véase también setUsesFilterEngine() y filterEngine().
[signal] void QHelpEngineCore::warning(const QString &msg)
Esta señal se emite cuando se produce un error no crítico. El mensaje de advertencia se almacena en msg.
© 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.