Computer Assited Medical Intervention Tool Kit  version 3.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Public Types | Public Slots | Public Member Functions | Private Attributes | List of all members
camitk::Action Class Referenceabstract

Action class is an abstract class that enables you to build a action (generally on a component). More...

#include <Action.h>

+ Inheritance diagram for camitk::Action:

Public Types

enum  ApplyStatus {
  SUCCESS, ERROR, WARNING, ABORTED,
  TRIGGERED
}
 describes what happened during the application of an algorithm (i.e. results of the apply method) More...
 

Public Slots

virtual ApplyStatus apply ()=0
 This method is called when the action has to be applied on the target list (get the target lists using getTargets()) More...
 
ApplyStatus trigger (QWidget *parent=NULL)
 This method triggers the action. More...
 

Public Member Functions

 Action (ActionExtension *)
 Default Constructor: the ActionExtension is needed. More...
 
bool getAutoUpdateProperties () const
 auto update properties More...
 
void setAutoUpdateProperties (bool)
 are the properties to be udpated every time the user makes a change in the widget (default is false)? More...
 
virtual ~Action ()
 Destructor. More...
 
Generic action getters

These methods can not be redefined in subclasses.

QAction * getQAction ()
 Get the corresponding QAction. More...
 
QString getName () const
 get the name of the action More...
 
QString getDescription () const
 the description of the action More...
 
QString getComponent () const
 the name of the component class that can be used by this action More...
 
QString getFamily () const
 the name of the family in which this action is associated More...
 
QString getExtensionName () const
 the name of the extension in the family in which this action is associated More...
 
QStringList getTag () const
 the name of the tag called this action More...
 
bool getEmbedded () const
 argument use to know if the widget is embedded or not More...
 
Method specific to an action.
virtual QWidget * getWidget ()
 This method has to be redefined in your Action only if: More...
 
virtual QPixmap getIcon ()
 the icon to personalize the action (no icon by default) More...
 
const ComponentList getTargets () const
 the currently selected and valid (regarding the component property) components, for which this action is called More...
 

Private Attributes

bool autoUpdateProperties
 Should the properties/parameters of this action be automatically updated when the user change something in the GUI. More...
 
QString component
 the name of the component class that can be used by this action More...
 
QString description
 the descriptionof the action More...
 
ActionExtensionextension
 the extension in which this action is declared and registered More...
 
QString family
 the name of the family in which this action is associated More...
 
QPixmap icon
 the Action pixmap icon More...
 
bool isEmbedded
 is the widget embedded or not More...
 
QString name
 the name of the action More...
 
QAction * qAction
 the corresponding QAction More...
 
QStringList tags
 the name of the tag called this action More...
 
ComponentList targetComponents
 The list of valid (regarding the component property) components for which this action is called. More...
 

Pipeline execuction of the Action

