Qt 4.4: QHelpEngineCore Class Reference

|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# QHelpEngineCore Class Reference
[QtHelp module]

The QHelpEngineCore class provides the core functionality of the help system. More...

     #include <QHelpEngineCore>

Inherits QObject.

Inherited by QHelpEngine.

- List of all members, including inherited members

### Public Functions

- QHelpEngineCore ( const QString & collectionFile, QObject * parent = 0 )
- virtual ~QHelpEngineCore ()
- bool addCustomFilter ( const QString & filterName, const QStringList & attributes )
- QString collectionFile () const
- bool copyCollectionFile ( const QString & fileName )
- QString currentFilter () const
- QStringList customFilters () const
- QVariant customValue ( const QString & key, const QVariant & defaultValue = QVariant() ) const
- QString documentationFileName ( const QString & namespaceName )
- QString error () const
- QByteArray fileData ( const QUrl & url ) const
- QList<QUrl> files ( const QString namespaceName, const QStringList & filterAttributes, const QString & extensionFilter = QString() )
- QList<QStringList> filterAttributeSets ( const QString & namespaceName ) const
- QStringList filterAttributes () const
- QStringList filterAttributes ( const QString & filterName ) const
- QUrl findFile ( const QUrl & url ) const
- QMap<QString, QUrl> linksForIdentifier ( const QString & id ) const
- bool registerDocumentation ( const QString & documentationFileName )
- QStringList registeredDocumentations () const
- bool removeCustomFilter ( const QString & filterName )
- bool removeCustomValue ( const QString & key )
- void setCollectionFile ( const QString & fileName )
- void setCurrentFilter ( const QString & filterName )
- bool setCustomValue ( const QString & key, const QVariant & value )
- bool setupData ()
- bool unregisterDocumentation ( const QString & namespaceName )

- 29 public functions inherited from QObject

### Signals

- void currentFilterChanged ( const QString & newFilter )
- void setupFinished ()
- void setupStarted ()
- void warning ( const QString & msg )

- 1 signal inherited from QObject

### Static Public Members

- QVariant metaData ( const QString & documentationFileName, const QString & name )
- QString namespaceName ( const QString & documentationFileName )

- 5 static public members inherited from QObject

### Additional Inherited Members

- 1 property inherited from QObject
- 1 public slot inherited from QObject
- 7 protected functions inherited from QObject

## Detailed Description

The QHelpEngineCore class provides the core functionality of the help system.

Before the help engine can be used, it must be initialized by calling setupData(). At the beginning of the setup process the signal setupStarted() is emitted. From this point on until the signal setupFinished() 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 linksForIdentifier() the engine returns urls specifying the file locations inside the help system. The actual file data can then be retrived by calling fileData(). In contrast to all other functions in this class, linksForIdentifier() depends on the currently set custom filter. Depending on the filter, the function may return different hits.

Every help engine can contain any number of custom filters. A custom filter is defined by a name and set of filter attributes and can be added to the help engine by calling addCustomFilter(). Analogous, it is removed by calling removeCustomFilter(). customFilters() returns all defined filters.

The help engine also offers the possiblity to set and read values in a persistant 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.

## Member Function Documentation

### QHelpEngineCore::QHelpEngineCore ( const QString & collectionFile, QObject * parent = 0 )

Constructs a new core help engine with a parent. The help engine uses the information stored in the collectionFile to provide help. If the collection file does not exist yet, it'll be created.

### QHelpEngineCore::~QHelpEngineCore () `[virtual]`

Destructs the help engine.

### bool QHelpEngineCore::addCustomFilter ( const QString & filterName, const QStringList & attributes )

Adds the new custom filter filterName. The filter attributes are specified by attributes. The function returns false if the filter can not be added, e.g. when the filter already exists.

See also customFilters() and removeCustomFilter().

### QString QHelpEngineCore::collectionFile () const

Returns the absolute file path of the collection file.

See also setCollectionFile().

### bool QHelpEngineCore::copyCollectionFile ( const QString & fileName )

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.

### QString QHelpEngineCore::currentFilter () const

Returns the name of the current custom filter.

See also setCurrentFilter().

### void QHelpEngineCore::currentFilterChanged ( const QString & newFilter ) `[signal]`

This signal is emitted when the current filter is changed to newFilter.

### QStringList QHelpEngineCore::customFilters () const

Returns a list of custom filters.

See also addCustomFilter() and removeCustomFilter().

### QVariant QHelpEngineCore::customValue ( const QString & key, const QVariant & defaultValue = QVariant() ) const

Returns the value assigned to the key. If the requested key does not exist, the specified defaultValue is returned.

