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.