En esta página

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:

QHelpEngine

Propiedades

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.