Tools Specification

All tools are specified in roughly the same way. Like most elements inside the VSM, they have an Id and a Label. For elements which will appear to the end-user (in the palette or in menus), make sure the Label is meaningful to them.

Tools Applicability. Most tools apply to a set of Mappings, sometimes only on certain kinds of mappings (e.g. Container Drop description only makes sense for container mappings). For tools which create new elements, the Mappings correspond to the kinds of elements the tool will create. For other tools, it corresponds to the kinds of element the tool can be applied to.

Many tools also support the notion of Extra Mappings. If these are specified, they indicate other kinds of elements than the primary ones on which the tool can be applied.

The Precondition of a tool definition can be used to restrict its applicability to only some instances of the Mappings (and Extra Mappings) associated with the tool. When the user tries to invoke the tool on an element, the expression will be evaluated in the context of that element' semantic target, and the tool will be applicable only if the expression returns true. Otherwise the user will have a feedback (typically a change in the mouse cursor’s shape) to indicate the tool can not be applied on this element.

Force Refresh. Tools have a Force Refresh flag. As most tools only perform a local change in the underlying model, by default Sirius will try to optimize its refresh operation (which synchronizes the graphical view with the state of the underlying semantic model) by only refreshing elements of the mappings explicitly associated with the tool. If you know your tool will have side-effects which can change other parts of the diagram, set the Force Refresh flag to force Sirius to perform a complete refresh of the whole diagram after the tool is executed. This ensures a perfect synchronization of the graphical representation with the state of the underlying model, possibly at the cost of performance and reactivity on big diagrams.

Selection after tool execution. The Elements to select and Inverse Selection Order flags can be used to defined what is selected in the active editor after tool execution.
By default, only the top level created elements are selected.

Tools' Body and Variables. The actual effect of a tool is defined inside its body, which is usually represented by a Begin element (the starting point of the tool’s execution). You can use any of the available model operations to specify the behavior of your tools, including, if necessary, operations which invoke complex algorithms written in Java. Inside the tools’body, you have access to variables, which are specific to each kind of tools and give you all the necessary information on how the tool was invoked, on which elements, etc. How you access these variables from the expressions inside the tool’s body depend on the query language you use for the expressions.

Static Variables. The static variables defined by each tool are visible directly inside the tool’s element in the VSM. The exact set of variables available will depend on each tool, but typically you will have access to both semantic variables which reference semantic elements and view variables which reference graphical elements. As an example, in a Node Creation Tool, you have both a container and a containerView variable. containerView will point to the graphical element on which the user invoked the node creation tool (for example a container view) while container will point to that view’s target semantic element. Usually the tools use only the semantic variables, but you may want to use the view variables if the same semantic elements can be represented in different ways on your diagram and you want your tool to behave differently depending on which of these representations the user targeted.

User-Defined Variables. In addition to the static variables which are pre-defined by Sirius for each kind of tool, you can define your own, which will also be available inside the tool’s body. These user variables are defined as sub-elements of the static variables using the New Variable... context menu. There are two kinds:

Tool Filters. Tool filters can be specified inside a tool to hide a tool in the diagram palette depending on dynamic conditions. The Elements To Listen is evaluated in the context of the diagram’s semantic element, and should return a set of semantic elements. The Precondition is re-evaluated on each of these elements whenever a change occurs.