[497403] Complete documentation about compartments layout

Bug: 497403
Cherry-picked-from: 495119
Change-Id: I873a3b0aafdf0a35ba124e79e78e5184a0ba48a9
Signed-off-by: Laurent Redor <laurent.redor@obeo.fr>

8 files changed, 138 insertions, 10 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index f12a67a178..3bf7989e5c 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -13,6 +13,14 @@
 				<a href="#ReleaseNotesforSirius">Release Notes for Sirius</a>
 				<ol style="list-style: disc;">
 					<li>
+						<a href="#sirius3.1.6">Changes in Sirius 3.1.6</a>
+						<ol style="list-style: disc;">
+							<li>
+								<a href="#SpecifierVisibleChanges">Specifier-Visible Changes</a>
+							</li>
+						</ol>
+					</li>
+					<li>
 						<a href="#sirius3.1.5">Changes in Sirius 3.1.5</a>
 						<ol style="list-style: disc;">
 							<li>
@@ -27,7 +35,7 @@
 								<a href="#UserVisibleChanges2">User-Visible Changes</a>
 							</li>
 							<li>
-								<a href="#SpecifierVisibleChanges">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges2">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#DeveloperVisibleChanges">Developer-Visible Changes</a>
@@ -38,7 +46,7 @@
 						<a href="#sirius3.1.1">Changes in Sirius 3.1.1</a>
 						<ol style="list-style: disc;">
 							<li>
-								<a href="#SpecifierVisibleChanges2">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges3">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#DeveloperVisibleChanges2">Developer-Visible Changes</a>
@@ -52,7 +60,7 @@
 								<a href="#UserVisibleChanges3">User-Visible Changes</a>
 							</li>
 							<li>
-								<a href="#SpecifierVisibleChanges3">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges4">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#DeveloperVisibleChanges3">Developer-Visible Changes</a>
@@ -66,7 +74,7 @@
 								<a href="#UserVisibleChanges4">User-Visible Changes</a>
 							</li>
 							<li>
-								<a href="#SpecifierVisibleChanges4">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges5">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#DeveloperVisibleChanges4">Developer-Visible Changes</a>
@@ -80,7 +88,7 @@
 								<a href="#UserVisibleChanges5">User-Visible Changes</a>
 							</li>
 							<li>
-								<a href="#SpecifierVisibleChanges5">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges6">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#APIChanges">API Changes</a>
@@ -93,6 +101,13 @@
 		<p>This document contains the release notes for recent major releases of Sirius. See also 
 			<a href="Release_Notes_Previous.html">the release notes from previous versions</a> for details about older releases.
 		</p>
+		<h2 id="sirius3.1.6">Changes in Sirius 3.1.6</h2>
+		<h3 id="SpecifierVisibleChanges">Specifier-Visible Changes</h3>
+		<ul>
+			<li>The rules concerning the layout of compartments have been changed/completed. You can have a look at the 
+				<a href="specifier/diagrams/Diagrams.html#compartments_layout">dedicated chapter</a> in the specifier documentation for more details.
+			</li>
+		</ul>
 		<h2 id="sirius3.1.5">Changes in Sirius 3.1.5</h2>
 		<h3 id="UserVisibleChanges">User-Visible Changes</h3>
 		<ul>
@@ -105,7 +120,7 @@
 				<code>IPermissionAuthority</code>, the properties view will not be editable if this locked object is selected from the Model Explorer view, as it is the case for selection from dialect editors.
 			</li>
 		</ul>
-		<h3 id="SpecifierVisibleChanges">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges2">Specifier-Visible Changes</h3>
 		<ul>
 			<li><span class="label label-info">Modified</span> The 
 				<code>BorderSizeComputationExpression</code> migration has been corrected to recursively handle the sub container mappings. VSM created or migrated with Sirius 3.1 (3.1.0, 3.1.1 or 3.1.2) might require a manual modification for the style descriptions of sub container mappings with border size computation equals to 0 as we cannot determine if they were added (or updated) after or before the migration: starting with Sirius 3.1.0, no border will be displayed for a 0 pixel value whereas with older version container alwyas had at least a 1 pixel border. 
@@ -135,7 +150,7 @@
 			</li>
 		</ul>
 		<h2 id="sirius3.1.1">Changes in Sirius 3.1.1</h2>
