| <?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="SiriusEvolutionSpecificationEdgewithlabelsandconnectedportscompoundmove.">Sirius Evolution Specification: Edge with labels and connected ports compound move.</h1><h2 id="Preamble">Preamble</h2><p><em>Summary</em>: Edge with labels and connected ports compound move.</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-06-25</td><td>mporhel</td><td>Initial version.</td></tr><tr><td>v0.2</td><td>PROPOSAL</td><td>2015-07-01</td><td>mporhel</td><td>Team review.</td></tr></table><p><em>Relevant tickets:</em></p><ul><li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=471104">Bug #471104, Edge with labels and connected ports compound moves</a></li></ul><h2 id="Introduction">Introduction</h2><p>In specific cases, we can find edges connected to border nodes. For example in Capella architecture and data flow diagrams, exchanges are connected to port in and port out. When the user wants to move an exchange on a layouted diagram, he has to move the source port, then the target port and possibly move some bendpoints of the edge.</p><p>The main goal of this evolution is to add the capability to move the group {edge, labels, ports} in a single «drag like» operation when the user uses a keyboard modifier and drag/move the edge.</p><p><img border="0" src="exchangeCompoundMove.jpg"/></p><p>This evolution only deals with the basic and direct cases: </p><ul><li>the moved group contain 1 edge and two border nodes which have only one connection: the moved one.</li><li>the group move is unidirectional and authorized only when there is no conflict on the resulting border node positions.</li><li>this compound move will be enabled when the user moves a segment of the edge but not when he moves the source/target node. <ul><li>the implementers will try a direct call of specific moves on the bendpoint move with modifier but if this case requires specific adaptations, it will enable in a further evolution.</li></ul></li><li>the moved edge must not have a tree routing style (which virtually merges segments of several edges).</li></ul><h2 id="DetailedSpecification">Detailed Specification</h2><h3 id="Keyboardmodifier">Keyboard modifier:</h3><p>Existing modifier for resize and move interactions: </p><table><tr><td>Resize shape + SHIFT</td><td>keep ratio</td></tr><tr><td>Resize shape + ALT (CTRL on Mac)</td><td>resize without snap</td></tr><tr><td>Resize shape + CTRL (ALT on Mac)</td><td>centered resize</td></tr><tr><td>Resize shape + F3</td><td>resize with children location relative to parents</td></tr><tr><td>Resize shape + F4</td><td>resize with snap to all shapes (if the «Snap to shapes» is already activated for the current diagram)</td></tr><tr><td>Move shape + SHIFT</td><td>restrict motion to 45 degrees</td></tr><tr><td>Move shape + ALT (CTRL on Mac)</td><td>Resize without snap</td></tr><tr><td>Move shape + CTRL (ALT on Mac)</td><td>clone in GEF, disabled in Sirius</td></tr><tr><td>Move shape + F4</td><td>Move with snap to all shapes (if the «Snap to shapes» is already activated for the current diagram)</td></tr><tr><td>Move bendpoint + SHIFT</td><td>restrict motion to 45 degrees</td></tr><tr><td>Move bendpoint + ALT</td><td>Resize without snap (should be CTRL on Mac, Bug 471018)</td></tr></table><p>See http://melb.enix.org/sirius/keyboard-shortcuts/<br/>See org.eclipse.gef.tools.ResizeTracker<br/>See org.eclipse.gef.tools.DragEditPartsTracker<br/>See org.eclipse.gmf.runtime.gef.ui.internal.tools.ConnectionBendpointTrackerEx<br/>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=471018">Bug 471018 – Wrong no snapping modifier on Mac OS X</a><br/>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=463485">Bug 463485 – Snap to all shapes</a></p><p>CTRL is declared as modifier for the GEF clone action on shapes and not referenced for interactions on bendpoints but it could be confusing to use it.</p><p>F3 is used as modifier for a Sirius specific resize interaction. We could also reuse it for the current Sirius specific group move.</p><h3 id="Identificationofthevalidmoves">Identification of the valid moves</h3><p>The first step of the group move validation will be to check the structure of the group: </p><ul><li>an edge (no check on labels)</li><li>a border node as source (check can be done on edit part, visual id or containing feature of the DNode).</li><li>a border node as target (check can be done on edit part, visual id or containing feature of the DNode).</li><li>source node has only one connection: the moved edge.</li><li>target node has only one connection: the moved edge.</li></ul><p>The second step is to check that source and target border nodes position on their parent are compatible with an unidirectional move:</p><ul><li>source and target located on west or east sides of their respective parent (could be the same)</li><li>source and target located on north or south sides of their respective parent (could be the same)</li></ul><p><img border="0" src="compoundmoves2.png"/></p><p>The third step consists of:</p><ul><li>restricting the request to the identified direction East/West or North/South, ie the x or y attribute of BendpointRequest.getLocation() field.</li><li>validating that there is no conflict with the source/target siblings and enough space on source/target parents to move the nodes: any conflict/overlap must result in an unexecutable command with the proper feedback. The validator should ensure that there is at least 1 pixel between the moved nodes and their siblings as done in the DBorderItemLocator.</li></ul><p><img border="0" src="compoundmoves1.png"/></p><p>The edge’s bendpoints are relative to the source and target anchors, themselves relatively located to the connected node bounds. So the compound move only has to move the source and target nodes with the same delta, the edge and its labels will automatically follow. However the feedback will have to properly computed and displayed whereas it is directly done in case of standard bendpoint move/creation. </p><h3 id="Feedback">Feedback</h3><p>The feedback should show the limits of the move or the validation result of the move. The mouse icon should be impacted. <br/>It might be different than displaying the moved group in its final position.<br/>It could be interesting to show guides as done on Sequence diagrams.<br/>The feedback might not be as advanced as the drag of a single port, which shows the collapsed sibling ports.</p><h3 id="ImpactonSequencediagrams">Impact on Sequence diagrams</h3><p>The Sequence diagram defines its own user interactions on Sequence elements. Implementers will have to make sure that this feature is disabled/forbidden on Sequence messages as they are connected to executions or lifelines which are border nodes.</p><h3 id="Unsupportedcases">Unsupported cases</h3><p>The current evolution only deals with edges connected to border nodes having only the moved edge in source/target connections.</p><p><img border="0" src="unsupportedstructures.png"/></p><p>The policy must return an unexecutable command and the feedback will have to show the forbidden icon for unsupported group structures.</p><h3 id="Entrypoints">Entry points</h3><ul><li>org.eclipse.gmf.runtime.diagram.ui.editpolicies.ConnectionBendpointEditPolicy sub-implementations.</li><li>org.eclipse.gmf.runtime.gef.ui.internal.tools.ConnectionBendpointTrackerEx</li></ul><h2 id="BackwardCompatibilityandMigrationPaths">Backward Compatibility and Migration Paths</h2><h3 id="MetamodelChanges">Metamodel Changes</h3><p>No metamodel changes.</p><h3 id="APIChanges">API Changes</h3><p>API Changes will be completed during implementation, it should concern only edit parts, policies and queries.</p><h3 id="UserInterfaceChanges">User Interface Changes</h3><p>A new modifier will be available to replace the bendpoint creation operation by an edge move interaction.</p><p>No other user interface changes.</p><h3 id="DocumentationChanges">Documentation Changes</h3><ul><li>User documentation: document the modifier and the supported cases.</li></ul><ul><li>N&N : the new feature must be documented.</li></ul><h2 id="TestsandNonregressionstrategy">Tests and Non-regression strategy</h2><ul><li>SWTBot Tests<ul><li>the supported cases: nominal cases (vertical, horizontal), unsupported/forbidden cases.</li><li>the label position changes (conditional style, import activation after layer/semantic modification)</li><li>See <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=463485">Bug 463485</a> for draft on drag with modifier.</li></ul></li></ul><ul><li>Manual Tests<ul><li>the feedback (supported: allowed/forbidden cases, unsupported cases)</li></ul></li></ul><h2 id="Implementationchoicesandtradeoffs">Implementation choices and tradeoffs</h2><p>Validator and commands will be created in the edge selection policy. An other possibility was to create a constrained move request (ChangeBoundsRequest) and ask the source/target edit parts to build their commands but this would have result in the compound move command creation, validation and feedback to be dispatched in several places.</p><p>Another proposed idea is to provide a new selection shortcut (like the ALT+SHIFT+UP in a Java file) to extend the selection: on an edge it could select the source and target (and keep the edge primary selected). The user could also use the CTRL + click to build the selection. Then the edge bendpoints move/creation commands could analyze the selection and produce the compound move.</p></body></html> |