CTK  0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
Public Types | Signals | Public Member Functions | List of all members
ctkCmdLineModuleManager Class Reference

Main manager class to handle loading and unloading of modules. More...

#include <Libs/CommandLineModules/Core/ctkCmdLineModuleManager.h>

Inheritance diagram for ctkCmdLineModuleManager:
Inheritance graph
[legend]
Collaboration diagram for ctkCmdLineModuleManager:
Collaboration graph
[legend]

Public Types

enum  ValidationMode { STRICT_VALIDATION , SKIP_VALIDATION , WEAK_VALIDATION }
 

Signals

void moduleRegistered (const ctkCmdLineModuleReference &)
 This signal is emitted whenever a module is registered. More...
 
void moduleUnregistered (const ctkCmdLineModuleReference &)
 This signal is emitted whenever a module is un-registered. More...
 

Public Member Functions

ctkCmdLineModuleBackendbackend (const QString &scheme) const
 Get the registered backend for a scheme. More...
 
QList< ctkCmdLineModuleBackend * > backends () const
 Get a list of all registered backends. More...
 
void clearCache ()
 Clears the XML/timestamp cache. More...
 
 ctkCmdLineModuleManager (ValidationMode validationMode=STRICT_VALIDATION, const QString &cacheDir=QString())
 Create a module manager instance. More...
 
ctkCmdLineModuleReference moduleReference (const QUrl &location) const
 Returns a ctkCmdLineModuleReference object for the given URL. More...
 
QList< ctkCmdLineModuleReferencemoduleReferences () const
 Returns module references for all currently registered modules. More...
 
void registerBackend (ctkCmdLineModuleBackend *backend)
 Registers a new back-end. More...
 
ctkCmdLineModuleReference registerModule (const QUrl &location)
 Registers a module, identified by the given URL. More...
 
ctkCmdLineModuleFuture run (ctkCmdLineModuleFrontend *frontend)
 Run a module front-end. More...
 
void setTimeOutForXMLRetrieval (int timeout)
 Set the timeout for retrieving the XML parameter description from a module. More...
 
void setValidationMode (const ValidationMode &mode)
 Set the validation mode. More...
 
int timeOutForXMLRetrieval () const
 Get the timeout for retrieving the XML parameter description from a module. More...
 
void unregisterModule (const ctkCmdLineModuleReference &moduleRef)
 Unregister a previously registered module. More...
 
ValidationMode validationMode () const
 Get the validation mode. More...
 
 ~ctkCmdLineModuleManager ()
 

Detailed Description

Main manager class to handle loading and unloading of modules.

This is the central managing class for CTK "command line modules". To register modules, you need a command line module back-end which is capable of handling the URL scheme under which you want to register your modules.

A default back-end for handling "file" URLs which runs local executables is available in ctkCmdLineModuleBackendLocalProcess.

To create and run a specific front-end for a given module, you need a concrete ctkCmdLineModuleFrontend implementation. The implementation provided in ctkCmdLineModuleFrontendQtGui creates a default Qt widgets based GUI for a given ctkCmdLineModuleReference instance.

Here is an example how this and related classes could be used:

First, we create ctkCmdLineModuleManager instance.

// Instantiate a ctkCmdLineModuleManager class.
ctkCmdLineModuleManager moduleManager(
// Use "strict" validation mode, rejecting modules with non-valid XML descriptions.
// Use the default cache location for this application
#if (QT_VERSION < QT_VERSION_CHECK(5,0,0))
QDesktopServices::storageLocation(QDesktopServices::CacheLocation)
#else
QStandardPaths::writableLocation(QStandardPaths::CacheLocation)
#endif
);
Main manager class to handle loading and unloading of modules.

Then we need at least one back-end which can handle registering modules.

// Instantiate a back-end for running executable modules in a local process.
// This back-end handles the "file" Url scheme.
QScopedPointer<ctkCmdLineModuleBackend> processBackend(new ctkCmdLineModuleBackendLocalProcess);
// Register the back-end with the module manager.
moduleManager.registerBackend(processBackend.data());
Provides an ctkCmdLineModuleBackend implementation to run a locally installed command line applicatio...

Finally, we can register a module.

try
{
// Register a local executable as a module, the ctkCmdLineModuleBackendLocalProcess
// can handle it.
moduleRef = moduleManager.registerModule(QUrl::fromLocalFile("C:/modules/MyModule.exe"));
}
catch (const ctkInvalidArgumentException& e)
{
// Module validation failed.
qDebug() << e;
return EXIT_FAILURE;
}
Defines a reference or handle to a module, including location, XML, description and access to the ass...
See also
ctkCmdLineModuleFrontend
ctkCmdLineModuleBackend

Definition at line 71 of file ctkCmdLineModuleManager.h.

Member Enumeration Documentation

◆ ValidationMode

Enumerator
STRICT_VALIDATION 

registerModule() will throw an exception if the XML is invalid

SKIP_VALIDATION 

no XML schema validation at all

WEAK_VALIDATION 