-		<h3 id="SpecifierVisibleChanges2">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges3">Specifier-Visible Changes</h3>
 		<ul>
 			<li><span class="label label-info">Modified</span> The use of type literals in operations like filter() or oclIsKindOf() requires to explicitly add the domain meta-models plug-ins to the dependencies of the Viewpoint Specification Project. The documentation has been modified to recommend this.</li>
 		</ul>
@@ -197,7 +212,7 @@
 				<em>Arrange Linked Border Nodes</em> as it is border nodes which are layouted and not bordered nodes.
 			</li>
 		</ul>
-		<h3 id="SpecifierVisibleChanges3">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges4">Specifier-Visible Changes</h3>
 		<ul>
 			<li><span class="label label-info">Modified</span> The 
 				<em>Acceleo Query Language</em> (AQL) interpreter  has been improved. AQL, and its support in Sirius, is no longer considered experimental, and instead is now the recommended query language to use for new VSMs. Improvements mostly concern better completion and validation, and more precise error reporting. In particular AQL expressions will now be able to display warnings and errors in the Interpreter view. The message displayed in the Interpreter view after an evaluation has also been improved to display the qualified name of the type of the value computed (
@@ -718,7 +733,7 @@
 				<em>Viewpoint Selection</em> dialog and wizard page, the &#171;plug-in&#187; decorator for viewpoints loaded from plug-ins is removed, and a &#171;Folder&#187; decorator for viewpoints loaded from the current workspace has been added. This makes the icons more visible in the most common where viewpoints come from installed plug-ins.
 			</li>
 		</ul>
-		<h3 id="SpecifierVisibleChanges4">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges5">Specifier-Visible Changes</h3>
 		<ul>
 			<li><span class="label label-success">Added</span> <span class="label label-info">Experimental</span> Optional support for the experimental 
 				<em>Acceleo Query Language</em> (AQL) has been added to write interpreted expressions.  It is provided by the 
@@ -1694,7 +1709,7 @@
 			<li>Reconnection of an edge will only now move the minimum necessary bendpoints instead of reseting it to default.</li>
 			<li>A new action has been added to reset the diagram (or container) origin: the diagram (or container) bounds (the rectangle formed by the highest, the leftmost, the lowest and the rightmost children elements) can have a negative origin or can be shifted toward the bottom-right with a blank zone at the top-left. This action aims to move all diagram (or container) elements so that the it retrieves its origin while keeping elements layout.</li>
 		</ul>
-		<h3 id="SpecifierVisibleChanges5">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges6">Specifier-Visible Changes</h3>
 		<ul>
 			<li>The specifier can now choose to hold the edge ends toward the center of the source, target or both. New fields within the &#171;advance&#187; tab of EdgeStyle description have been added to choose for which source or target mappings an edge should be centered. See 
 				<a href="specifier/diagrams/Diagrams.html#edges_styles">Edges Styles &gt; Edge Centering</a> in the specifier manual for more details.
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
index 947a9d099e..84fa56d942 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -4,6 +4,12 @@ h1. Release Notes for Sirius
 
 This document contains the release notes for recent major releases of Sirius. See also "the release notes from previous versions":Release_Notes_Previous.html for details about older releases.
 
+h2(#sirius3.1.6). Changes in Sirius 3.1.6
+
+h3. Specifier-Visible Changes
+
+* The rules concerning the layout of compartments have been changed/completed. You can have a look at the "dedicated chapter":specifier/diagrams/Diagrams.html#compartments_layout in the specifier documentation for more details.
+
 h2(#sirius3.1.5). Changes in Sirius 3.1.5
 
 h3. User-Visible Changes
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.html b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.html
index f4fe9a547c..0adcad0081 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.html
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.html
@@ -657,6 +657,7 @@
 			<li>The Show/Hide, Hide filter features are disabled on regions (hide filter can be created to the compartment content but not the compartment). The Show/Hide label feature is supported.</li>
 			<li>The move and drag and drop of regions are disabled. Reordering regions can be done by reordering their semantic elements.</li>
 			<li>The resize of compartments might evolve in future versions. The current behavior is to redistribute space between adjacent regions and to resize the first/last region when the region container is resized from top/bottom for a vertical stack and left/right for an horizontal one.</li>
+			<li>A compartment is always considered as auto-sized (except after creation time when it contains no region).</li>
 			<li>The capability to define complex or recursive stack of regions mixing both stack directions has been introduced in Sirius 3.1.0 as an 
 				<em>experimental</em> configuration. Some layout-related actions might produce unexpected result. The limitations only concerns the visual aspects, there is no risk of corrupting the underlying models.
 			</li>
@@ -704,6 +705,81 @@
 		<p>Most of the properties used to configure the various styles are self-explanatory. See the 
 			<a href="#styling">styles</a> section below for a general discussion. You can also refer to the tool-tips available directly in the editor on the &#171;question mark&#187; icon of each property.
 		</p>
+		<h6 id="compartments_layout">Specific compartments layout</h6>
+		<p>Due to layout specificity of compartments, there are specific rules for this kind of containers:</p>
+		<ul>
+			<li>It is recommended to set to &#171;-1&#187; the 
+				<code>Width Computation Expression</code> and 
+				<code>Height Computation Expression</code>. The size of the compartment is expected to be computed from their regions.
+			</li>
+			<li>For the same reason, the 
+				<code>Width Computation Expression</code> should be the same for each region of the same vertical compartment (same 
+				<code>Height Computation Expression</code> for horizontal compartment ). If they are not the same the maximum is used.
+			</li>
+			<li>When a 
+				<code>Width Computation Expression</code> and 
+				<code>Height Computation Expression</code> are defined for the compartments, they are used at the creation time. You have the same effect if the end-user creates a compartment by drawing a rectangle for creation (instead of just clicking on the diagram). This dimension is kept for the first region creation. After the first region creation, the compartment is considered as auto-sized. A second region creation resizes the compartment (in the direction of the stack of the compartment).
+			</li>
+		</ul>
+		<p>Examples of some layout results according to VSM configuration:</p>
+		<ul>
+			<li>1st example:
+				<ul>
+					<li>Compartment with horizontal stack and with 
+						<code>Width Computation Expression</code> and 
+						<code>Height Computation Expression</code> equal to 10.
+					</li>
+					<li>Regions with 
+						<code>Width Computation Expression</code> and 
+						<code>Height Computation Expression</code> equal to 5.
+					</li>
+				</ul>
+			</li>
+		</ul>
+		<p>
+			<img border="0" src="images/compartmentsLayout-Creation1.png"/>
+			<br/>1- Creation of a compartment: The compartment has a size of 100x100 pixels. The result would be the same if the end-user drawn a rectangle of 100x100 pixels at the creation time.
+			<br/>2- Creation of a first region: The first region uses the free size of the compartment. The compartment keeps its size.
+			<br/>3- Creation of a second region: The second region uses the height of the first region (highest than the 50 pixels defined in the VSM) and has a width of 50 pixels. The compartment is increased in width.
+		</p>
+		<ul>
+			<li>2nd example:
+				<ul>
+					<li>Compartment with horizontal stack and with 
+						<code>Width Computation Expression</code> and 
+						<code>Height Computation Expression</code> equal to 10.
+					</li>
+					<li>Regions with 
+						<code>Width Computation Expression</code> and 
+						<code>Height Computation Expression</code> equal to 15.
+					</li>
+				</ul>
+			</li>
+		</ul>
+		<p>
+			<img border="0" src="images/compartmentsLayout-Creation2.png"/>
+			<br/>The first and second steps are the same. But the third is different. The second region has a width of 150 pixels and also a height of 150 pixels (highest than the first one). The compartment is increased in both directions.
+		</p>
+		<ul>
+			<li>3rd example:
+				<ul>
+					<li>Compartment with horizontal stack and with 
+						<code>Width Computation Expression</code> and 
+						<code>Height Computation Expression</code> equal to -1.
+					</li>
+					<li>Regions with 
+						<code>Width Computation Expression</code> and 
+						<code>Height Computation Expression</code> equal to 5.
+					</li>
+				</ul>
+			</li>
+		</ul>
+		<p>
+			<img border="0" src="images/compartmentsLayout-Creation3.png"/>
+			<br/>1- Creation of a compartment: The compartment is auto-sized and fits to the title.
+			<br/>2- Creation of a first region: The first region uses the width of the compartment (highest than the 50 pixels defined in the VSM) and has a height of 50 pixels. The compartment is increased in height.
+			<br/>3- Creation of a second region: The second region has a size of 50x50 pixels. The compartment is increased in both directions.
+		</p>
 		<h4 id="container_tools">Container Tools</h4>
 		<p>See the 
 			<a href="#tools">tools</a> section for a general presentation of how tools are defined. This section only presents tools which are specific to containers.
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.textile b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.textile
index 7384fb6fb9..1865c45e9e 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.textile
@@ -195,6 +195,7 @@ _Warning:_ The compartment feature has been introduced in Sirius 3.0.0. While wo
 * The Show/Hide, Hide filter features are disabled on regions (hide filter can be created to the compartment content but not the compartment). The Show/Hide label feature is supported.
 * The move and drag and drop of regions are disabled. Reordering regions can be done by reordering their semantic elements.
 * The resize of compartments might evolve in future versions. The current behavior is to redistribute space between adjacent regions and to resize the first/last region when the region container is resized from top/bottom for a vertical stack and left/right for an horizontal one.
+* A compartment is always considered as auto-sized (except after creation time when it contains no region).
 * The capability to define complex or recursive stack of regions mixing both stack directions has been introduced in Sirius 3.1.0 as an _experimental_ configuration. Some layout-related actions might produce unexpected result. The limitations only concerns the visual aspects, there is no risk of corrupting the underlying models.
 
 h4(#container_styles). Container Styles
@@ -216,6 +217,36 @@ You can specify the default size of _Gradient_ and _Parallelogram_ styles at cre
 
 Most of the properties used to configure the various styles are self-explanatory. See the "styles":#styling section below for a general discussion. You can also refer to the tool-tips available directly in the editor on the "question mark" icon of each property.
 
+h6(#compartments_layout). Specific compartments layout
+
+Due to layout specificity of compartments, there are specific rules for this kind of containers:
+* It is recommended to set to "-1" the @Width Computation Expression@ and @Height Computation Expression@. The size of the compartment is expected to be computed from their regions.
+* For the same reason, the @Width Computation Expression@ should be the same for each region of the same vertical compartment (same @Height Computation Expression@ for horizontal compartment ). If they are not the same the maximum is used.
+* When a @Width Computation Expression@ and @Height Computation Expression@ are defined for the compartments, they are used at the creation time. You have the same effect if the end-user creates a compartment by drawing a rectangle for creation (instead of just clicking on the diagram). This dimension is kept for the first region creation. After the first region creation, the compartment is considered as auto-sized. A second region creation resizes the compartment (in the direction of the stack of the compartment).
+
+Examples of some layout results according to VSM configuration:
+* 1st example:
+** Compartment with horizontal stack and with @Width Computation Expression@ and @Height Computation Expression@ equal to 10.
+** Regions with @Width Computation Expression@ and @Height Computation Expression@ equal to 5.
+!images/compartmentsLayout-Creation1.png!
+1- Creation of a compartment: The compartment has a size of 100x100 pixels. The result would be the same if the end-user drawn a rectangle of 100x100 pixels at the creation time.
+2- Creation of a first region: The first region uses the free size of the compartment. The compartment keeps its size.
+3- Creation of a second region: The second region uses the height of the first region (highest than the 50 pixels defined in the VSM) and has a width of 50 pixels. The compartment is increased in width.
+
+* 2nd example:
+** Compartment with horizontal stack and with @Width Computation Expression@ and @Height Computation Expression@ equal to 10.
+** Regions with @Width Computation Expression@ and @Height Computation Expression@ equal to 15.
+!images/compartmentsLayout-Creation2.png!
+The first and second steps are the same. But the third is different. The second region has a width of 150 pixels and also a height of 150 pixels (highest than the first one). The compartment is increased in both directions.
+
+* 3rd example:
+** Compartment with horizontal stack and with @Width Computation Expression@ and @Height Computation Expression@ equal to -1.
+** Regions with @Width Computation Expression@ and @Height Computation Expression@ equal to 5.
+!images/compartmentsLayout-Creation3.png!
+1- Creation of a compartment: The compartment is auto-sized and fits to the title.
+2- Creation of a first region: The first region uses the width of the compartment (highest than the 50 pixels defined in the VSM) and has a height of 50 pixels. The compartment is increased in height.
+3- Creation of a second region: The second region has a size of 50x50 pixels. The compartment is increased in both directions.
+
 h4(#container_tools). Container Tools
 
 See the "tools":#tools section for a general presentation of how tools are defined. This section only presents tools which are specific to containers.
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation1.png b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation1.png
new file mode 100644
index 0000000000..97a9a90b8d
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation1.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation2.png b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation2.png
new file mode 100644
index 0000000000..17274bba8a
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation2.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation3.png b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation3.png
new file mode 100644
index 0000000000..4cf6f91d13
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout-Creation3.png
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout.xcf b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout.xcf
new file mode 100644
index 0000000000..b9e9e90eda
--- /dev/null
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/images/compartmentsLayout.xcf