Base class for all plugins. More...

#include <addInInterface.h>

Inheritance diagram for ito::AddInBase:

Classes
struct	AddInRef
Public Slots
virtual ito::RetVal	init (QVector< ito::ParamBase > paramsMand, QVector< ito::ParamBase > paramsOpt, ItomSharedSemaphore *waitCond=NULL)=0
	method for the initialisation of a new instance of the class (must be overwritten)
virtual ito::RetVal	close (ItomSharedSemaphore *waitCond)=0
	method for closing an instance (must be overwritten)
virtual ito::RetVal	getParam (QSharedPointer< ito::Param > val, ItomSharedSemaphore *waitCond=NULL)=0
	method for the retrieval of a parameter. The actual value is always passed as ito::Param (must be overwritten). See also setParam
virtual ito::RetVal	setParam (QSharedPointer< ito::ParamBase > val, ItomSharedSemaphore *waitCond=NULL)=0
	method to set a parameter. The actual value is always passed as ito::ParamBase (must be overwritten). See also getParam
ito::RetVal	setParamVector (const QVector< QSharedPointer< ito::ParamBase > > values, ItomSharedSemaphore *waitCond=NULL)
	method for setting various parameters (can be used instead of multiple calls to setParam, this can safe multiple invocations)
ito::RetVal	getParamVector (const QVector< QSharedPointer< ito::Param > > values, ItomSharedSemaphore *waitCond=NULL)
	method for getting various parameters (can be used instead of multiple calls to getParam, this can safe multiple invocations)
virtual ito::RetVal	execFunc (const QString funcName, QSharedPointer< QVector< ito::ParamBase > > paramsMand, QSharedPointer< QVector< ito::ParamBase > > paramsOpt, QSharedPointer< QVector< ito::ParamBase > > paramsOut, ItomSharedSemaphore *waitCond=NULL)
	overwrite this function if you registered exec funcs. Once the exec function is called, this method is executed.
ito::RetVal	moveBackToApplicationThread (ItomSharedSemaphore *waitCond=NULL)
	method invoked by AddInManager if the plugin should be pulled back to the main thread of itom. (not for direct use in plugins)
Signals
void	parametersChanged (QMap< QString, ito::Param > params)
	This signal usually is emitted if the vector m_params is changed.
Public Member Functions
const Param	getParamRec (const QString name, bool *nameCheckOk=NULL) const
	method to retrieve a parameter from the parameter map (m_params)
AddInInterfaceBase *	getBasePlugin (void) const
	returns the interface of this instance.
ito::RetVal	MoveToThread (void)
	creates new thread for the class instance and moves this instance to the new thread
const ito::RetVal	getParamList (QMap< QString, Param > **paramNames)
	returns a map with the parameters of this plugin.
const ito::RetVal	getExecFuncList (QMap< QString, ExecFuncParams > **funcs)
	returns list of registered additional functions
int	getID () const
	retrieve the uniqueID of this instance
QString	getIdentifier () const
	retrieve the unique identifier of this instance
virtual int	hasConfDialog (void)
	determine if a configuration dialog is available
virtual const ito::RetVal	showConfDialog (void)
	open configuration dialog
int	createdByGUI () const
	returns true if this instance has firstly been created by the GUI
void	setCreatedByGUI (int value)
	method to set whether this instance has been firstly created by the GUI (true) or by any other component (Python, C++, other plugin,..) (false)
int	getRefCount (void) const
	Returns the reference counter of this instance.
bool	hasDockWidget (void) const
	Returns true if this plugin provides a dock widget, that can be shown in the main window.
QDockWidget *	getDockWidget (void) const
	Returns the reference to the dock widget of this plugin or NULL, if no dock widget is provided.
virtual void	dockWidgetDefaultStyle (bool &floating, bool &visible, Qt::DockWidgetArea &defaultArea) const
	returns default style properties for dock-widget of plugin
int	isAlive (void)
	returns the alive-flag of this plugin
void	setAlive (void)
	sets the alive-flag to 1 ("still alive")
