Qtilities::ExtensionSystem::ExtensionSystemCore Class Reference

The ExtensionSystemCore class is the core of the Qtilities extension system library. More...

#include <ExtensionSystemCore.h>

List of all members.

Public Slots
void	handlePluginConfigurationChange (QList< QObject * > active_plugins, QList< QObject * > inactive_plugins)
	Handle plugin configuration changes.

Signals
void	newProgressMessage (const QString &message)
	Progress messages submitted during application startup.
void	pluginLoadingCompleted ()
	Signal which is emitted when the plugin loading completed.
void	pluginLoadingStarted ()
	Signal which is emitted when the plugin loading started.
void	pluginPathsChanged (const QStringList &plugin_paths)
	Signal which is emitted when the plugin paths changed.

Public Member Functions
QString	activePluginConfigurationFile () const
	Gets the name of the current plugin configuration set's file.
QStringList	activePlugins () const
	Function to return the names of all plugins that are loaded and initialized at present.
void	addPluginPath (const QString &path)
	Function to add a custom plugin path.
QWidget *	configWidget ()
	Returns a widget with information about loaded plugins.
QStringList	corePlugins () const
	Function to return the names of all core plugins.
void	disablePluginActivityControl ()
	Disables plugin activity control in the plugin details widget.
void	disablePluginActivityDisplay ()
	Disables plugin activity display in the plugin details widget.
void	enablePluginActivityControl ()
	Disables plugin activity control in the plugin details widget.
void	enablePluginActivityDisplay ()
	Disables plugin activity display in the plugin details widget.
QStringList	filteredPlugins () const
	Function to return the file names of all plugins which as not loaded during the initialize() function call.
QStringList	filteredPluginsCurrentSet () const
	Function to return the filter expression of the current plugin configuration set.
void	finalize ()
	Finalizes the plugin manager by unloading and finalizing all plugins.
Interfaces::IPlugin *	findPlugin (const QString &plugin_name) const
	Function which finds the plugin with the given plugin_name and returns its plugin interface. If no plugin exists with that name in the set of loaded plugins (active and inactive plugins), null is returned.
QStringList	inactivePlugins () const
	Function to return the names of all plugins that are loaded but not initialized at present.
QStringList	inactivePluginsCurrentSet () const
	Function to return the filter expression of the current plugin configuration set.
void	initialize ()
	Initializes the plugin manager by loading all found plugins.
bool	isPluginActivityControlEnabled () const
	Indicates if plugin activity can be changed by the user in the plugin details widget.
bool	isPluginActivityDisplayEnabled () const
	Indicates if plugin activity is displayed in the plugin details widget.
bool	loadPluginConfiguration (QString file_name=QString(), QStringList *inactive_plugins=0, QStringList *filtered_plugins=0)
	Function which loads a plugin configuration file.
QStringList	pluginPaths () const
	Function to get the paths from where plugins are loaded.
bool	savePluginConfiguration (QString file_name=QString(), QStringList *inactive_plugins=0, QStringList *filtered_plugins=0, Qtilities::ExportVersion version=Qtilities::Qtilities_Latest, QString *errorMsg=0) const
	Function which saves a plugin configuration file for the given parameters.
void	setActivePluginConfigurationFile (const QString &file_name)
	Sets the name of the current plugin configuration set's file.
void	setCorePlugins (QStringList core_plugins)
	Function to set the names of all plugins which should be handled as core plugins. That is, they cannot be made inactive by an user.
void	setFilteredPlugins (QStringList filtered_plugins)
	Function to set the file names of all plugins which should not be loaded during the initialize() function call.
void	setInactivePlugins (QStringList inactive_plugins)
	Function to set the names of all plugins that is loaded but not initialized at present.

---

Detailed Description

The ExtensionSystemCore class is the core of the Qtilities extension system library.

The extension system core class is a singleton which is used to load plugins.

See the Extension System article for more information about the Qtilities extension system.

---

Member Function Documentation

QString Qtilities::ExtensionSystem::ExtensionSystemCore::activePluginConfigurationFile

(

)

const

Gets the name of the current plugin configuration set's file.

When loadPluginConfiguration() is loaded with a valid file, this function will return the file name that was loaded. Otherwise it will return "App_Path/plugins/default" + qti_def_SUFFIX_PLUGIN_CONFIG.

QStringList Qtilities::ExtensionSystem::ExtensionSystemCore::activePlugins

(

)

const

Function to return the names of all plugins that are loaded and initialized at present.

