- class QHelpEngineCore#
The
QHelpEngineCore
class provides the core functionality of the help system. More…Inherited by:
QHelpEngine
Synopsis#
Properties#
autoSaveFilterᅟ
- Whether QHelpEngineCore is in auto save filter mode or notcollectionFileᅟ
- The absolute file name of the collection file currently usedcurrentFilterᅟ
- The name of the custom filter currently appliedreadOnlyᅟ
- Whether the help engine is read-only
Methods#
def
__init__()
def
autoSaveFilter()
def
collectionFile()
def
currentFilter()
def
customFilters()
def
customValue()
def
error()
def
fileData()
def
files()
def
filterEngine()
def
findFile()
def
isReadOnly()
def
setCustomValue()
def
setReadOnly()
def
setupData()
Signals#
def
setupFinished()
def
setupStarted()
def
warning()
Static functions#
def
metaData()
def
namespaceName()
Note
This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE
Detailed Description#
Before the help engine can be used, it must be initialized by calling
setupData()
. At the beginning of the setup process the signalsetupStarted()
is emitted. From this point on until the signalsetupFinished()
is emitted, is the help data in an undefined meaning unusable state.The core help engine can be used to perform different tasks. By calling
documentsForIdentifier()
the engine returns URLs specifying the file locations inside the help system. The actual file data can then be retrieved by callingfileData()
.The help engine can contain any number of custom filters. The management of the filters, including adding new filters, changing filter definitions, or removing existing filters, is done through the
QHelpFilterEngine
class, which can be accessed by thefilterEngine()
method.Note
QHelpFilterEngine
replaces the older filter API that is deprecated since Qt 5.13. CallsetUsesFilterEngine()
withtrue
to enable the new functionality.The core help engine has two modes:
Read-only mode, where the help collection file is not changed unless explicitly requested. This also works if the collection file is in a read-only location, and is the default.
Fully writable mode, which requires the help collection file to be writable.
The mode can be changed by calling
setReadOnly()
method, prior to callingsetupData()
.The help engine also offers the possibility to set and read values in a persistent way comparable to ini files or Windows registry entries. For more information see setValue() or value().
This class does not offer any GUI components or functionality for indices or contents. If you need one of those use
QHelpEngine
instead.Note
Properties can be used directly when
from __feature__ import true_property
is used or via accessor functions otherwise.- property autoSaveFilterᅟ: bool#
This property holds whether
QHelpEngineCore
is in auto save filter mode or not..If
QHelpEngineCore
is in auto save filter mode, the current filter is automatically saved when it is changed by thesetActiveFilter()
function. The filter is saved persistently in the help collection file.By default, this mode is on.
- Access functions:
- property collectionFileᅟ: str#
This property holds the absolute file name of the collection file currently used..
Setting this property leaves the help engine in an invalid state. It is important to invoke
setupData()
or any getter function in order to setup the help engine again.- Access functions:
- property currentFilterᅟ: str#
This property holds the name of the custom filter currently applied..
activeFilter()
should be used instead.Setting this property will save the new custom filter permanently in the help collection file. To set a custom filter without saving it permanently, disable the auto save filter mode.
See also
- Access functions:
- property readOnlyᅟ: bool#
This property holds whether the help engine is read-only..
In read-only mode, the user can use the help engine with a collection file installed in a read-only location. In this case, some functionality won’t be accessible, like registering additional documentation, filter editing, or any action that would require changes to the collection file. Setting it to
false
enables the full functionality of the help engine.By default, this property is
true
.- Access functions:
Constructs a new core help engine with a
parent
. The help engine uses the information stored in thecollectionFile
to provide help. If the collection file does not exist yet, it’ll be created.- addCustomFilter(filterName, attributes)#
- Parameters:
filterName – str
attributes – list of strings
- Return type:
bool
setFilterData()
should be used instead.Adds the new custom filter
filterName
. The filter attributes are specified byattributes
. If the filter already exists, its attribute set is replaced. The function returns true if the operation succeeded, otherwise it returns false.See also
- autoSaveFilter()#
- Return type:
bool
See also
Getter of property
autoSaveFilterᅟ
.- collectionFile()#
- Return type:
str
See also
Getter of property
collectionFileᅟ
.- copyCollectionFile(fileName)#
- Parameters:
fileName – str
- Return type:
bool
Creates the file
fileName
and copies all contents from the current collection file into the newly created file, and returns true if successful; otherwise returns false.The copying process makes sure that file references to Qt Collection files (
.qch
) files are updated accordingly.- currentFilter()#
- Return type:
str
See also
Getter of property
currentFilterᅟ
.- currentFilterChanged(newFilter)#
- Parameters:
newFilter – str
filterActivated()
should be used instead.This signal is emitted when the current filter is changed to
newFilter
.- customFilters()#
- Return type:
list of strings
filters()
should be used instead.Returns a list of custom filters.
See also
- customValue(key[, defaultValue=None])#
- Parameters:
key – str
defaultValue – object
- Return type:
object
Returns the value assigned to the
key
. If the requested key does not exist, the specifieddefaultValue
is returned.See also
- documentationFileName(namespaceName)#
- Parameters:
namespaceName – str
- Return type:
str
Returns the absolute file name of the Qt compressed help file (.qch) identified by the
namespaceName
. If there is no Qt compressed help file with the specified namespace registered, an empty string is returned.See also
Returns a list of all the document links found for the
id
. The returned list contents depend on the current filter, and therefore only the keywords registered for the current filter will be returned.- documentsForIdentifier(id, filterName)
- Parameters:
id – str
filterName – str
- Return type:
.list of QHelpLink
Returns a list of the document links found for the
id
, filtered byfilterName
. The returned list contents depend on the passed filter, and therefore only the keywords registered for this filter will be returned. If you want to get all results unfiltered, pass empty string asfilterName
.Returns a list of all the document links found for the
keyword
. The returned list contents depend on the current filter, and therefore only the keywords registered for the current filter will be returned.- documentsForKeyword(keyword, filterName)
- Parameters:
keyword – str
filterName – str
- Return type:
.list of QHelpLink
Returns a list of the document links found for the
keyword
, filtered byfilterName
. The returned list contents depend on the passed filter, and therefore only the keywords registered for this filter will be returned. If you want to get all results unfiltered, pass empty string asfilterName
.- error()#
- Return type:
str
Returns a description of the last error that occurred.
Returns the data of the file specified by
url
. If the file does not exist, an empty QByteArray is returned.See also
- files(namespaceName, filterName[, extensionFilter=""])#
- Parameters:
namespaceName – str
filterName – str
extensionFilter – str
- Return type:
.list of QUrl
Returns a list of files contained in the Qt compressed help file for
namespaceName
. The files can be filtered byfilterName
as well as by their extensionextensionFilter
(for example, ‘html’).- files(namespaceName, filterAttributes[, extensionFilter=""])
- Parameters:
namespaceName – str
filterAttributes – list of strings
extensionFilter – str
- Return type:
.list of QUrl
files() should be used instead.
Returns a list of files contained in the Qt compressed help file
namespaceName
. The files can be filtered byfilterAttributes
as well as by their extensionextensionFilter
(e.g. ‘html’).- filterAttributeSets(namespaceName)#
- Parameters:
namespaceName – str
- Return type:
.list of QStringList
filterData()
should be used instead.Returns a list of filter attributes for the different filter sections defined in the Qt compressed help file with the given namespace
namespaceName
.- filterAttributes()#
- Return type:
list of strings
availableComponents()
should be used instead.Returns a list of all defined filter attributes.
- filterAttributes(filterName)
- Parameters:
filterName – str
- Return type:
list of strings
filterData()
should be used instead.Returns a list of filter attributes used by the custom filter
filterName
.- filterEngine()#
- Return type:
Returns the filter engine associated with this help engine. The filter engine allows for adding, changing, and removing existing filters for this help engine. To use the engine you also have to call
setUsesFilterEngine()
set totrue
.Returns the corrected URL for the
url
that may refer to a different namespace defined by the virtual folder defined as a part of theurl
. If the virtual folder matches the namespace of theurl
, the method just checks if the file exists and returns the sameurl
. When the virtual folder doesn’t match the namespace of theurl
, it tries to find the best matching namespace according to the active filter. When the namespace is found, it returns the corrected URL if the file exists, otherwise it returns an invalid URL.- isReadOnly()#
- Return type:
bool
Getter of property
readOnlyᅟ
.- static metaData(documentationFileName, name)#
- Parameters:
documentationFileName – str
name – str
- Return type:
object
Returns the meta data for the Qt compressed help file
documentationFileName
. If there is no data available forname
, an invalid QVariant() is returned. The meta data is defined when creating the Qt compressed help file and cannot be modified later. Common meta data includes e.g. the author of the documentation.- static namespaceName(documentationFileName)#
- Parameters:
documentationFileName – str
- Return type:
str
Returns the namespace name defined for the Qt compressed help file (.qch) specified by its
documentationFileName
. If the file is not valid, an empty string is returned.See also
- readersAboutToBeInvalidated()#
- registerDocumentation(documentationFileName)#
- Parameters:
documentationFileName – str
- Return type:
bool
Registers the Qt compressed help file (.qch) contained in the file
documentationFileName
. One compressed help file, uniquely identified by its namespace can only be registered once. True is returned if the registration was successful, otherwise false.See also
- registeredDocumentations()#
- Return type:
list of strings
Returns a list of all registered Qt compressed help files of the current collection file. The returned names are the namespaces of the registered Qt compressed help files (.qch).
- removeCustomFilter(filterName)#
- Parameters:
filterName – str
- Return type:
bool
removeFilter()
should be used instead.Returns true if the filter
filterName
was removed successfully, otherwise false.See also
- removeCustomValue(key)#
- Parameters:
key – str
- Return type:
bool
Removes the
key
from the settings section in the collection file. Returns true if the value was removed successfully, otherwise false.See also
- setAutoSaveFilter(save)#
- Parameters:
save – bool
See also
Setter of property
autoSaveFilterᅟ
.- setCollectionFile(fileName)#
- Parameters:
fileName – str
See also
Setter of property
collectionFileᅟ
.- setCurrentFilter(filterName)#
- Parameters:
filterName – str
See also
Setter of property
currentFilterᅟ
.- setCustomValue(key, value)#
- Parameters:
key – str
value – object
- Return type:
bool
Save the
value
under thekey
. If the key already exist, the value will be overwritten. Returns true if the value was saved successfully, otherwise false.See also
- setReadOnly(enable)#
- Parameters:
enable – bool
See also
Setter of property
readOnlyᅟ
.- setUsesFilterEngine(uses)#
- Parameters:
uses – bool
Enables or disables the new filter engine functionality inside the help engine, according to the passed
uses
parameter.See also
- setupData()#
- Return type:
bool
Sets up the help engine by processing the information found in the collection file and returns true if successful; otherwise returns false.
By calling the function, the help engine is forced to initialize itself immediately. Most of the times, this function does not have to be called explicitly because getter functions which depend on a correctly set up help engine do that themselves.
Note
qsqlite4.dll
needs to be deployed with the application as the help system uses the sqlite driver when loading help collections.- setupFinished()#
This signal is emitted when the setup is complete.
- setupStarted()#
This signal is emitted when setup is started.
- unregisterDocumentation(namespaceName)#
- Parameters:
namespaceName – str
- Return type:
bool
Unregisters the Qt compressed help file (.qch) identified by its
namespaceName
from the help collection. Returns true on success, otherwise false.See also
- usesFilterEngine()#
- Return type:
bool
Returns whether the help engine uses the new filter functionality.
See also
- warning(msg)#
- Parameters:
msg – str
This signal is emitted when a non critical error occurs. The warning message is stored in
msg
.