List of alive component before the application of the action (to be compared withe the list after and deduce outputComponents.

ComponentList aliveBeforeComponents
 
ComponentList outputComponents
 List returned by getOutputComponents() More...
 
virtual ApplyStatus applyInPipeline ()
 This method encapsulates the apply() method. More...
 
virtual void setInputComponents (ComponentList inputs)
 Specify the input Component(s) Only applyInPipeline() should be called with this method (maybe apply), but not trigger() as its first intruction is to clear the target components list !!! More...
 
virtual void setInputComponent (Component *input)
 Specify the input Components in case of only one Component. More...
 
virtual ComponentList getOutputComponents ()
 Returns the output Component(s) More...
 
virtual ComponentgetOutputComponent ()
 Returns the output Components in case of only one Component. More...
 
virtual void preProcessInPipeline ()
 Selects the right component(s) (the one that has been set by setInputComponents() ), so that the apply method uses the right component(s) through getTargets(). More...
 
virtual void postProcessInPipeline ()
 Set the right output component list so that the method getOutputComponents() can be called. More...
 

Generic action attributes setters

These methods can not be redefined in subclasses but have to used to ensure name/description unicity among CamiTK.

QWidget * actionWidget
 the action widget More...
 
void setName (QString name)
 
void setDescription (QString description)
 the description of the action More...
 
void setComponent (QString component)
 the name of the component class that can be used by this action More...
 
void setFamily (QString family)
 the name of the family in which this action is associated More...
 
void addTag (QString tag)
 add a tag to the tags list of this action More...
 
void setEmbedded (bool isEmbedded)
 set the embedded property (an action is embedded by default, unless specified otherwise by explicitly calling this method with false) More...
 
void setIcon (QPixmap)
 set the Pixmap More...
 

Detailed Description

Action class is an abstract class that enables you to build a action (generally on a component).

At least two classes have to be reimplemented to enable the action: ActionExtension + Action

This is the list of attributes you need to consider when creating a new action

An Action has a corresponding QAction, see getQAction(), that makes it easy to trigger an action from any Qt GUI (menus, toolbar, push buttons...)

If the component class is defined (non empty string), an Action is applied on the currently selected components. If there are no component defined (i.e. you specifies setComponent("")), it means that your action does not need any inputs.

Two steps have to be considered when using an action:

The targets can have changed between the time the action is first triggered and the time the action is applied. getWidget() is always called when the targets are updated. Therefore whenever getWidget() is called, you should make sure to update the the action GUI consequently. getTargets() is always updated in trigger() and available.

Note
trigger() and apply() are public slots. They can be called either directly (classic C++ method invocation) or by connecting them to a QWidget signal.

When an action is triggered (e.g., by right clicking in the context menu), the following algorithm applies, see trigger():

This means that, if there is a widget, the action algorithm is controlled by the action widget, i.e. apply() is not called by trigger() but should be called by one of the action widget's button.

An Action generally is used to wrap an algorithm in CamiTK. If this algorithm has parameters, it is very easy to get these parameters accessible to the user through the ActionWidget. These parameters are in fact defined as Qt dynamic properties.

By default an action has a widget, instance of ActionWidget. If ActionWidget does not correspond to what you need, just create a new class inheriting from QWidget, or even better, inheriting from ActionWidget.

These are the use cases for using the default behaviour (i.e. an instance of ActionWidget):

ActionWidget should be good enough in most of the cases. The default widget contains a description, a reminder of the current target component names, and an applyable/revertable ObjectController that allows you to edit/modify properties.

Note
The recommanded architecture is for the action widget to call the action's apply method. The widget should only manage user interaction.

Here are some notes about the rest of the properties:

extensionName is automatically given during the action registration in the ActionExtension.

The component property determines on which type of component your action can be applied. Generic actions are action that have an empty component name. Therefore generic actions can be called to generate/synthetize data or initialize resources.

You can add any number of tags using the method addTag().

If ActionWidget is not what your need, a typical getWidget() method should use the lazy instanciation pattern to instanciate MyVerySpecialActionWidget the first time it is called, and call the MyVerySpecialActionWidget instance's updateTargets() method for any subsequent calls. Something like:

QWidget *MyAction::getWidget() {
// build or update the widget
if (!myWidget)
myWidget = new MyVerySpecialActionWidget(this);
else
// MyVerySpecialActionWidget should have a updateTargets() method
myWidget->updateTargets();
return myWidget;
}

But of course you can also use any kind of widget you like. ActionWidget is just defining a default widget for an action. If your action does not have any GUI/parameters, just override the getWidget() method in order to return NULL.

By default the properties/parameters are not automatically updated when the user change the default widget, they are updated only when the user click on the apply button of the default widget. Use setAutoUpdateProperties(true) to automatically update the action's properties.

Note
if you use your own MyVerySpecialActionWidget class, make sure it conforms to this behaviour (you can get the desired behaviour by calling getAutoUpdateProperty()

By default the action's widget is embedded. If you do not want to embed your action's widget, use setEmbedded(false) in the constructor. When embedded, the parent widget has to be given at triggered time. If there is no parent given for an embedded action, then the action is embedded in the ActionViewer by default.

The method apply() must be implemented in your Action.

Note
at any moment, the selected components on which the action needs to be applied are available by getTargets(). targetComponents is filtered so that it only contains compatible components (i.e., instances of getComponent()).

The method applyInPipeline() performs some pre- and post-processing around the method apply(). It has to be used within a pipeline (a chain of actions) where setInputComponents() and getOutputComponents() are needed. preProcessInPipeline() only selects the right components, and postProcess() sets output components and record history.

See Also
RenderingOption For a simple example of an embedded action
RigidTransform For a simple example of a non-embedded action
ChangeColor For a simple example of an action with no widget (but with a GUI)

Member Enumeration Documentation

describes what happened during the application of an algorithm (i.e. results of the apply method)

Enumerator
SUCCESS 

everything went according to plan

ERROR 

apply() failed : an error occured (usually it means that the apply() was interrupted)

WARNING 

some (partial) error occured during the application of the algorithm

ABORTED 

the action was aborted before completion

TRIGGERED 

the action was triggered only, but not applied

Constructor & Destructor Documentation

camitk::Action::Action ( ActionExtension )

Default Constructor: the ActionExtension is needed.

virtual camitk::Action::~Action ( )
virtual

Destructor.

Member Function Documentation

void camitk::Action::addTag ( QString  tag)
protected

add a tag to the tags list of this action

virtual ApplyStatus camitk::Action::apply ( )
pure virtualslot

This method is called when the action has to be applied on the target list (get the target lists using getTargets())

Note
it should never be empty!
Returns
status of the apply method
virtual ApplyStatus camitk::Action::applyInPipeline ( )
virtual

This method encapsulates the apply() method.

It has to be called within a pipeline (a chain of actions), where a script or another programm calls setInputComponents() and/or getOutputComponents. It is not needed in the case of graphical interface which trigger the Action's widget and applies the action on selected components. When there is no GUI, preProcessInPipeline() and postProcessInPipeline() methods select the right component(s). As the method apply() is called between preProcessInPipeline() and postProcessInPipeline(), the returned value is the returned value of apply().

bool camitk::Action::getAutoUpdateProperties ( ) const

auto update properties

QString camitk::Action::getComponent ( ) const
inline

the name of the component class that can be used by this action

QString camitk::Action::getDescription ( ) const
inline

the description of the action

bool camitk::Action::getEmbedded ( ) const
inline

argument use to know if the widget is embedded or not

QString camitk::Action::getExtensionName ( ) const

the name of the extension in the family in which this action is associated

QString camitk::Action::getFamily ( ) const
inline

the name of the family in which this action is associated

virtual QPixmap camitk::Action::getIcon ( )
virtual

the icon to personalize the action (no icon by default)

QString camitk::Action::getName ( ) const
inline

get the name of the action

virtual Component* camitk::Action::getOutputComponent ( )
virtual

Returns the output Components in case of only one Component.

virtual ComponentList camitk::Action::getOutputComponents ( )
virtual

Returns the output Component(s)

QAction* camitk::Action::getQAction ( )

Get the corresponding QAction.

The corresponding QAction has its triggered() signal connected to the trigger() slot of the action. It shares the action icon (as the QAction's icon) and name (as the QAction's text). It also use the descriptions of the action for the tooltip/whatsThis text.

To add a shortcut, simply call getQAction()->setShortcut(..) in the action constructor. To make this shortcut available for any windows of the application, call getQAction()->setShortcutContext(Qt::ApplicationShortcut);

QStringList camitk::Action::getTag ( ) const
inline

the name of the tag called this action

const ComponentList camitk::Action::getTargets ( ) const

the currently selected and valid (regarding the component property) components, for which this action is called

virtual QWidget* camitk::Action::getWidget ( )
virtual

This method has to be redefined in your Action only if:

  • you do not have any widget to control your action (i.e. getWidget() will have to return NULL),
  • you do not use the default ActionWidget but another one.

In the second case, it is strongly recommanded to have a code similar to this:

QWidget *MyAction::getWidget() {
// build or update the widget
if (!myWidget)
myWidget = new MyVerySpecialActionWidget(this);
else
// MyVerySpecialActionWidget should have a updateTargets() method
myWidget->updateTargets();
return myWidget;
}

The updateTargets method in MyVerySpecialActionWidget is used in case the selection has changed since the last time the widget was shown (a change in the selection often means an updateTargets of the action's widget fields).

virtual void camitk::Action::postProcessInPipeline ( )
protectedvirtual

Set the right output component list so that the method getOutputComponents() can be called.

virtual void camitk::Action::preProcessInPipeline ( )
protectedvirtual

Selects the right component(s) (the one that has been set by setInputComponents() ), so that the apply method uses the right component(s) through getTargets().

If setInputComponents where not called, does not select any component.

void camitk::Action::setAutoUpdateProperties ( bool  )

are the properties to be udpated every time the user makes a change in the widget (default is false)?

void camitk::Action::setComponent ( QString  component)
protected

the name of the component class that can be used by this action

void camitk::Action::setDescription ( QString  description)
protected

the description of the action

void camitk::Action::setEmbedded ( bool  isEmbedded)
protected

set the embedded property (an action is embedded by default, unless specified otherwise by explicitly calling this method with false)

void camitk::Action::setFamily ( QString  family)
protected

the name of the family in which this action is associated

void camitk::Action::setIcon ( QPixmap  )
protected

set the Pixmap

virtual void camitk::Action::setInputComponent ( Component input)
virtual

Specify the input Components in case of only one Component.

virtual void camitk::Action::setInputComponents ( ComponentList  inputs)
virtual

Specify the input Component(s) Only applyInPipeline() should be called with this method (maybe apply), but not trigger() as its first intruction is to clear the target components list !!!

void camitk::Action::setName ( QString  name)
protected

set the name of the action class

ApplyStatus camitk::Action::trigger ( QWidget *  parent = NULL)
slot

This method triggers the action.

The parent widget is used if the action is embedded, see class description for more information about the algorithm. This method cannot be redefined in inherited class.

Member Data Documentation

QWidget* camitk::Action::actionWidget
protected

the action widget

ComponentList camitk::Action::aliveBeforeComponents
private
bool camitk::Action::autoUpdateProperties
private

Should the properties/parameters of this action be automatically updated when the user change something in the GUI.

QString camitk::Action::component
private

the name of the component class that can be used by this action

QString camitk::Action::description
private

the descriptionof the action

ActionExtension* camitk::Action::extension
private

the extension in which this action is declared and registered

QString camitk::Action::family
private

the name of the family in which this action is associated

QPixmap camitk::Action::icon
private

the Action pixmap icon

bool camitk::Action::isEmbedded
private

is the widget embedded or not

QString camitk::Action::name
private

the name of the action

ComponentList camitk::Action::outputComponents
private

List returned by getOutputComponents()

QAction* camitk::Action::qAction
private

the corresponding QAction

QStringList camitk::Action::tags
private

the name of the tag called this action

ComponentList camitk::Action::targetComponents
private

The list of valid (regarding the component property) components for which this action is called.

This list is private (use getTargets() in subclasses). This list may by filled


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