PluginManager Class Reference

Singleton responsible for tracking all operation factories in the application. More...

#include <Workspace/Application/pluginmanager.h>

Public Types
enum	InitOption { SkipLoadingWidgets = 0x01 , LazyDllLoad = 0x02 , DefaultOptions = 0 }

Public Member Functions
	~PluginManager ()
bool	addPlugin (WorkspacePlugin &plugin)
HelpImplementation *	getHelpImplementation ()
int	getNumPlugins () const
WorkspacePlugin *	getPlugin (const QString &name)
const WorkspacePlugin *	getPlugin (const QString &name) const
WorkspacePlugin *	getPlugin (int i)
const WorkspacePlugin *	getPlugin (int i) const
QList< const DataExecution::DataFactory * >	getRegisteredDataFactories (bool aggregateSharedFactories=true) const
QList< const DataExecution::OperationFactory * >	getRegisteredOperationFactories () const
QList< const Widgets::WidgetFactory * >	getRegisteredWidgetFactories () const
QList< const DataExecution::DataFactory * >	getSharedDataFactories (const DataExecution::DataFactory *) const
void	notifyWorkspaceClosed ()
void	setHelpImplementation (HelpImplementation *helpImpl)

Static Public Member Functions
static PluginManager &	createInstance (InitOptions options)
static PluginManager &	getInstance ()

Detailed Description

Every operation, data or widget factory the application uses must be registered with this manager. The manager does not own the factories, it just provides a central place to provide information about all known factories. Every plugin should call addFactory() for each of the operation, data or widget factories it provides. The manager singleton can be obtained using getInstance().

When the PluginManager singleton is constructed, it will attempt to find and auto-load Workspace plugins according to the policy specified by Settings::getPluginAutoLoadPolicy(). For those plugins it is allowed to auto-load, PluginManager will call the plugin's setup() function and if that returns true, the plugin will remain loaded. For each plugin successfully loaded, the PluginManager will also augment certain resource search paths, such as for custom widget .ui files, style sheets, etc. In order to take advantage of this resource path augmentation, it is strongly recommended that plugin developers use the following directory structure, where the Install directory is some base directory below which all files are located:

  Install/bin
  Install/lib
  Install/lib/Plugins
  Install/appdata/MyPlugin
  Install/doc/MyPlugin
  Install/include/MyPlugin
  Install/styles/MyPlugin
  Install/widgets/MyPlugin

The various paths ending in MyPlugin show where to put plugin-specific files. The plugin library itself should be in Install/lib/Plugins. It would also be customary to put executables in Install/lib and put a launcher for it in Install/bin instead of putting the executable directly in the Install/bin directory. The launcher would then have the opportunity to set environment variables, etc. before running the executable and the CMake build system that comes with the workspace has direct support for creating these launchers for you automatically using the launcher_for_executable() CMake function.

The PluginManager constructor looks in the following locations (in the order shown) when searching for plugins to auto-load:

• The internal built-in plugin is always loaded first, regardless of the auto-loading policy.
• Any permitted plugin library found in the lib/Plugins directory below the path returned from Settings::getInstallBasePath(). This directory is not searched recursively.
• Any text files in the installArea found in the directory specified in the WORKSPACE_INSTALL_AREAS environment variable, if present. These directories are not searched recursively.
• Any directories or paths to plugins as returned by Settings::getPluginPaths(). Directories are not searched recursively.

Note that if the plugin auto-load policy is set to AutoLoadAllPluginsExceptExcluded , some of the above locations from the above sequence may not be permissible search paths. Also, once a plugin is loaded successfully, if a plugin with the same name is found later in the search sequence, the later one(s) are ignored.

Member Enumeration Documentation

InitOption

enum InitOption

Enumerator
SkipLoadingWidgets
LazyDllLoad
DefaultOptions

Constructor & Destructor Documentation

~PluginManager()

~PluginManager ( )

default

Member Function Documentation

addPlugin()

bool addPlugin

(

WorkspacePlugin &

plugin

)

Parameters

plugin

A plugin instance to add to the plugin manager.

When providing a plugin to the plugin manager with this function, the caller is responsible for ensuring that the library associated with the plugin remains loaded as long as it is needed (typically the lifetime of the application).

It is assumed that plugin's setup() has not been called. Therefore, addPlugin() will call setup() before adding it to the internal list of plugins.

Returns

True if the plugin manager did not already have plugin loaded and if the setup() function for plugin was successful.

createInstance()

PluginManager & createInstance ( InitOptions  options )

static

Parameters

options

Initialisation options for the PluginManager instance

Returns

Reference to the instance of the plugin manager.

Identical to getInstance(), but will provide options for initialisation.

getHelpImplementation()

HelpImplementation * getHelpImplementation

(

)

Returns

The current help implementation, or a null pointer if no implementation has been set.

This function may be called directly by plugin code to show help to the user, but it is often more convenient to use the various WorkspacePlugin::showHelp() functions (they call getHelpImplementation() internally).

See also

getHelpImplementation(), HelpPlugin

getInstance()

PluginManager & getInstance ( )

static

getNumPlugins()

int getNumPlugins

(

)

const

Returns

The number of plugins currently loaded by the plugin manager.

getPlugin() [1/4]

WorkspacePlugin * getPlugin

(

const QString &

name

)

Parameters

name	The plugin name to find. Note that this is not the file name of the plugin library, but rather the name as returned by WorkspacePlugin::getName().

Returns

A pointer to the plugin with the specified name, or a null pointer if no plugin has been loaded with the specified name.

getPlugin() [2/4]

const WorkspacePlugin * getPlugin

(

const QString &

name

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getPlugin() [3/4]

WorkspacePlugin * getPlugin

(

int

i

)

Parameters

i	Index of the plugin to retrieve.

Returns

The plugin at index i. No check is made to ensure that i is a valid index.

getPlugin() [4/4]

const WorkspacePlugin * getPlugin

(

int

i

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

getRegisteredDataFactories()

QList< const DataExecution::DataFactory * > getRegisteredDataFactories

(

bool

aggregateSharedFactories = true

)

const

Parameters

aggregateSharedFactories

Whether or not to aggregate shared DataFactories by only returning main shared DataFactories in the list.

Returns

a list containing all data factories registered with any plugins that have been loaded by the plugin manager.

getRegisteredOperationFactories()

QList< const DataExecution::OperationFactory * > getRegisteredOperationFactories

(

)

const

Returns

a list containing all operation factories registered with any plugins that have been loaded by the plugin manager.

getRegisteredWidgetFactories()

QList< const Widgets::WidgetFactory * > getRegisteredWidgetFactories

(

)

const

Returns

a list containing all widget factories registered with any plugins that have been loaded by the plugin manager.

getSharedDataFactories()

QList< const DataExecution::DataFactory * > getSharedDataFactories

(

const DataExecution::DataFactory *

dataFactory

)

const

Returns

a list containing all data factories that is shared with a given data factory.

notifyWorkspaceClosed()

void notifyWorkspaceClosed

(

)

Notifies the plugin manager that a Workspace has closed. The manager can then notify each of its plugins of this fact, and they can then take appropriate action, if any.

setHelpImplementation()

void setHelpImplementation

(

HelpImplementation *

helpImpl

)

Parameters

helpImpl

The new help implementation. This can also be a null pointer to clear the current help implementation.

If there is already a help implementation when this function is called and helpImpl is not that implementation, then deregistering() will be called on the old implementation before replacing it.

See also

getHelpImplementation(), HelpPlugin