Dev:Action System

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()

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

Terminology:

Value (ValueBase): The ValueBase class can store values of any of the 13 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 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.