See also setCustomValue() and removeCustomValue().

### QString QHelpEngineCore::documentationFileName ( const QString & namespaceName )

Returns the absolute file name of the Qt documentation file (.qch) identified by the namespaceName. If there is no documentation with the specified namespace registered, an empty string is returned.

See also namespaceName().

### QString QHelpEngineCore::error () const

Returns a description of the last error that occured.

### QByteArray QHelpEngineCore::fileData ( const QUrl & url ) const

Returns the data of the file specified by url. If the file does not exist, an empty QByteArray is returned.

/sa findFile()

### QList<QUrl> QHelpEngineCore::files ( const QString namespaceName, const QStringList & filterAttributes, const QString & extensionFilter = QString() )

Returns a list of files contained in the documentation set namespaceName. The files can be filtered by filterAttributes as well as by their extension extensionFilter (e.g. 'html').

### QList<QStringList> QHelpEngineCore::filterAttributeSets ( const QString & namespaceName ) const

Returns a list of filter attributes for the different filter sections defined in the documentation set with the namespace namespaceName.

### QStringList QHelpEngineCore::filterAttributes () const

Returns a list of all defined filter attributes.

### QStringList QHelpEngineCore::filterAttributes ( const QString & filterName ) const

This is an overloaded member function, provided for convenience.

Returns a list of filter attributes used by the custom filter filterName.

### QUrl QHelpEngineCore::findFile ( const QUrl & url ) const

Returns an invalid URL if the file url cannot be found. If the file exists, either the same url is returned or a different url if the file is located in a different namespace which is merged via a common virtual folder.

### QMap<QString, QUrl> QHelpEngineCore::linksForIdentifier ( const QString & id ) const

Returns a map of hits found for the id. A hit contains the title of the document and the url where the keyword is located. The result depends on the current filter, meaning only the keywords registered for the current filter will be returned.

### QVariant QHelpEngineCore::metaData ( const QString & documentationFileName, const QString & name ) `[static]`

Returns the meta data for the documentation file documentationFileName. If there is no data available for name, an invalid QVariant() is returned. The meta data is defined when creating the documention file and cannot be modified later. Common meta data includes e.g. the author of the documentation.

### QString QHelpEngineCore::namespaceName ( const QString & documentationFileName ) `[static]`

Returns the namespace name of a documentation set specified by its file name. If the file is not valid, an empty string is returned.

See also documentationFileName().

### bool QHelpEngineCore::registerDocumentation ( const QString & documentationFileName )

Registers the documentation set contained in the file documentationFileName. One documentation set, uniquely identified by its namespace can only be registered once. True is returned if the registration was successful, otherwise false.

See also unregisterDocumentation() and error().

### QStringList QHelpEngineCore::registeredDocumentations () const

Returns a list of all documentations registered in the collection file. The returned names are the namespaces of the documentation sets.

### bool QHelpEngineCore::removeCustomFilter ( const QString & filterName )

Returns true if the filter filterName was removed successfully, otherwise false.

See also addCustomFilter() and customFilters().

### bool QHelpEngineCore::removeCustomValue ( const QString & key )

Removes the key from the settings section in the collection file. Returns true if the value was removed successfully, otherwise false.

See also customValue() and setCustomValue().

### void QHelpEngineCore::setCollectionFile ( const QString & fileName )

Sets the file fileName as the collection file for the help engine. Calling this function will leave the help engine in an invalid state, meaning setupData() or any getter function has to be called in order to setup the help engine again.

See also collectionFile().

### void QHelpEngineCore::setCurrentFilter ( const QString & filterName )

Sets the filter used by the help engine to filterName.

See also currentFilter().

### bool QHelpEngineCore::setCustomValue ( const QString & key, const QVariant & value )

Save the value under the key. If the key already exist, the value will be overwritten. Returns true if the value was saved successfully, otherwise false.

See also customValue() and removeCustomValue().

### bool QHelpEngineCore::setupData ()

Sets up the help engine by processing the information found in the collection file. 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 explicitely, since getter functions which depend on a set up help engine do that themselves. If the set up was successful, true is returned otherwise false.

### void QHelpEngineCore::setupFinished () `[signal]`

This signal is emitted when the setup is complete.

### void QHelpEngineCore::setupStarted () `[signal]`

This signal is emitted when setup is started.

### bool QHelpEngineCore::unregisterDocumentation ( const QString & namespaceName )

Unregisters the documentation set identified by its namespaceName from the help collection. Returns true on success, otherwise false.

See also registerDocumentation() and error().

### void QHelpEngineCore::warning ( const QString & msg ) `[signal]`

This signal is emitted when a non critical error occurs. The warning message is stored in msg.