Note:

This function only provides usefull information after initialize() have been called.

See also:

activePlugins()

void Qtilities::ExtensionSystem::ExtensionSystemCore::addPluginPath

(

const QString &

path

)

Function to add a custom plugin path.

By default plugins are loaded only from the /plugins folder in the application directory. Using this function it is possible to add as many paths as you wish to the plugin loading process.

In order for path to be added it must exist and it should not exist as a custom plugin path yet.

Note:

Add all the needed paths before calling loadPlugins().

See also:

pluginPaths(), pluginPathsChanged()

QStringList Qtilities::ExtensionSystem::ExtensionSystemCore::corePlugins

(

)

const

Function to return the names of all core plugins.

See also:

setCorePlugins()

QStringList Qtilities::ExtensionSystem::ExtensionSystemCore::filteredPlugins

(

)

const

Function to return the file names of all plugins which as not loaded during the initialize() function call.

See also:

setFilteredPlugins()

void Qtilities::ExtensionSystem::ExtensionSystemCore::finalize

(

)

Finalizes the plugin manager by unloading and finalizing all plugins.

Will call finalize on all plugins in the order that they were loaded. Thus the order can be random.

QStringList Qtilities::ExtensionSystem::ExtensionSystemCore::inactivePlugins

(

)

const

Function to return the names of all plugins that are loaded but not initialized at present.

Note:

This function only provides usefull information after initialize() have been called.

See also:

inactivePlugins()

void Qtilities::ExtensionSystem::ExtensionSystemCore::initialize

(

)

Initializes the plugin manager by loading all found plugins.

Will load all plugins in the specified plugin paths. Once an IPlugin interface is discovered, initialize() will be called on it. When all the plugins in the system are loaded, the initializeDependencies() funciton will be called on each plugin.

When enablePluginActivityControl() is true, the initialize() function will attempt to load the default plugin configuration set in the file specified by activePluginConfigurationFile(). If you want to load a file other than the default configuration file you can set it using setActivePluginConfigurationFile() before calling initialize().

It is important to note that the IPlugin implementations loaded through initialize() should live in the same thread as the extension system core instance. Thus you should not move your plugin to a different thread during its lifetime.

See also:

pluginPaths()

bool Qtilities::ExtensionSystem::ExtensionSystemCore::isPluginActivityControlEnabled

(

)

const

Indicates if plugin activity can be changed by the user in the plugin details widget.

False by default.

Note:

isPluginActivityDisplayEnabled() must also be true for the activity control to be available, thus if plugin activity display is not yet enabled, this function call will enabled it.

See also:

enablePluginActivityControl(), disablePluginActivityControl(), setInactivePlugins()

bool Qtilities::ExtensionSystem::ExtensionSystemCore::isPluginActivityDisplayEnabled

(

)

const

Indicates if plugin activity is displayed in the plugin details widget.

False by default.

See also:

enablePluginActivityDisplay(), disablePluginActivityDisplay(), setInactivePlugins()

bool Qtilities::ExtensionSystem::ExtensionSystemCore::loadPluginConfiguration	(	QString	file_name = QString(),
		QStringList *	inactive_plugins = 0,
		QStringList *	filtered_plugins = 0
	)

Function which loads a plugin configuration file.

Loads a plugin configuration from a file. Before initialization the function can be called with inactive_plugins = 0 and filtered_plugins = 0 in order to load the plugin configuration to be used in initialize(). After initialization you must pass proper values for inactive_plugins and filtered_plugins in order for the function to work. False will be returned when this requirement is not met. The reason for this is that the extension system's configuration set cannot be changed again after initialization since the plugins would have been loaded at that time.

Parameters:

file_name	When empty the file name in activePluginConfigurationFile() will be used. When empty the default plugin configuration file is used. The default plugin file is located at QtilitiesApplication::applicationSessionPath()/Plugins/default.pconfig. For more information, see Qtilities::CoreGui::QtilitiesApplication::applicationSessionPath().
inactive_plugins	The QStringList to be populated with the inactive plugin names found in the input file. When null, the inactive plugins in the extension system's active plugin configuration will be set. See setInactivePlugins() for more information.
filtered_plugins	The QStringList to be populated with the plugin filter expressions found in the input file. When null, the filtered plugins in the extension system's active plugin configuration will be set. See setFilteredPlugins() for more information.

See also:

savePluginConfiguration()

void Qtilities::ExtensionSystem::ExtensionSystemCore::pluginLoadingCompleted ( )