bool	isInitialized (void) const
	returns in a thread-safe way the status of the m_initialized-member variable. This variable should be set to true at the end of the init-method.
void	setInitialized (bool initialized)
	sets in a thread-safe way the status of the m_initialized-member
QVector < ito::AddInBase::AddInRef * > *	getArgAddIns (void)
	returns vector of AddInRef instances.
Protected Member Functions
	AddInBase ()
	Constructor.
virtual	~AddInBase ()
	Destructor.
void	setIdentifier (const QString &identifier)
	sets the identifier of the plugin. The slot AbstractAddInDockWidget::identifierChanged is invoked if a corresponding dock widget is available.
void	createDockWidget (QString title, QDockWidget::DockWidgetFeatures features, Qt::DockWidgetAreas allowedAreas=Qt::AllDockWidgetAreas, QWidget *content=NULL)
	Creates the dock-widget for this plugin.
ito::RetVal	registerExecFunc (const QString funcName, const QVector< ito::Param > &paramsMand, const QVector< ito::Param > &paramsOpt, const QVector< ito::Param > &paramsOut, const QString infoString)
	Registers an additional function with specific name and default parameters.
void	setBasePlugin (AddInInterfaceBase *base)
	sets the interface of this instance to base.
Protected Attributes
QMap< QString, Param >	m_params
	map of the available parameters
QString	m_identifier
	unique identifier (serial number, com-port...)
Private Slots
void	sendParameterRequest ()
	immediately emits the signal parametersChanged
virtual void	dockWidgetVisibilityChanged (bool)
	overwrite this slot if you want to get informed when the dock-widget of the plugin becomes (in)visible
void	dockWidgetDestroyed ()
	call this method, if the dock-widget of the plugin will be deleted.
Private Member Functions
void	incRefCount (void)
	increments reference counter of this plugin (thread-safe)
void	decRefCount (void)
	decrements reference counter of this plugin (thread-safe)
Private Attributes
QThread *	m_pThread
	the instance's thread
AddInInterfaceBase *	m_pBasePlugin
	the AddInInterfaceBase instance of this plugin
int	m_refCount
	reference counter, used to avoid early deletes (0 means that one instance is holding one reference, 1 that two participants hold the reference...)
int	m_createdByGUI
	1 if this instance has firstly been created by GUI, 0: this instance has been created by c++ or python
QVector < ito::AddInBase::AddInRef * >	m_hwDecList
	list of hardware that was passed to the plugin on initialisation and whose refcounter was incremented
QMap< QString, ExecFuncParams >	m_execFuncList
	map with registered additional functions. funcExec-name -> (default mandParams, default optParams, default outParams, infoString)
int	m_uniqueID
	uniqueID (automatically given by constructor of AddInBase with auto-incremented value)
QMutex	m_refCountMutex
	mutex for making the reference counting mechanism thread-safe.
QDockWidget *	m_dockWidget
	instance-pointer to the dock-widget of the plugin or NULL if no dock-widget instatiated in constructor of plugin
int	m_alive
	member to check if thread is still responsive
QMutex	m_atomicMutex
	mutex for protecting atomic getter and setter methods (e.g. alive and initialized)
bool	m_initialized
	true: init-method has been returned with any RetVal, false (default): init-method has not been finished yet
Static Private Attributes
static int	m_instCounter = 0
Friends
class	AddInInterfaceBase
	AddInBase is friend with AddInInterfaceBase, such that the interface can access methods like the protected constructor or destructor of this plugin class.

Detailed Description

Base class for all plugins.

The common methods and members are defined here. The available plugin type (actuator AddInActuator, dataIO AddInDataIO and algo AddInAlgo) are derived from this class. At the main program startup all available plugins located in the plugin directory are searched and matched against the current plugin interface version. Then all compatible plugins can be check with the AddInManager. Up to that stage for each plugin only a lightweight AddInInterface AddInInterfaceBase class has been loaded. To use a plugin instances of the plugin class have to be instantiated. The AddInInterface is run in the calling thread whilst the plugin classes are run in separate threads. Therefore the plugin functions are implemented as slots which can be used e.g. with the invokeMethod function. The base functionality included in this base class is getting the plugin's parameter list, getting the classes uniqueID (which is used e.g. for saveing the parameter values) and optinally to bring up a configuration dialog.

