Difference between revisions of "Dev:Action System"

From Synfig Studio :: Documentation
Jump to: navigation, search
(More documentation)
(More writing)
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

Revision as of 20:53, 8 September 2010

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



get_param_vocab()

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.

  • 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 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")));"


is_candidate(const ParamList &x)

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.

  • 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.


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