registerModule() will validate the XML description but proceed with registration on validation error.

Definition at line 77 of file ctkCmdLineModuleManager.h.

Constructor & Destructor Documentation

◆ ctkCmdLineModuleManager()

ctkCmdLineModuleManager::ctkCmdLineModuleManager ( ValidationMode  validationMode = STRICT_VALIDATION,
const QString &  cacheDir = QString() 
)

Create a module manager instance.

Parameters
validationModeThe validation mode for the XML description of the module parameters.
cacheDirThe directory where to cache information about registered modules.

If the validationMode argument is set to SKIP_VALIDATION, no XML validation takes place and certain front-ends might fail to generate a GUI. If it is set to WEAK_VALIDATION, module registrations will proceed on error but the error status is available via ctkCmdLineModuleReference::xmlValidationErrorString().

◆ ~ctkCmdLineModuleManager()

ctkCmdLineModuleManager::~ctkCmdLineModuleManager ( )

Member Function Documentation

◆ backend()

ctkCmdLineModuleBackend* ctkCmdLineModuleManager::backend ( const QString &  scheme) const

Get the registered backend for a scheme.

Parameters
schemeThe scheme the backend was registered with
Returns
The backend or NULL, if scheme is unknown.

◆ backends()

QList<ctkCmdLineModuleBackend*> ctkCmdLineModuleManager::backends ( ) const

Get a list of all registered backends.

Returns
A list of currently registered backends.

◆ clearCache()

void ctkCmdLineModuleManager::clearCache ( )

Clears the XML/timestamp cache.

◆ moduleReference()

ctkCmdLineModuleReference ctkCmdLineModuleManager::moduleReference ( const QUrl &  location) const

Returns a ctkCmdLineModuleReference object for the given URL.

Parameters
locationThe location URL for which to get a module reference.
Returns
The module reference for the location or an invalid module reference if no module was registered under the given location URL.

◆ moduleReferences()

QList<ctkCmdLineModuleReference> ctkCmdLineModuleManager::moduleReferences ( ) const

Returns module references for all currently registered modules.

Returns
A list of module references.

◆ moduleRegistered

void ctkCmdLineModuleManager::moduleRegistered ( const ctkCmdLineModuleReference )
signal

This signal is emitted whenever a module is registered.

◆ moduleUnregistered

void ctkCmdLineModuleManager::moduleUnregistered ( const ctkCmdLineModuleReference )
signal

This signal is emitted whenever a module is un-registered.

◆ registerBackend()

void ctkCmdLineModuleManager::registerBackend ( ctkCmdLineModuleBackend backend)

Registers a new back-end.

Parameters
backendThe new back-end.
Exceptions
ctkInvalidArgumentExceptionif another back-end was already registered handling one of the URL schemes this back-end claims to handle.

◆ registerModule()

ctkCmdLineModuleReference ctkCmdLineModuleManager::registerModule ( const QUrl &  location)

Registers a module, identified by the given URL.

Parameters
locationThe URL for the new module.
Returns
A module reference.
Exceptions
ctkInvalidArgumentExceptionif no back-end for the given URL scheme was registered or the XML description for the module is invalid.
ctkCmdLineModuleTimeoutExceptionif a time-out occured when retrieving the XML description from the module.
ctkCmdLineModuleRunExceptionif a general error occurred when running the module.

◆ run()

ctkCmdLineModuleFuture ctkCmdLineModuleManager::run ( ctkCmdLineModuleFrontend frontend)

Run a module front-end.

Parameters
frontendThe module front-end to run.
Returns
A ctkCmdLineModuleFuture object which can be used to interact with the running front-end.

This method takes a ctkCmdLineModuleFrontend pointer and uses the registered back-end for this module's location URL scheme to run it asynchronously. The returned future object is the only way to interact with the task started by the specific back-end.

See also
ctkCmdLineModuleFuture
ctkCmdLineModuleFutureWatcher

◆ setTimeOutForXMLRetrieval()

void ctkCmdLineModuleManager::setTimeOutForXMLRetrieval ( int  timeout)

Set the timeout for retrieving the XML parameter description from a module.

The default time-out is 30 seconds.

Parameters
timeoutThe timeout in milli seconds.

◆ setValidationMode()

void ctkCmdLineModuleManager::setValidationMode ( const ValidationMode mode)

Set the validation mode.

◆ timeOutForXMLRetrieval()

int ctkCmdLineModuleManager::timeOutForXMLRetrieval ( ) const

Get the timeout for retrieving the XML parameter description from a module.

Returns
The timeout in milli seconds.

◆ unregisterModule()

void ctkCmdLineModuleManager::unregisterModule ( const ctkCmdLineModuleReference moduleRef)

Unregister a previously registered module.

Parameters
moduleRefThe reference for the module to unregister.

This method does nothing if the module reference moduleRef is invalid or reference an un-registered module.

◆ validationMode()

ValidationMode ctkCmdLineModuleManager::validationMode ( ) const

Get the validation mode.

Returns
The validation mode.

The documentation for this class was generated from the following file: