[490360] Add spec for this feature

Bug: 490360
Change-Id: I52deb9cd09703216321cdd8499d41bd6ad69bd69
Signed-off-by: Laurent Redor <laurent.redor@obeo.fr>

7 files changed, 178 insertions, 2 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 83a3b021ec..af81b0aa4b 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
@@ -18,4 +18,5 @@ encoding//specs/archived/465328_edgeLabelLocation/465328.html=UTF-8
 encoding//specs/archived/471104_edgeAndPortsCompoundMoves/471104.html=utf-8
 encoding//specs/proposal/440296_Required_side_for_border_nodes/440296_Required_side_for_border_nodes.html=UTF-8
 encoding//specs/proposal/459993_VSM_Internationalization/VSM_Internationalization.html=utf-8
+encoding//specs/proposal/490360_SnapToShapeForBorderNodes/490360.html=UTF-8
 encoding//specs/proposal/connections_to_figure_border/connections_between_figures_borders_and_edges.html=utf-8
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.html b/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.html
index 571b4055b9..4877d2277b 100644
--- a/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.html
+++ b/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.html
@@ -82,7 +82,7 @@
 				<em>Properties</em> view when the diagram itself is selected. You can also disable it for all future diagrams in the preferences: 
 				<em>Sirius &gt; Sirius Diagram &gt; Rulers and Grid</em>, un-check the 
 				<em>Snap to grid for new diagrams</em> and 
