Dev:Action System - Revision history

Want at 15:55, 16 March 2017

2017-03-16T15:55:46Z

D.j.a.y: /* Properties of an Action */ add info about get_param _added during merge #102_

2015-12-16T23:21:13Z

‎Properties of an Action: add info about get_param _added during merge #102_

D.j.a.y: terminology

2014-04-25T21:27:29Z

terminology

Nikitakit: Formatting

2010-11-03T21:11:58Z

Formatting

Nikitakit: Make page more coherent

2010-10-11T18:39:04Z

Make page more coherent

Nikitakit: Some infor on value/valuenode/valuedesc

2010-09-08T21:32:37Z

Some infor on value/valuenode/valuedesc

Nikitakit: More writing

2010-09-08T18:53:30Z

More writing

Nikitakit: More documentation

2010-09-08T01:52:24Z

Nikitakit: Initial notes

2010-09-07T20:25:44Z

Initial notes

New page

This page is a work-in-progress documentation of the action system.
At the moment there are only some brief notes.

Types of actions

*Inherit from Super
**can only call other actions
**implement a prepare() method to create sub-actions

*Inherit from Undoable and CanvasSpecific
**implement perform() and undo()

*Get_Param_Vocab
** Get the parent param vocab "ParamVocab ret(Action::CanvasSpecific::get_param_vocab());"
** Then add parameters to it e.g. " ret.push_back(ParamDesc("new_value",Param::TYPE_VALUE).set_local_name(_("ValueBase")));"

← Older revision		Revision as of 15:55, 16 March 2017
Line 1:		Line 1:
		+	{{Title\|Action System}}
	The action system provides a good entry-point into Synfig because it functions as a stand-alone component that only interacts with Synfig's core data structure. This page is intended to provide a quick overview of the structure of the action system.		The action system provides a good entry-point into Synfig because it functions as a stand-alone component that only interacts with Synfig's core data structure. This page is intended to provide a quick overview of the structure of the action system.