signal

Signal which is emitted when the plugin loading completed.

This class was added in Qtilities v1.1.

void Qtilities::ExtensionSystem::ExtensionSystemCore::pluginLoadingStarted ( )

signal

Signal which is emitted when the plugin loading started.

This class was added in Qtilities v1.1.

QStringList Qtilities::ExtensionSystem::ExtensionSystemCore::pluginPaths

(

)

const

Function to get the paths from where plugins are loaded.

See also:

addPluginPath(), pluginPathsChanged()

void Qtilities::ExtensionSystem::ExtensionSystemCore::pluginPathsChanged ( const QStringList &  plugin_paths )

signal

Signal which is emitted when the plugin paths changed.

This class was added in Qtilities v1.3.

bool Qtilities::ExtensionSystem::ExtensionSystemCore::savePluginConfiguration	(	QString	file_name = QString(),
		QStringList *	inactive_plugins = 0,
		QStringList *	filtered_plugins = 0,
		Qtilities::ExportVersion	version = Qtilities::Qtilities_Latest,
		QString *	errorMsg = 0
	)		const

Function which saves a plugin configuration file for the given parameters.

Parameters:

file_name	When empty the file name in activePluginConfigurationFile() will be used. When empty the default plugin configuration file is used. The default plugin file is located at QtilitiesApplication::applicationSessionPath()/Plugins/default.pconfig. For more information, see Qtilities::CoreGui::QtilitiesApplication::applicationSessionPath().
inactive_plugins	The list of plugins which must be inactive plugins in the saved configuration file. When null, extension system's active plugin configuration's inactive plugins will be used. See inactivePlugins() for more information.
filtered_plugins	The list of plugin filter expressions which must be used the saved configuration file. When null, extension system's active plugin configuration's filtered plugins will be used. See filteredPlugins() for more information.

See also:

loadPluginConfiguration()

void Qtilities::ExtensionSystem::ExtensionSystemCore::setCorePlugins

(

QStringList

core_plugins

)

Function to set the names of all plugins which should be handled as core plugins. That is, they cannot be made inactive by an user.

Sets a list of plugin names which corresponds to the IPlugin::pluginName() implementation of the plugins which should be handled as core plugins. Note that the setInactivePlugins() function checks that you don't set a core plugin as inactive but the setFilteredPlugins() function does not do that. Thus it is possible to filter a core plugin. The developer must make sure this does not happen.

Note:

This function only does something usefull when called before initialize().

Below is an example of how you can verify that all core plugins loaded successfully:

QStringList core_plugins;
core_plugins << "Project Management Plugin";
EXTENSION_SYSTEM->setCorePlugins(core_plugins);
EXTENSION_SYSTEM->initialize();

// Give error message if any of the core plugins were not found:
bool core_plugins_ok = true;
QStringList missing_plugins;
foreach (QString core_plugin, core_plugins) {
    if (!EXTENSION_SYSTEM->activePlugins().contains(core_plugin)) {
        core_plugins_ok = false;
        missing_plugins << core_plugin;
    }
}

if (!core_plugins_ok) {
    QMessageBox msgBox;
    msgBox.setIcon(QMessageBox::Critical);
    msgBox.setWindowTitle("All Core Plugins Not Found");
    msgBox.setText("All core plugins could not be loaded properly. Everything might not work as expected.<br><br>The following core plugin(s) were not found: <br><br>" + missing_plugins.join("<br>") + "<br><br>The following plugin(s) were loaded and set active: <br><br>" + EXTENSION_SYSTEM->activePlugins().join("<br>"));
    msgBox.exec();
}

void Qtilities::ExtensionSystem::ExtensionSystemCore::setFilteredPlugins

(

QStringList

filtered_plugins

)

Function to set the file names of all plugins which should not be loaded during the initialize() function call.

Sets a list of wildcard mode regular expressions which will be evaluated during initialize(). Each plugin file that is found will be checked against this wildcard mode regular expression and if it matches the expression, it will not be loaded. See QRegExp::Wildcard for more information.

Note:

This function only does something usefull when called before initialize().

void Qtilities::ExtensionSystem::ExtensionSystemCore::setInactivePlugins

(

QStringList

inactive_plugins

)

Function to set the names of all plugins that is loaded but not initialized at present.

Sets a list of plugin names which corresponds to the IPlugin::pluginName() implementation of the plugins which should be inactive on startup.

Note:

This function only does something usefull when called before initialize().