Qtilities::CoreGui::HelpManager Class Reference

A help manager which provides functionality to help developers integrate the Qt Help System into their applications. More...

#include <HelpManager.h>

List of all members.

Signals
void	forwardRequestUrlDisplay (const QUrl &url, bool ensure_visible=true)
	Signal used to forward help display requests to any help browsers connected to the help manager.
void	homePageChanged (const QUrl &url)
	Home page changed signal.
void	registeredFilesChanged (const QStringList &files)
	Signal which is emitted when the files registered in the engine is changed.

Public Member Functions
void	clearRegisteredFiles (bool initialize_after_change=true)
	Register files in the help engine.
QHelpEngine *	helpEngine ()
	Returns a help engine to use in your application.
QUrl	homePage () const
	Gets the home page of your application.
void	initialize ()
	Initializes the help engine.
void	readSettings (bool initialize_after_change=true)
	Reads the help settings.
QStringList	registeredFiles () const
	Gets the registered files in the help engine.
void	registerFile (const QString &file, bool initialize_after_change=true)
	Registers a file in the help engine.
void	registerFiles (const QStringList &files, bool initialize_after_change=true)
	Register files in the help engine.
void	requestUrlDisplay (const QUrl &url, bool ensure_visible=true)
	Request a help page to be shown in any help browsers connected to the help manager.
void	setHomePage (const QUrl &home_page)
	Sets the home page of your application.
void	unregisterFile (const QString &file, bool initialize_after_change=true)
	Unregisters a file in the help engine.
void	unregisterFiles (const QStringList &files, bool initialize_after_change=true)
	Unregister files in the help engine.
void	writeSettings ()
	Writes the help settings.

Static Public Member Functions
static QString	formatFileName (const QString &file_name)
	Formats file names into the format used by the help manager.

---

Detailed Description

A help manager which provides functionality to help developers integrate the Qt Help System into their applications.

The help manager allows you to integrate the Qt Help System into your applications. You can access the help manager using the HELP_MANAGER macro directly, or through Qtilities::CoreGui::QtilitiesApplication::helpManager().

The helpEngine() function provides a QHelpEngine which you can use throughout your application. To use it is simple, you need to register all qch files that you want to use using either registerFile() or registerFiles() and then initialize the plugin. For example:

// We register two example files. The false parameter indicates that we don't want the registerFile()
// function to initialize the manager after the changes made to it.
HELP_MANAGER->registerFile("myFile1.qch",false);
HELP_MANAGER->registerFile("myFile2.qch",false);
HELP_MANAGER->initialize();

// Now that it was initialized we can use the helpEngine().
HELP_MANAGER->helpEngine();

When initializing the help manager, two tasks will be created:

• One task for setting up the help manager.
• One task for indexing the documentation.

Both these task will be registered in the global object pool for you, thus it will show up in your Qtilities::CoreGui::TaskSummaryWidget widgets. After initialization you can change the files you want to show through registerFile(), registerFiles(), clearRegisteredFiles(), unregisterFile() and unregisterFiles(). After you have registered and unregistered the files you want, you can call initialize() again which will set up and index the help system for the registered files found through registeredFiles().

When registering files from the Qt Resource System the help manager will automatically create temporary local copies of the files to register, thus you don't need to worry about that.

The Qtilities::Plugins::Help plugin provides a ready to use GUI frontend for the help system which allows you to view the contents of all help files, view an index or search the documentation:

Help Plugin Showing GUI Frontend For The Help Manager

When using the Qtilities extension system, you can easily let plugins register help files providing help for their functionality. The important thing to remember is to register the files in the initializeDependencies() function of your plugin implementation. For example:

bool MyPlugins::initializeDependencies(QStringList *error_strings) {
    HELP_MANAGER->registerFile(":/MyPlugin/plugin_help.qch",false);
}

In time, the API of the help manager will be extended to allow deeper integration with applications.

This class was added in Qtilities v1.1.

---

Member Function Documentation

void HelpManager::clearRegisteredFiles

(

bool

initialize_after_change = true

)

Register files in the help engine.

Note:

Registered files will only be saved between sessions when QtilitiesCoreApplication::qtilitiesSettingsEnabled() is enabled.

QHelpEngine * HelpManager::helpEngine

(

)

Returns a help engine to use in your application.

Make sure you call initialize() before using the help engine since the help engine is constructed in initialize().

void Qtilities::CoreGui::HelpManager::homePageChanged ( const QUrl &  url )

signal

Home page changed signal.

This signal was added in Qtilities v1.3.

void HelpManager::initialize

(

)

Initializes the help engine.

Initialize will set up the internal help engine and start indexing of all documentation registered in the manager.

QStringList HelpManager::registeredFiles

(

)

const

Gets the registered files in the help engine.

Note:

Registered files will only be saved between sessions when QtilitiesCoreApplication::qtilitiesSettingsEnabled() is enabled.

void HelpManager::registerFile	(	const QString &	file,
		bool	initialize_after_change = true
	)

Registers a file in the help engine.

Note:

Registered files will only be saved between sessions when QtilitiesCoreApplication::qtilitiesSettingsEnabled() is enabled.

void HelpManager::registerFiles	(	const QStringList &	files,
		bool	initialize_after_change = true
	)

Register files in the help engine.

Note:

Registered files will only be saved between sessions when QtilitiesCoreApplication::qtilitiesSettingsEnabled() is enabled.

void HelpManager::requestUrlDisplay	(	const QUrl &	url,
		bool	ensure_visible = true
	)

Request a help page to be shown in any help browsers connected to the help manager.

When the Qtilities help plugin is loaded in your application, this function will load the requested page in the help plugin and if ensure_visible is true, the application will switch to the help mode provided by the help plugin.

void HelpManager::unregisterFile	(	const QString &	file,
		bool	initialize_after_change = true
	)

Unregisters a file in the help engine.

Note:

Registered files will only be saved between sessions when QtilitiesCoreApplication::qtilitiesSettingsEnabled() is enabled.

void HelpManager::unregisterFiles	(	const QStringList &	files,
		bool	initialize_after_change = true
	)

Unregister files in the help engine.

Note:

Registered files will only be saved between sessions when QtilitiesCoreApplication::qtilitiesSettingsEnabled() is enabled.