← Older revision		Revision as of 23:21, 16 December 2015
Line 61:		Line 61:
	* Check that the required parameters for CanvasSpecific actions are met "return Action::CanvasSpecific::is_ready();"		* Check that the required parameters for CanvasSpecific actions are met "return Action::CanvasSpecific::is_ready();"

		+	===get_param(const synfig::String& name, Action::Param &param)===

		+	Typical implementation:
		+	* Set the value of the parameter from the action point of vue
		+
		+	The action is used in action like renameValueNode / renameLayer ... all case when a previous value was present.
		+	To use get_param you will need Action::set_value_provided() property during the parameter description in {{l\|Dev:Action_System#get_param_vocab()\|get_param_vocab()}} implemenation.

	==Types of actions==		==Types of actions==

@@ Line 15: / Line 15: @@
 ===ValueDesc===
-Instances of this class describe a ''location'' where a ValueNode may be rather than that ValueNode itself. For example, they can refer to "the 'amount' parameter of layer x" or "the 5th point in the bline". That way, the ValueDesc continues to function even if the underlying value has been changed, exported, converted, etc.
+Instances of this class describe a ''location'' where a ValueNode may be rather than that ValueNode itself. For example, they can refer to "the 'amount' parameter of layer x" or "the 5th point in the spline (bline)". That way, the ValueDesc continues to function even if the underlying value has been changed, exported, converted, etc.
 Actions typically receive ValueDescs to operate on, only retrieving their values when they are necessary for computations.
@@ Line 21: / Line 21: @@
 ==Properties of an Action==
-The majority of actions are accessible by right-clicking on certain ducks, parameters, or layers. At that point, Synfig Studio automatically determines which actions can be called based on the data that is currently selected.
+The majority of actions are accessible by right-clicking on certain handle (ducks), parameters, or layers. At that point, Synfig Studio automatically determines which actions can be called based on the data that is currently selected.
 The first step is for the action to provide a "Parameter Vocabulary" object that describes what types of parameters it needs in order to function.

@@ Line 1: / Line 1: @@
-This page is a work-in-progress documentation of the action system.
+The action system provides a good entry-point into Synfig because it functions as a stand-alone component that only interacts with Synfig's core data structure. This page is intended to provide a quick overview of the structure of the action system.
-At the moment there are only some brief notes.
-The action system, for the most part, interacts only with document data structure. As such, it is important to understand what this structure is consists of.
+==Data Structures==
-Value (ValueBase): The ValueBase class can store values of any of the 13 {{l|Dev:Types|Types}}. As such, using Values requires one to check the type of the given object (by calling value.get_type()) and to know the value type before fetching its contents (e.g. value.get(Real())).
+The action system interacts with the underlying data structure of a Synfig document. An action is most likely to affect the parameters of a given layer or object, which are described by the following classes.
-ValueNode: A {{l|ValueNode}} is a value that changes with time. Calling value_node(time) retrieves the value at that given time.
+===Value (ValueBase)===
-ValueDesc: Instances of this class describe a ''location'' where a ValueNode may be rather than that ValueNode itself. (For example "the 'amount' parameter of layer x" or "the 5th point in the bline"). That way, the ValueDesc consistently refers to the same location even if the underlying value has been changed, exported, converted, etc.
+===ValueNode===
-Actions typically receive ValueDescs to operate on and will only retrieve the actual value at that point if necessary
+Actions typically receive ValueDescs to operate on, only retrieving their values when they are necessary for computations.
 ==Properties of an Action==
-The majority of actions are accessible by right-clicking on certain ducks, parameters, or layers. At that point, Synfig Studio automatically determines which actions can be called based on the data that is currently selected. The first step is for the action to provide a "Parameter Vocabulary" object that describes what types of parameters it needs in order to function.
+The majority of actions are accessible by right-clicking on certain ducks, parameters, or layers. At that point, Synfig Studio automatically determines which actions can be called based on the data that is currently selected.
-get_param_vocab()
+The first step is for the action to provide a "Parameter Vocabulary" object that describes what types of parameters it needs in order to function.
 Typical implementation:
@@ Line 33: / Line 38: @@
 However, the parameter types alone are not always sufficient to determine whether the action should be called. As such, checking a given parameter set is done by the action:
-is_candidate(const ParamList &x)
+===is_candidate(const ParamList &x)===
 Typical implementation:
 * The first step of any candidate check is to test whether the requirements of the ParamDesc are met. "if (!candidate_check(get_param_vocab(), x)) return false;"
 * At this point, you know that all of your parameters are present and can begin testing for specific cases. (For example, the "activepointsetoff" action is only applicable when the activepoint is currently on)
-* If there are no tests to perform, simply return true.
+* If there are no tests to perform, return "true".
-Once the parameter list is checked, Synfig Studio will pass the actual parameters to the action. The action must then retrieve their values and store them internally. This internal storage allows for the action to be un-done and re-done multiple times.\
+Once the parameter list is checked, Synfig Studio will pass the actual parameters to the action. The action must then retrieve their values and store them internally. This internal storage allows for the action to be un-done and re-done multiple times.
-set_param(const synfig::String& name, const Action::Param &param)
+===set_param(const synfig::String& name, const Action::Param &param)===
 Typical implementation:
@@ Line 50: / Line 55: @@
 The action needs to be able to check whether all of its parameters are set. While the parameter list is checked when the action is called as a result of a right-click menu, any actions called from other places (e.g. by other actions) manually set parameters and must check that the proper parameters are present.
-is_ready()
+===is_ready()===
 Typical implementation:
@@ Line 62: / Line 67: @@
 There are two major types of actions.
 The first are standard undoable actions
 *These inherit from [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1Undoable.html Undoable] and [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1CanvasSpecific.html CanvasSpecific]
 *It is necessary to implement perform() and undo()
 The second are Super-actions which can only call other actions. Since undoing a Super-action is simply undoing all of its sub-actions, these do not require an undo method.
 *Inherit from [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1Super.html Super]
 *perform() and undo() are inherited from Super and should not be overridden.
-Sub-actions are added by:
+To add sub-actions:
-* First create the action of the needed type "Action::Handle action(Action::create("ValueDescSet"));" or "ValueDescConnect::create()" (TODO: Style review here)
+* First create the action of the needed type e.g. "Action::Handle action(Action::create("ValueDescSet"));" or "ValueDescConnect::create()" (TODO: Style review here)
-* Set it's parameters:
+* Set its parameters:
-**The canvas, canvas interface, and current time are usually simply passed on to children
+**The canvas, canvas interface, and current time of the current action are usually passed on to children
 ***action->set_param("canvas",get_canvas());
 ***action->set_param("canvas_interface",get_canvas_interface());
@@ Line 82: / Line 89: @@
 ***action->set_param("value_desc",reference_value_desc);
 ***action->set_param("new_value",value);

@@ Line 2: / Line 2: @@
 At the moment there are only some brief notes.
-Types of actions
+The action system, for the most part, interacts only with document data structure. As such, it is important to understand what this structure is consists of.
-*Inherit from [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1Super.html Super]
+Value (ValueBase): The ValueBase class can store values of any of the 13 {{l|Dev:Types|Types}}. As such, using Values requires one to check the type of the given object (by calling value.get_type()) and to know the value type before fetching its contents (e.g. value.get(Real())).
-**can only call other actions
-**implement a prepare() method to create sub-actions
-*Inherit from [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1Undoable.html Undoable] and [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1CanvasSpecific.html CanvasSpecific]
+ValueDesc: Instances of this class describe a ''location'' where a ValueNode may be rather than that ValueNode itself. (For example "the 'amount' parameter of layer x" or "the 5th point in the bline"). That way, the ValueDesc consistently refers to the same location even if the underlying value has been changed, exported, converted, etc.
-**implement perform() and undo()
-get_param_vocab()
+Actions typically receive ValueDescs to operate on and will only retrieve the actual value at that point if necessary
-Each action must be able to supply a "Parameter Vocabulary" object. This object specifies what parameters the action requires and what type they need to be.
+==Properties of an Action==
 * Get the param vocab from the parent action. In most cases, it will be "ParamVocab ret(Action::CanvasSpecific::get_param_vocab());"
-* Create a parameter description for each of the parameters(see [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1ParamDesc.html ParamDesc])
+* Create a parameter description for each of the parameters your action needs(see [http://download.tuxfamily.org/synfig/api/synfig-studio/classsynfigapp_1_1Action_1_1ParamDesc.html ParamDesc])
 ** ParamDesc("new_value",Param::TYPE_VALUE)
 ** Set the parameter options e.g. "ParamDesc(...).set_local_name(_("ValueBase"))"
 ** The set actions all return the object, so you should chain them: ParamDesc(...).set_local_name(...).set_supports_multiple(...)
-* Once the parameters are set, they should be added to the Parameter Vocabulary e.g. "ret.push_back(ParamDesc("new_value",Param::TYPE_VALUE).set_local_name(_("ValueBase")));"
+* Once the parameters are set, add them to the Parameter Vocabulary e.g. "ret.push_back(ParamDesc("new_value",Param::TYPE_VALUE).set_local_name(_("ValueBase")));"
-is_candidate(const ParamList &x)
+However, the parameter types alone are not always sufficient to determine whether the action should be called. As such, checking a given parameter set is done by the action:
-Any time the user selects some object (be it a duck, parameter, layer, etc) and right-clicks, she is offered a context menu containing all applicable actions. Synfig checks for candidates by passing them a list of parameters and asking if they are acceptable.
+is_candidate(const ParamList &x)
 * The first step of any candidate check is to test whether the requirements of the ParamDesc are met. "if (!candidate_check(get_param_vocab(), x)) return false;"
 * At this point, you know that all of your parameters are present and can begin testing for specific cases. (For example, the "activepointsetoff" action is only applicable when the activepoint is currently on)
 * If there are no tests to perform, simply return true.
 set_param(const synfig::String& name, const Action::Param &param)
-When passed a parameter, the action must be able to determine if it is the right type and, if so, set an internal variable that stores the value of the parameter. All action parameters are stored in variables so that they can be accessed again if the action is undone or has been undone and now should be performed again.
+Typical implementation:
 is_ready()
-This method should check that all internal variables needed have been properly initialized. This test is performed before any action is called to ensure that it has all of its variables set and can be executed safely.
+Typical implementation:
-(Only applies to actions inheriting from Super). The prepare function should create sub-actions that need to be performed and call "add_action" or "add_action_front" on them. There is no need to manually implement perform() and undo(), as these will be done automatically by either performing all of the sub-actions or undoing them.
+==Types of actions==
-Actions are added by:
+There are two major types of actions.
 * First create the action of the needed type "Action::Handle action(Action::create("ValueDescSet"));" or "ValueDescConnect::create()" (TODO: Style review here)
@@ Line 61: / Line 82: @@
 ***action->set_param("value_desc",reference_value_desc);
 ***action->set_param("new_value",value);

← Older revision		Revision as of 21:32, 8 September 2010
Line 62:		Line 62:
	***action->set_param("new_value",value);		***action->set_param("new_value",value);

		+	Terminology:

−	~~TODO~~: ~~explain valuebase, valuenodes, valuedesc~~, and the ~~differences between them~~	+	Value (ValueBase): The ValueBase class can store values of any of the 13 {{l\|Dev:Types\|Types}}. Actions involved in setting a value typically require an object of this type for a parameter. Since a given instance of ValueBase may in fact store objects of different types, it is important to check the type (by calling value.get_type()) and then get the value in the proper type (e.g. value.get(Real()))
		+
		+	ValueNode: A {{l\|ValueNode}} is a value that changes with time.
		+
		+	ValueDesc: Instances of this class describe a ''location'' where a ValueNode may be rather than that ValueNode itself. (For example "the 'amount' parameter of layer x" or "the 5th point in the bline"). That way, the ValueDesc consistently refers to the same location even if the underlying value has been changed, exported, converted, etc.

← Older revision		Revision as of 18:53, 8 September 2010
Line 34:		Line 34:
	* At this point, you know that all of your parameters are present and can begin testing for specific cases. (For example, the "activepointsetoff" action is only applicable when the activepoint is currently on)		* At this point, you know that all of your parameters are present and can begin testing for specific cases. (For example, the "activepointsetoff" action is only applicable when the activepoint is currently on)
	* If there are no tests to perform, simply return true.		* If there are no tests to perform, simply return true.
		+
		+
		+	set_param(const synfig::String& name, const Action::Param &param)
		+
		+	When passed a parameter, the action must be able to determine if it is the right type and, if so, set an internal variable that stores the value of the parameter. All action parameters are stored in variables so that they can be accessed again if the action is undone or has been undone and now should be performed again.
		+
		+
		+	is_ready()
		+
		+	This method should check that all internal variables needed have been properly initialized. This test is performed before any action is called to ensure that it has all of its variables set and can be executed safely.
		+
		+
		+	prepare()
		+
		+	(Only applies to actions inheriting from Super). The prepare function should create sub-actions that need to be performed and call "add_action" or "add_action_front" on them. There is no need to manually implement perform() and undo(), as these will be done automatically by either performing all of the sub-actions or undoing them.
		+
		+	Actions are added by:
		+
		+	* First create the action of the needed type "Action::Handle action(Action::create("ValueDescSet"));" or "ValueDescConnect::create()" (TODO: Style review here)
		+	* Set it's parameters:
		+	**The canvas, canvas interface, and current time are usually simply passed on to children
		+	***action->set_param("canvas",get_canvas());
		+	***action->set_param("canvas_interface",get_canvas_interface());
		+	***action->set_param("time",time);
		+	**Other parameters will vary from action to action. For ValueDescSet they might be:
		+	***action->set_param("value_desc",reference_value_desc);
		+	***action->set_param("new_value",value);
		+
		+
		+	TODO: explain valuebase, valuenodes, valuedesc, and the differences between them