Sirius Evolution Specification: Allow specifier to choose the selected elements after tool execution

Preamble

Summary: Allow specifier to choose the selected elements after tool execution.

Relevant tickets:

• Bug 464269 – Allow specifier to choose the selected elements after tool execution

Introduction

Currently, after a tool execution, all new graphical elements are selected (in the creation order). The last created graphical element is the primary selection. The primary selection determines the available actions and the scope of these actions.

This behavior is not always the expected one. For example, just after a creation, the direct edit tool is available on the primary selection (the last created graphical element). If the direct edit tool must operate on the first created graphical element, the user must select the diagram and then select again the first created graphical element to direct edit.

The goal of this feature is to allow the specifier to choose the selected elements after a tool execution.

Detailed Specification

To allow the specifier to choose the graphical elements to select after a tool execution, some additional data are needed for tools description.
There are 2 cases:

• the tool creates only semantic elements (graphical elements are computing during the refresh according to the mapping and to the new semantic elements)
• the tool creates the semantic elements and the graphical elements

In the first case, the specifier can only fill an expression with the list of semantic elements to select. Depending on the tool, the same semantic element can correspond to several graphical elements. In this case, all the graphical elements corresponding to the semantic element will be selected (with the same current rule: the last created element is the primary selection).
In the second case, we can easily imagine that the specifier fills an expression with the list of graphical elements to select. Indeed, if the tool also creates the graphical elements, they are accessible latter in the tool by using the instance variable name.

VSM

On the VSM side, two new fields are necessary on AbstractToolDescription:

• InterpretedExpression elementsToSelect: Expression to list the elements to select after the execution of the tool. There are 4 possibilities for the list of elements returned by this expression:
  • 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: The default behavior is applied. For diagram, all the new created graphical elements will be selected after the execution of the tool. For tree or table, it depends on the behavior adopted for bugzilla 428545 that is currently in progress.
  • List with only the DRepresentation: Nothing is selected after the execution of the tool.
  • List with a mix of DRepresentationElement and non DRepresentationElement is forbidden. A such list will be considered as empty list.
• EBoolean inverseSelectionOrder : By default, false, the elements are selected in the order of the list or in creation order. 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 false, the order is reversed.
  • 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 creation order. The last element is the primary selection. If inverseSelectionOrder is false, the order is reversed (the order of the list AND the order of several graphical elements correspond to the same semantic element).
  • Empty: All the new created graphical elements are selected in order of their creation (first element is selected in first, second element is selected in second, and so on). The last created graphical element will be the primary selection. If inverseSelectionOrder is false, the order is reversed.
  • List with only the DRepresentation: The inverseSelectionOrder is ignored in this context.

Completion

List of variables that should be proposed in the completion:

• All sub variables defined directly under the tool. Examples:
  • container and containerView for a ContainerCreationDescription,
  • element and elementView for a ToolDescription
  • root, element and container for a CreateLineTool
• All variables defined through CreateInstance operations
• All variables defined through CreateView operations
• All variables defined through CreateEdgeView operations

Technically, the entry point to changes this is in org.eclipse.sirius.tools.api.interpreter.context.SiriusInterpreterContextFactory.createInterpreterContext(EObject, EStructuralFeature) and depending classes, for example in org.eclipse.sirius.diagram.business.internal.dialect.description.DiagramInterpretedExpressionQuery.getAvailableVariables().

Runtime

All above changes, on the VSM side, allow the specifier to configure the expected list of elements to select. Then, new fields are needed in representations file to store this result, used later in a post commit listener (a ResourceSetListenerImpl). Indeed, the tool is not accessible in the post commit listener so these data must be stored in the current modified representation.
A new class UIState will be added in the meta-model to store this computed expression (and also the current inverseSelectionOrder). A new reference, uiState to this UIState will be added in DRepresentation. This reference is a containment reference and is transient. The class UIState allows to store several transient data in DRepresentation. It will be currently used only for this feature but we can imagine to use it in the future instead of specific singleton (ViewLocationHint, ViewSizeHint) or for copy/paste layout capability for example.
This new class has 2 fields:

• List<EObject> elementsToSelect: The result of the computation of elementsToSelect interpreted expression of the tool. The expression elementsToSelect is evaluated after the execution of the tool (technically as the current refresh task: org.eclipse.sirius.tools.api.command.AbstractCommandFactory.addRefreshTask(DSemanticDecorator, DCommand, AbstractToolDescription) or org.eclipse.sirius.diagram.tools.internal.command.builders.AbstractDiagramCommandBuilder.addRefreshTask(DDiagram, DCommand, AbstractToolDescription)). The context of evaluation should «be the same as completion»: every variable proposed in the completion should be available and valued in the context of the interpreter during evaluation of the expression.
• EBoolean inverseSelectionOrder: The value of the inverseSelectionOrder of the tool.

The uiState will be cleaned just before the next use of it. This leads to a temporary memory leak:

• The elements to select are retained by the uiState.elementsToSelect reference.
• But in theory there are already loaded and available in the semantic resource or in the representation resource.

This temporary memory leak is accepted as it will be free when the representation is unloaded.

Currently, the selection is made by SelectCreatedDRepresentationElementsListener for the diagram and not done for table and tree (see bugzilla 428545 for table and tree). The chosen behavior for tree (probably TreeUIUpdater) and table (probably TableUIUpdater) must also consider the new fields of DRepresentation as for SelectCreatedDRepresentationElementsListener.

Backward Compatibility and Migration Paths

This is a new behavior, so without modification of the VSM, there is no impact. The metamodel is changed but just with new elements.

Metamodel Changes

All the new metamodel elements are in blue.

No validation rule is needed:

• AbstractToolDescription.elementsToSelect can be blank (considered as empty): in this case the behavior is the current (all the created elements are selected in the order of the creation).
• AbstractToolDescription.inverseSelectionOrder has false as default value
• UIState.elementsToSelect can be null: in this case, it is considered as empty and nothing is selected.
• UIState.inverseSelectionOrder has false as default value

No migration is needed for the new elements.

API Changes

The main API changes is for meta-model.
There is probably new API in org.eclipse.sirius.tools.api.command.AbstractCommandFactory to provide default access to the new fields of the tool (evaluation of the expression...).

User Interface Changes

In the Properties view of a VSM, the tool have now the new properties defined above.

Documentation Changes

Update specifier documentation and release note about this new feature.

Tests and Non-regression strategy

• Select nothing (expression that returns the representation)
• Empty expression --> current behavior
• Empty expression but inverse order
• Select 2 elements of 3
• Select 2 elements of 3 with inverse order
• Use description of use case of bugzilla 428545
• Test at least a tool in a diagram, in a table and in a tree.

Implementation choices and tradeoffs

The solution to add a new ModelOperation has not been chosen because the specifier has not really the choice. This operation is called at the end of the tool and not in the middle of other ModelOperation.