diff options
| author | Laurent Redor | 2015-04-09 10:19:44 +0000 |
|---|---|---|
| committer | Laurent Redor | 2015-04-22 07:01:50 +0000 |
| commit | d8ac477147d385f28ba23ec47a0965c180401b8e (patch) | |
| tree | fa9675c5a28ca95f6fc95164289d1fcbf8a797f4 | |
| parent | 62a157b3bfb9c196b41affe22d88667406807aa5 (diff) | |
| download | org.eclipse.sirius-d8ac477147d385f28ba23ec47a0965c180401b8e.tar.gz org.eclipse.sirius-d8ac477147d385f28ba23ec47a0965c180401b8e.tar.xz org.eclipse.sirius-d8ac477147d385f28ba23ec47a0965c180401b8e.zip | |
[464269] Specification
Bug: 464269
Change-Id: I9b0a699413b63bd686e1cea590c161ff91036f23
Signed-off-by: Laurent Redor <laurent.redor@obeo.fr>
5 files changed, 123 insertions, 0 deletions
diff --git a/plugins/org.eclipse.sirius.doc/.settings/org.eclipse.core.resources.prefs b/plugins/org.eclipse.sirius.doc/.settings/org.eclipse.core.resources.prefs index ee70190fe6..9d80bbf715 100644 --- a/plugins/org.eclipse.sirius.doc/.settings/org.eclipse.core.resources.prefs +++ b/plugins/org.eclipse.sirius.doc/.settings/org.eclipse.core.resources.prefs @@ -12,3 +12,4 @@ encoding//specs/archived/437097-moveEdgeClosestSegmentWhenMovingNode/437097-move encoding//specs/archived/441090_ResizeNodeWithoutModifyingContainedElementsLocation/441090.html=utf-8 encoding//specs/archived/442289_DistributeShapesActions/442289_DistributeShapesActions.html=utf-8 encoding//specs/proposal/463485_snapToAllShapes/463485.html=utf-8 +encoding//specs/proposal/464269_selectElementsAfterToolExecution/464269.html=utf-8 diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/464269.html b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/464269.html new file mode 100644 index 0000000000..3cefde07a4 --- /dev/null +++ b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/464269.html @@ -0,0 +1 @@ +<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/></head><body><h1 id="SiriusEvolutionSpecificationAllowspecifiertochoosetheselectedelementsaftertoolexecution">Sirius Evolution Specification: Allow specifier to choose the selected elements after tool execution</h1><h2 id="Preamble">Preamble</h2><p><em>Summary</em>: Allow specifier to choose the selected elements after tool execution.</p><table><tr><th>Version </th><th>Status </th><th>Date </th><th>Authors </th><th>Changes </th></tr><tr><td>v0.1 </td><td>DRAFT </td><td>2015-04-15 </td><td>lredor </td><td>Initial version. </td></tr><tr><td>v0.2 </td><td>DRAFT </td><td>2015-04-21 </td><td>lredor </td><td>Consider team review. </td></tr><tr><td>v0.3 </td><td>PROPOSAL </td><td>2015-04-22 </td><td>lredor </td><td>Consider team review. </td></tr></table><p><em>Relevant tickets</em>:</p><ul><li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=464269">Bug 464269 – Allow specifier to choose the selected elements after tool execution</a></li></ul><h2 id="Introduction">Introduction</h2><p>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.</p><p>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.</p><p>The goal of this feature is to allow the specifier to choose the selected elements after a tool execution. </p><h2 id="DetailedSpecification">Detailed Specification</h2><p>To allow the specifier to choose the graphical elements to select after a tool execution, some additional data are needed for tools description.<br/>There are 2 cases:</p><ul><li>the tool creates only semantic elements (graphical elements are computing during the refresh according to the mapping and to the new semantic elements)</li><li>the tool creates the semantic elements <strong>and</strong> the graphical elements</li></ul><p>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).<br/>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.</p><p><img border="0" src="images/metaModelChanges.jpg"/></p><h3 id="VSM">VSM </h3><p>On the VSM side, two new fields are necessary on <code>AbstractToolDescription</code>:</p><ul><li><code>InterpretedExpression elementsToSelect</code>: 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:<ul><li>List of <code>DRepresentationElement</code>: All this graphical elements will be selected after the execution of the tool.</li><li>List of semantic elements: All <code>EObject</code> that are not a <code>DRepresentationElement</code> are considered as semantic elements. All graphical elements corresponding to these semantic elements will be selected after the execution of the tool.</li><li>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 <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=428545">bugzilla 428545</a> that is currently in progress.</li><li>List with only the <code>DRepresentation</code>: Nothing is selected after the execution of the tool.</li><li>List with a mix of <code>DRepresentationElement</code> and non <code>DRepresentationElement</code> is forbidden. A such list will be considered as empty list.</li></ul></li><li><code>EBoolean inverseSelectionOrder</code> : 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:<ul><li>List of <code>DRepresentationElement</code>: 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 <code>inverseSelectionOrder</code> is false, the order is reversed.</li><li>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 <code>inverseSelectionOrder</code> is false, the order is reversed (the order of the list AND the order of several graphical elements correspond to the same semantic element).</li><li>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 <code>inverseSelectionOrder</code> is false, the order is reversed.</li><li>List with only the <code>DRepresentation</code>: The <code>inverseSelectionOrder</code> is ignored in this context.</li></ul></li></ul><h4 id="Completion">Completion</h4><p>List of variables that should be proposed in the completion:</p><ul><li>All sub variables defined directly under the tool. Examples:<ul><li><code>container</code> and <code>containerView</code> for a <code>ContainerCreationDescription</code>, </li><li><code>element</code> and <code>elementView</code> for a <code>ToolDescription</code></li><li><code>root</code>, <code>element</code> and <code>container</code> for a <code>CreateLineTool</code></li></ul></li><li>All variables defined through <code>CreateInstance</code> operations</li><li>All variables defined through <code>CreateView</code> operations</li><li>All variables defined through <code>CreateEdgeView</code> operations</li></ul><p>Technically, the entry point to changes this is in <code>org.eclipse.sirius.tools.api.interpreter.context.SiriusInterpreterContextFactory.createInterpreterContext(EObject, EStructuralFeature)</code> and depending classes, for example in <code>org.eclipse.sirius.diagram.business.internal.dialect.description.DiagramInterpretedExpressionQuery.getAvailableVariables()</code>.</p><h3 id="Runtime">Runtime </h3><p>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 <code>ResourceSetListenerImpl</code>). Indeed, the tool is not accessible in the post commit listener so these data must be stored in the current modified representation.<br/>A new class <code>UIState</code> will be added in the meta-model to store this computed expression (and also the current <code>inverseSelectionOrder</code>). A new reference, <code>uiState</code> to this <code>UIState</code> will be added in <code>DRepresentation</code>. This reference is a containment reference and is transient. The class <code>UIState</code> allows to store several transient data in <code>DRepresentation</code>. It will be currently used only for this feature but we can imagine to use it in the future instead of specific singleton (<code>ViewLocationHint</code>, <code>ViewSizeHint</code>) or for copy/paste layout capability for example.<br/>This new class has 2 fields:</p><ul><li><code>List<EObject> elementsToSelect</code>: The result of the computation of <code>elementsToSelect</code> interpreted expression of the tool. The expression <code>elementsToSelect</code> is evaluated after the execution of the tool (technically as the current refresh task: <code>org.eclipse.sirius.tools.api.command.AbstractCommandFactory.addRefreshTask(DSemanticDecorator, DCommand, AbstractToolDescription)</code> or <code>org.eclipse.sirius.diagram.tools.internal.command.builders.AbstractDiagramCommandBuilder.addRefreshTask(DDiagram, DCommand, AbstractToolDescription)</code>). 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.</li><li><code>EBoolean inverseSelectionOrder</code>: The value of the <code>inverseSelectionOrder</code> of the tool.</li></ul><p>The <code>uiState</code> will be cleaned just before the next use of it. This leads to a temporary memory leak:</p><ul><li>The elements to select are retained by the <code>uiState.elementsToSelect</code> reference.</li><li>But in theory there are already loaded and available in the semantic resource or in the representation resource.</li></ul><p>This temporary memory leak is accepted as it will be free when the representation is unloaded.</p><p>Currently, the selection is made by <code>SelectCreatedDRepresentationElementsListener</code> for the diagram and not done for table and tree (see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=428545">bugzilla 428545</a> 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 <code>SelectCreatedDRepresentationElementsListener</code>.</p><h2 id="BackwardCompatibilityandMigrationPaths">Backward Compatibility and Migration Paths</h2><p>This is a new behavior, so without modification of the VSM, there is no impact. The metamodel is changed but just with new elements.</p><h3 id="MetamodelChanges">Metamodel Changes</h3><p>All the new metamodel elements are in blue.<br/><img border="0" src="images/metaModelChanges.jpg"/></p><p>No validation rule is needed:</p><ul><li><code>AbstractToolDescription.elementsToSelect</code> 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).</li><li><code>AbstractToolDescription.inverseSelectionOrder</code> has false as default value</li><li><code>UIState.elementsToSelect</code> can be null: in this case, it is considered as empty and nothing is selected.</li><li><code>UIState.inverseSelectionOrder</code> has false as default value</li></ul><p>No migration is needed for the new elements.</p><h3 id="APIChanges">API Changes</h3><p>The main API changes is for meta-model.<br/>There is probably new API in <code>org.eclipse.sirius.tools.api.command.AbstractCommandFactory</code> to provide default access to the new fields of the tool (evaluation of the expression...).</p><h3 id="UserInterfaceChanges">User Interface Changes</h3><p>In the <em>Properties</em> view of a VSM, the tool have now the new properties defined above.<br/><img border="0" src="images/expectedPropertiesView.png"/></p><h3 id="DocumentationChanges">Documentation Changes</h3><p>Update specifier documentation and release note about this new feature.</p><h2 id="TestsandNonregressionstrategy">Tests and Non-regression strategy</h2><ul><li>Select nothing (expression that returns the representation)</li><li>Empty expression --> current behavior</li><li>Empty expression but inverse order</li><li>Select 2 elements of 3</li><li>Select 2 elements of 3 with inverse order</li><li>Use description of use case of <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=464269#c1">bugzilla 428545</a></li><li>Test at least a tool in a diagram, in a table and in a tree. </li></ul><h2 id="Implementationchoicesandtradeoffs">Implementation choices and tradeoffs</h2><p>The solution to add a new <code>ModelOperation</code> 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 <code>ModelOperation</code>. </p></body></html>
\ No newline at end of file diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/464269.textile b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/464269.textile new file mode 100644 index 0000000000..a15c9ed3b7 --- /dev/null +++ b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/464269.textile @@ -0,0 +1,121 @@ +h1. Sirius Evolution Specification: Allow specifier to choose the selected elements after tool execution + +h2. Preamble + +_Summary_: Allow specifier to choose the selected elements after tool execution. + +|_. Version |_. Status |_. Date |_. Authors |_. Changes | +| v0.1 | DRAFT | 2015-04-15 | lredor | Initial version. | +| v0.2 | DRAFT | 2015-04-21 | lredor | Consider team review. | +| v0.3 | PROPOSAL | 2015-04-22 | lredor | Consider team review. | + +_Relevant tickets_: +* "Bug 464269 - Allow specifier to choose the selected elements after tool execution":https://bugs.eclipse.org/bugs/show_bug.cgi?id=464269 + +h2. 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. + +h2. 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. + +!images/metaModelChanges.jpg! + +h3. 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":https://bugs.eclipse.org/bugs/show_bug.cgi?id=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. + +h4. 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()@. + +h3. 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":https://bugs.eclipse.org/bugs/show_bug.cgi?id=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@. + +h2. 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. + +h3. Metamodel Changes + +All the new metamodel elements are in blue. +!images/metaModelChanges.jpg! + +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. + +h3. 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...). + +h3. User Interface Changes + +In the _Properties_ view of a VSM, the tool have now the new properties defined above. +!images/expectedPropertiesView.png! + +h3. Documentation Changes + +Update specifier documentation and release note about this new feature. + +h2. 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":https://bugs.eclipse.org/bugs/show_bug.cgi?id=464269#c1 +* Test at least a tool in a diagram, in a table and in a tree. + +h2. 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@. diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/images/expectedPropertiesView.png b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/images/expectedPropertiesView.png Binary files differnew file mode 100644 index 0000000000..fb86ae02c5 --- /dev/null +++ b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/images/expectedPropertiesView.png diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/images/metaModelChanges.jpg b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/images/metaModelChanges.jpg Binary files differnew file mode 100644 index 0000000000..9b19ee3e48 --- /dev/null +++ b/plugins/org.eclipse.sirius.doc/specs/proposal/464269_selectElementsAfterToolExecution/images/metaModelChanges.jpg |