-				<em>Snap to shapes for new diagrams</em> check boxes. Since Sirius 3.1.0, the snap features are automaticcaly disabled in Sequence diagram editors and the user can not reactivate them.
+				<em>Snap to shapes for new diagrams</em> check boxes. Since Sirius 3.1.0, the snap features are automatically disabled in Sequence diagram editors and the user can not reactivate them.
 			</li>
 			<li>Enable Sirius&#8217;s 
 				<em>Automatic Refresh</em> (in the main 
diff --git a/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.textile b/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.textile
index c559cde0ef..6bbb101d09 100644
--- a/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/user/sequences/Sequence Diagrams.textile
@@ -15,7 +15,7 @@ These diagrams behave mostly like normal Sirius diagrams, but in order to ensure
 This document only describes the specificities of sequence diagrams. Unless otherwise stated here, all the features of normal Sirius diagrams apply also to sequence diagrams, so you can refer to "the general diagrams user manual":../diagrams/Diagrams.html for more information.
 
 *IMPORTANT WARNING*: To work correctly, Sirius sequence diagrams must have a tight control on where the graphical elements are placed on the diagram and on their synchronization with the underlying semantic model. This means that to use sequence diagrams you _must_:
-# Disable the _Snap to Grid_ and the _Snap to Shapes_ behaviors. For an existing diagram, this is available in the _Rulers & Grid_ section of the _Properties_ view when the diagram itself is selected. You can also disable it for all future diagrams in the preferences: _Sirius > Sirius Diagram > Rulers and Grid_, un-check the _Snap to grid for new diagrams_ and _Snap to shapes for new diagrams_ check boxes. Since Sirius 3.1.0, the snap features are automaticcaly disabled in Sequence diagram editors and the user can not reactivate them.
+# Disable the _Snap to Grid_ and the _Snap to Shapes_ behaviors. For an existing diagram, this is available in the _Rulers & Grid_ section of the _Properties_ view when the diagram itself is selected. You can also disable it for all future diagrams in the preferences: _Sirius > Sirius Diagram > Rulers and Grid_, un-check the _Snap to grid for new diagrams_ and _Snap to shapes for new diagrams_ check boxes. Since Sirius 3.1.0, the snap features are automatically disabled in Sequence diagram editors and the user can not reactivate them.
 # Enable Sirius's _Automatic Refresh_ (in the main _Sirius_ preferences page) to ensure the diagram is always kept in synch with the underlying semantic model.
 
 h2(#semantics). Sequence Diagrams Semantics
diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/490360.html b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/490360.html
new file mode 100644
index 0000000000..87a55210ac
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/490360.html
@@ -0,0 +1,103 @@
+<?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="AllowtheSnapToShapesfeatureonbordernodes">Allow the &#171;Snap To Shapes&#187; feature on border nodes</h1>
+		<h2 id="Preamble">Preamble</h2>
+		<p>
+			<em>Summary</em>: Allow the &#171;Snap To Shapes&#187; feature on border nodes.
+		</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>2016-03-24</td>
+				<td>lredor</td>
+				<td>Initial version.</td>
+			</tr>
+		</table>
+		<p>
+			<em>Relevant tickets</em> :
+		</p>
+		<ul>
+			<li>"Bug 490360 &#8211; Allow the &#171;Snap To Shapes&#187; feature on border nodes":https://bugs.eclipse.org/bugs/show_bug.cgi?id=490360</li>
+		</ul>
+		<h2 id="Introduction">Introduction</h2>
+		<p>As explained in specification of 
+			<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=463485">bug 463485</a>, 
+			<cite>the 
+				<em>Snap To Shapes</em> feature is not operational when moving or resizing a border node.
+			</cite>. The goal of this feature is to make operational the 
+			<em>Snap To Shapes</em> feature even on border nodes, and also to benefit of the same feature as 
+			<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=463485">bug 463485</a> (ie &#171;snap to all shapes&#187;, and not only snap to brothers). You can see 
+			<a href="http://git.eclipse.org/c/sirius/org.eclipse.sirius.git/plain/plugins/org.eclipse.sirius.doc/specs/accepted/463485_snapToAllShapes/463485.html?h=v3.1.x">specification</a> of bug 463485 for details about &#171;snap to all shapes&#187; feature.
+		</p>
+		<h2 id="DetailedSpecification">Detailed Specification</h2>
+		<p>The 
+			<em>Snap To Shapes</em> feature is natively not supported by GMF. Probably because the interest is limited. It allows only to snap to another border node on the opposite side:
+			<br/>
+			<img border="0" src="snapToBrotherBorderNode.png"/>
+		</p>
+		<p>But with the option to &#171;snap to all shapes&#187; (with F4 shortcut key), this feature becomes interesting even for border nodes. To align &#171;in&#187; border node with &#171;out&#187; border node for example:
+			<br/>
+			<img border="0" src="snapToAnotherBorderNode.png"/>
+		</p>
+		<h3 id="Collapsedbordernodes">Collapsed border nodes</h3>
+		<p>The border node can be collapsed (with a filter for example). In this case:</p>
+		<ul>
+			<li>If the moved border node is collapsed, the collapsed border node is snapped to other shapes (not its expanded bounds).</li>
+			<li>If the moved border node is snapped to a collapsed border node, the behavior will be the same as other kind of nodes currently. It will be snapped to the collapsed border node (and not to its expanded bounds).</li>
+		</ul>
+		<h3 id="Knownlimitations">Known limitations</h3>
+		<p>As a reminder (See 
+			<a href="https://www.eclipse.org/sirius/doc/user/sequences/Sequence%20Diagrams.html#introduction)">Sequence diagram introduction</a>, the snap features (snap to grid or snap to shapes) are disabled in sequence diagrams. This will obviously also the case for border nodes even with this improvement.
+		</p>
+		<h3 id="Technicaldetails">Technical details</h3>
+		<p>The 
+			<code>SiriusDragEditPartsTrackerEx</code> has the responsibility to find the correct 
+			<code>SnapHelper</code> according to the &#171;targetUnderMouse&#187; (in 
+			<code>org.eclipse.gef.tools.DragEditPartsTracker.setTargetEditPart(EditPart)</code>).
+			<br/>When moving a border node, the &#171;targetUnderMouse&#187; is an 
+			<code>AbstractDiagramNodeEditPart</code> (parent is a Node) or an 
+			<code>AbstractDNodeContainerCompartmentEditPart</code> (parent is a container).
+			<br/>The policy that displays the feedback (guide line) is 
+			<code>SiriusSnapFeedbackPolicy</code>.
+			<br/>The 
+			<code>SiriusSnapToGeometry</code> is responsible to compute the element to snap with (and so x and y coordinates to snap with). 
+		</p>
+		<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>All the changes will be mainly internal to the edit part and associated policies. So there will be no API changes for this feature.</p>
+		<h3 id="UserInterfaceChanges">User Interface Changes</h3>
+		<p>No user interface change.</p>
+		<h3 id="DocumentationChanges">Documentation Changes</h3>
+		<p>This new behavior should be added in the New and Noteworthy documentation. 
+			<br/>The limitation "
+			<cite>This feature is not enabled on border nodes.</cite>" in the diagram documentation should be removed.
+		</p>
+		<h2 id="TestsandNonregressionstrategy">Tests and Non-regression strategy</h2>
+		<p>The class 
+			<code>org.eclipse.sirius.tests.swtbot.SnapAllShapesTest</code> must be completed with border nodes cases:
+		</p>
+		<ul>
+			<li>Border node on node in diagram</li>
+			<li>Border node on node in container</li>
+			<li>Border node on container</li>
+			<li>Border node on list</li>
+			<li>Border node on border node</li>
+		</ul>
+		<h2 id="Implementationchoicesandtradeoffs">Implementation choices and tradeoffs</h2>
+		<p>For the case of collapsed border nodes, it would be interesting to snap the expanded bounds (and not the collapsed state). But the &#171;snap to&#187; mechanism is generic to all kind of nodes and associated to the figure representing the node. It would be too impacting to try to manage the expanded state.</p>
+	</body>
+</html>
\ No newline at end of file
diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/490360.textile b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/490360.textile
new file mode 100644
index 0000000000..cc43bd55b0
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/490360.textile
@@ -0,0 +1,72 @@
+h1. Allow the "Snap To Shapes" feature on border nodes
+
+h2. Preamble
+
+_Summary_: Allow the "Snap To Shapes" feature on border nodes.
+
+|_. Version |_. Status |_. Date        |_. Authors |_. Changes |
+| v0.1        | DRAFT    | 2016-03-24 | lredor    | Initial version. |
+
+_Relevant tickets_ :
+* "Bug 490360 - Allow the "Snap To Shapes" feature on border nodes":https://bugs.eclipse.org/bugs/show_bug.cgi?id=490360
+
+h2. Introduction
+
+As explained in specification of "bug 463485":https://bugs.eclipse.org/bugs/show_bug.cgi?id=463485, ??the _Snap To Shapes_ feature is not operational when moving or resizing a border node.??. The goal of this feature is to make operational the _Snap To Shapes_ feature even on border nodes, and also to benefit of the same feature as "bug 463485":https://bugs.eclipse.org/bugs/show_bug.cgi?id=463485 (ie "snap to all shapes", and not only snap to brothers). You can see "specification":http://git.eclipse.org/c/sirius/org.eclipse.sirius.git/plain/plugins/org.eclipse.sirius.doc/specs/accepted/463485_snapToAllShapes/463485.html?h=v3.1.x of bug 463485 for details about "snap to all shapes" feature.
+
+h2. Detailed Specification
+
+The _Snap To Shapes_ feature is natively not supported by GMF. Probably because the interest is limited. It allows only to snap to another border node on the opposite side:
+!snapToBrotherBorderNode.png!
+
+But with the option to "snap to all shapes" (with F4 shortcut key), this feature becomes interesting even for border nodes. To align "in" border node with "out" border node for example:
+!snapToAnotherBorderNode.png!
+
+h3. Collapsed border nodes
+
+The border node can be collapsed (with a filter for example). In this case:
+* If the moved border node is collapsed, the collapsed border node is snapped to other shapes (not its expanded bounds).
+* If the moved border node is snapped to a collapsed border node, the behavior will be the same as other kind of nodes currently. It will be snapped to the collapsed border node (and not to its expanded bounds).
+
+h3. Known limitations
+
+As a reminder (See "Sequence diagram introduction":https://www.eclipse.org/sirius/doc/user/sequences/Sequence%20Diagrams.html#introduction), the snap features (snap to grid or snap to shapes) are disabled in sequence diagrams. This will obviously also the case for border nodes even with this improvement.
+
+h3. Technical details
+
+The @SiriusDragEditPartsTrackerEx@ has the responsibility to find the correct @SnapHelper@ according to the "targetUnderMouse" (in @org.eclipse.gef.tools.DragEditPartsTracker.setTargetEditPart(EditPart)@).
+When moving a border node, the "targetUnderMouse" is an @AbstractDiagramNodeEditPart@ (parent is a Node) or an @AbstractDNodeContainerCompartmentEditPart@ (parent is a container).
+The policy that displays the feedback (guide line) is @SiriusSnapFeedbackPolicy@.
+The @SiriusSnapToGeometry@ is responsible to compute the element to snap with (and so x and y coordinates to snap with). 
+
+h2. Backward Compatibility and Migration Paths
+
+h3. Metamodel Changes
+
+No metamodel changes.
+  
+h3. API Changes
+
+All the changes will be mainly internal to the edit part and associated policies. So there will be no API changes for this feature.
+
+h3. User Interface Changes
+
+No user interface change.
+
+h3. Documentation Changes
+
+This new behavior should be added in the New and Noteworthy documentation. 
+The limitation "??This feature is not enabled on border nodes.??" in the diagram documentation should be removed.
+
+h2. Tests and Non-regression strategy
+
+The class @org.eclipse.sirius.tests.swtbot.SnapAllShapesTest@ must be completed with border nodes cases:
+* Border node on node in diagram
+* Border node on node in container
+* Border node on container
+* Border node on list
+* Border node on border node
+
+h2. Implementation choices and tradeoffs
+
+For the case of collapsed border nodes, it would be interesting to snap the expanded bounds (and not the collapsed state). But the "snap to" mechanism is generic to all kind of nodes and associated to the figure representing the node. It would be too impacting to try to manage the expanded state.
\ No newline at end of file
diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/snapToAnotherBorderNode.png b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/snapToAnotherBorderNode.png
new file mode 100644
index 0000000000..d4a147bd55
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/snapToAnotherBorderNode.png
diff --git a/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/snapToBrotherBorderNode.png b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/snapToBrotherBorderNode.png
new file mode 100644
index 0000000000..6de1d84080
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/specs/proposal/490360_SnapToShapeForBorderNodes/snapToBrotherBorderNode.png