Constructor & Destructor Documentation

ito::AddInBase::AddInBase ( ) [protected]

Constructor.

This constructor is called by any constructor of classes AddInActuator, AddInDataIO or AddInAlgo. Please make sure to call these constructors in your plugin constructor, since this is not automatically be done (due to the single parameter of the constructor).

This constructor simply initializes several member variables of this class.

Parameters:

[in] uniqueID is the unique identifier of this plugin instance. This identifier can be changed in the constructor or finally at the beginning of in the init-method. Afterwards it is used by different organizers and GUI components.

ito::AddInBase::~AddInBase ( ) [protected, virtual]

Destructor.

This destructor is automatically called if any plugin instance is destroyed. It does the following steps:

Deletes the dock widget if available.
Clears the internal parameter-vector.
If the plugin instance is executed in its own thread, this thread is stopped and finally deleted.

Member Function Documentation

void ito::AddInBase::dockWidgetDestroyed ( ) [inline, private, slot]

call this method, if the dock-widget of the plugin will be deleted.

The member variable m_dockWidget will be set to NULL.

See also:: m_dockWidget

virtual void ito::AddInBase::dockWidgetVisibilityChanged ( bool ) [inline, private, virtual, slot]

overwrite this slot if you want to get informed when the dock-widget of the plugin becomes (in)visible

It is recommended to use this method, in order to connect the widget to signals like parametersChanged, actuatorStatusChanged or targetChanged (both actuator only) if the dock-widget becomes visible and disconnect them if it is hidden. This is useful in order to avoid intense function calls if the dock-widget is not visible.

See also:: parametersChanged

ito::RetVal ito::AddInBase::execFunc	(	const QString	funcName,
		QSharedPointer< QVector< ito::ParamBase > >	paramsMand,
		QSharedPointer< QVector< ito::ParamBase > >	paramsOpt,
		QSharedPointer< QVector< ito::ParamBase > >	paramsOut,
		ItomSharedSemaphore *	waitCond = `NULL`
	)		`[virtual, slot]`

overwrite this function if you registered exec funcs. Once the exec function is called, this method is executed.

this method can handle additional functions of your plugin.

Use registerExecFunc to register a specific function name and a set of mandatory and optional default parameters. It one on those functions is called (for instance by a python-call), this method is executed. Implement a switch case for the function name and start the execution. The mandatory and optional parameters are handled like it is the case for the creation (init-method) of a plugin. Additionally define an optional vector of output parameters, that are finally filled with a valid input during the execution of the function.

Parameters:

funcName	is the function name
paramsMand	is the vector of mandatory parameters for the specific function name
paramsOpt	is the vector of optional parameters for the specific function name
paramsOut	is the vector of parameters (must have flag OUT, not IN), that are the return value(s) of the specific function call
waitCond	is the semaphore in order guarantee, that the caller of this method waits until the function has been executed.

See also:: registerExecFunc, init

AddInInterfaceBase* ito::AddInBase::getBasePlugin ( void ) const [inline]

returns the interface of this instance.

See also:: AddInInterfaceBase

const Param ito::AddInBase::getParamRec	(	const QString	name,
		bool *	nameCheckOk = `NULL`
	)		const

method to retrieve a parameter from the parameter map (m_params)

returns parameter from m_params vector. If the parameter could not be found or if the given name is invalid an invalid Param is returned. If you provide the nameCheckOk-pointer, you will return a boolean value describing whether your name matched the possible regular expression.

The parameter name, that is search can have the following form:

Name (where Name consists of numbers, characters (a-z) or the symbols _-)
Name[Idx] (where Idx is a fixed-point number
Name[Idx]:suffix (where suffix is any string - suffix is ignored by this method)
Name:suffix

until now, the Idx is ignored by this method.

Parameters:

name	is the name of the parameter
nameCheckOk	returns true if name corresponds to the necessary syntax, else false

Returns:: Param as copy of the internal m_params-map or empty Param, if name could not be resolved or found

ito::RetVal ito::AddInBase::getParamVector	(	const QVector< QSharedPointer< ito::Param > >	values,
		ItomSharedSemaphore *	waitCond = `NULL`
	)		`[slot]`

method for getting various parameters (can be used instead of multiple calls to getParam, this can safe multiple invocations)

method for setting various parameters in a sequence

Using this method, only one over-thread call needs to be executed in order to set various parameters by calling setParam for each parameter.

Parameters:

values	is a vector of parameters to set
waitCond	is the locked semaphore that is released at the end of the method.

See also:: setParam, ParamBase

int ito::AddInBase::hasConfDialog ( void ) [virtual]

determine if a configuration dialog is available

method indicates whether this plugin instance has a configuration dialog.

Overwrite this method if your plugin provides such a configuration dialog by simply returning 1 instead of 0.

Returns:: 0 since the base implementation of a plugin does not have a configuration dialog. If there is a configuration dialog overwrite this method and return 1.

ito::RetVal ito::AddInBase::moveBackToApplicationThread ( ItomSharedSemaphore * waitCond = NULL ) [slot]

method invoked by AddInManager if the plugin should be pulled back to the main thread of itom. (not for direct use in plugins)

method invoked by AddInManager if the plugin should be pulled back to the main thread of itom.

Do not invoke this method in any other case. It should only be invoked by AddInManager of the itom core. After having moved the thread to the main thread of itom, the plugin's thread m_pThread can be closed and deleted. However this cannot be done in this method, since a thread can only be killed and closed by another thread. Therefore, this is done in the destructor of the AddIn.

Qt does not allow pushing an object from the object's thread to the caller's thread. Only the object itself can move its thread to another thread.

void ito::AddInBase::parametersChanged ( QMap< QString, ito::Param > params ) [signal]

This signal usually is emitted if the vector m_params is changed.

Emit this signal for instance in setParam if the parameter has been changed in order to inform connected dock-widgets... about the change. This signal is also emitted if you invoke the slot sendParameterRequest.

Parameters:

params is the parameter-vector to send (usually m_params)

See also:: m_params, sendParameterRequest

void ito::AddInBase::sendParameterRequest ( ) [inline, private, slot]

immediately emits the signal parametersChanged

call or invoke this method for instance after creating a configuration dialog for the plugin. Then the dialog gets the current parameter map m_params, if it has been connected to the signal parametersChanged (must be done before).

See also:: parametersChanged, m_params

void ito::AddInBase::setBasePlugin ( AddInInterfaceBase * base ) [inline, protected]

sets the interface of this instance to base.

See also:: AddInInterfaceBase

ito::RetVal ito::AddInBase::setParamVector	(	const QVector< QSharedPointer< ito::ParamBase > >	values,
		ItomSharedSemaphore *	waitCond = `NULL`
	)		`[slot]`

method for setting various parameters (can be used instead of multiple calls to setParam, this can safe multiple invocations)

method for setting various parameters in a sequence

Using this method, only one over-thread call needs to be executed in order to set various parameters by calling setParam for each parameter.

Parameters:

values	is a vector of parameters to set
waitCond	is the locked semaphore that is released at the end of the method.

See also:: setParam, ParamBase

const ito::RetVal ito::AddInBase::showConfDialog ( void ) [virtual]

open configuration dialog

method called if the configuration dialog of the plugin should be shown.

Overwrite this method if your plugin provides a configuration dialog. This method is directly called by the main (GUI) thread. Therefore you can directly show your configuration dialog, connect it with signals and slots of your plugin instance (which possibly is executed in another thread), wait for any commands or that the dialog is closed and handle the result.

Returns:: retWarning since you have to overwrite this method in order to show your configuration dialog.

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

D:/git-itom/sources/itom/common/addInInterface.h
D:/git-itom/sources/itom/common/sources/addInInterface.cpp

Classes

Public Slots

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Private Slots

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation