![]() |
Computer Assited Medical Intervention Tool Kit
version 3.2
|
Action class is an abstract class that enables you to build a action (generally on a component). More...
#include <Action.h>
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... | |
ActionExtension * | extension |
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 Component * | getOutputComponent () |
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... | |
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.
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.
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:
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.
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.
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.
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 |
camitk::Action::Action | ( | ActionExtension * | ) |
Default Constructor: the ActionExtension is needed.
|
virtual |
Destructor.
|
protected |
add a tag to the tags list of this action
|
pure virtualslot |
This method is called when the action has to be applied on the target list (get the target lists using getTargets())
|
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
|
inline |
the name of the component class that can be used by this action
|
inline |
the description of the action
|
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
|
inline |
the name of the family in which this action is associated
|
virtual |
the icon to personalize the action (no icon by default)
|
inline |
get the name of the action
|
virtual |
Returns the output Components in case of only one Component.
|
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);
|
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 |
This method has to be redefined in your Action only if:
In the second case, it is strongly recommanded to have a code similar to this:
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).
|
protectedvirtual |
Set the right output component list so that the method getOutputComponents() can be called.
|
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)?
|
protected |
the name of the component class that can be used by this action
|
protected |
the description of the action
|
protected |
set the embedded property (an action is embedded by default, unless specified otherwise by explicitly calling this method with false)
|
protected |
the name of the family in which this action is associated
|
protected |
set the Pixmap
|
virtual |
Specify the input Components in case of only one Component.
|
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 !!!
|
protected |
set the name of the action class
|
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.
|
protected |
the action widget
|
private |
|
private |
Should the properties/parameters of this action be automatically updated when the user change something in the GUI.
|
private |
the name of the component class that can be used by this action
|
private |
the descriptionof the action
|
private |
the extension in which this action is declared and registered
|
private |
the name of the family in which this action is associated
|
private |
the Action pixmap icon
|
private |
is the widget embedded or not
|
private |
the name of the action
|
private |
List returned by getOutputComponents()
|
private |
the corresponding QAction
|
private |
the name of the tag called this action
|
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