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. The refresh will be effective only on the current diagram and not on all opened 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.

• Elements to select: Expression to list the elements to select after tool execution. There are four possibilities for the list of elements returned by this expression. In any case, if the default list of elements is not empty, the list of elements returned is filtered with the default selected elements. In case of creation tool, the default list contains newly created elements so, the returned list can contain at most that elements. For specific cases, this constraint can be removed by setting to false the system property org.eclipse.sirius.ui.enableCreatedElementsConstraintInSelectElementsListener.
  • Empty expression: The default behavior is applied: if graphical elements has been created, these elements will be selected(excluding the sub elements), else, the selection is unchanged.
  • List of DRepresentationElement: All this graphical elements will be selected after the execution of the tool.
  • List of semantic elements: All EObject that are not a DRepresentationElement are considered as semantic elements. All graphical elements corresponding to these semantic elements will be selected after the execution of the tool.
  • Empty list: Nothing is selected after the execution of the tool.
  • List with only the DRepresentation: It will be considered as empty list.
  • List with a mix of DRepresentationElement and non DRepresentationElement is forbidden. A such list will be considered as empty list.
• Inverse Selection Order : By default, false, the elements are selected in the order of the list or the default list if existing. It is possible to inverse this order by setting this property to true. To be more precise, the meaning of this property depends on the value of elementsToSelectExpression:
  • List of DRepresentationElement: The elements are selected in order of the list (first element is selected in first, second element is selected in second, and so on). The last graphical element of the list will be the primary selection. If inverseSelectionOrder is true, the order is reverted.
  • List of semantic elements: The elements are selected in order of the list (the graphical element corresponding to the first semantic element is selected in first, the graphical element corresponding to second semantic element is selected in second, and so on). And if several graphical elements correspond to the same semantic element, they are selected on their default order. The last element is the primary selection. If inverseSelectionOrder is true, the order is reverted (the order of the list AND the order of several graphical elements corresponding to the same semantic element).
  • Empty list or list with only the DRepresentation: The inverseSelectionOrder is ignored in this context.

Some services exist natively in Sirius and can be used to contribute new select all actions for diagram. These services are all in the class org.eclipse.sirius.diagram.ui.tools.api.interpreter.StandardDiagramServices:

• stdGetViewsRepresentingSameEType(DSemanticDiagram, List<DSemanticDecorator>): Return the list of DSemanticDecorator representing semantic element with same EType as the current selected diagram elements.
• stdGetViewsWithSameMapping(DSemanticDiagram, List<DSemanticDecorator>): Return the list of DSemanticDecorator having the same mappings as the current selected diagram elements.
• stdGetViewsRepresentingSelectedType(DSemanticDiagram): Return the list of DSemanticDecorator in the current diagram representing semantic element having the EType provided by the end-user through a dialog box. This dialog box can be improved. There is currently no completion, neither validation.
• stdGetViewsOfExpression(DSemanticDiagram): Return the list of DSemanticDecorator corresponding to the evaluation of an expression written by the end-user in a dialog box. This dialog box can be improved. There is currently no completion, neither validation.

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:

• Expression Variables have a name and a Computation Expression. When the tool is invoked, the computation expression will be evaluated in the context or the parent variable’s value (i.e. the static variable inside which the Expression Variable is defined).
• Select Model Element Variables will open a dialog box when the tool is invoked, from which the user can manually select model elements from a list you can configure. The element or elements selected by the user will become the value of the variable. To configure the dialog box, you must set a Message and a Candidates Expression (evaluated in the context of the parent variable’s value). The candidates expression should return a list of elements from which the user can select the variable’s value. By default these candidates are presented as a list. You can also enable the Tree mode, and specify a Children Expression, which will be evaluated recursively on each candidate to build a tree of possible values. Finally, you can set the Multiple flag to allow users to select several of the candidates instead of a single one.

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 in the context of the diagram whenever a change occurs on Elements To Listen.