[499828] Complete documentation about compartments layout

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

8 files changed, 128 insertions, 8 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index 1b1008d4b4..de8c879d08 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -18,6 +18,9 @@
 							<li>
 								<a href="#UserVisibleChanges">User-Visible Changes</a>
 							</li>
+							<li>
+								<a href="#SpecifierVisibleChanges">Specifier-Visible Changes</a>
+							</li>
 						</ol>
 					</li>
 					<li>
@@ -27,7 +30,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>
@@ -41,7 +44,7 @@
 								<a href="#UserVisibleChanges3">User-Visible Changes</a>
 							</li>
 							<li>
-								<a href="#SpecifierVisibleChanges2">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges3">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#DeveloperVisibleChanges2">Developer-Visible Changes</a>
@@ -55,7 +58,7 @@
 								<a href="#UserVisibleChanges4">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>
@@ -69,7 +72,7 @@
 								<a href="#UserVisibleChanges5">User-Visible Changes</a>
 							</li>
 							<li>
-								<a href="#SpecifierVisibleChanges4">Specifier-Visible Changes</a>
+								<a href="#SpecifierVisibleChanges5">Specifier-Visible Changes</a>
 							</li>
 							<li>
 								<a href="#APIChanges">API Changes</a>
@@ -93,6 +96,12 @@
 				<em>Ctrl+HOME</em>.
 			</li>
 		</ul>
+		<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="sirius4.0.0">Changes in Sirius 4.0.0</h2>
 		<h3 id="UserVisibleChanges2">User-Visible Changes</h3>
 		<ul>
@@ -114,7 +123,7 @@
 				<code>Apply Appearance Properties</code> action has been modified to use the last selected element as base style instead of the first one.
 			</li>
 		</ul>
-		<h3 id="SpecifierVisibleChanges">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges2">Specifier-Visible Changes</h3>
 		<ul>
 			<li><span class="label label-success">Added</span> Sirius 4.0 introduces 
 				<strong>experimental</strong>  support for specifying the properties views of your modelers directly from inside the VSM. This feature uses the same dynamic approach as for specifying  diagrams, tables and trees, with a very flexible configuration language and no code generation involved (including live preview of any change). As of Sirius 4.0, this feature should be considered in an experimental  state with details subject to changes until Sirius 4.1, and is not installed by default. To install it, make sure either 
@@ -615,7 +624,7 @@
 				<em>Arrange Linked Border Nodes</em> as it is border nodes which are layouted and not bordered nodes.
 			</li>
 		</ul>
-		<h3 id="SpecifierVisibleChanges2">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges3">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 (
@@ -1145,7 +1154,7 @@
 				<em>Viewpoint Selection</em> dialog and wizard page, the &#8220;plug-in&#8221; decorator for viewpoints loaded from plug-ins is removed, and a &#8220;Folder&#8221; 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="SpecifierVisibleChanges3">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges4">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 
@@ -2121,7 +2130,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="SpecifierVisibleChanges4">Specifier-Visible Changes</h3>
+		<h3 id="SpecifierVisibleChanges5">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 &#8220;advance&#8221; 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 c56503535e..14c3320685 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -10,6 +10,10 @@ h3. User-Visible Changes
 
 * <span class="label label-info">Modified</span> The shortcut _Ctrl+&_, for "_Reset Origin_":./user/diagrams/Diagrams.html#reset_origin action, has been replaced by _Ctrl+HOME_.
 
+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(#sirius4.0.0). Changes in Sirius 4.0.0
 
 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 a419688198..6d4722ce65 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.html
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.html
@@ -672,6 +672,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>
@@ -719,6 +720,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 &#8220;question mark&#8221; 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 &#8220;-1&#8221; 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 a8c7e86063..ad6d5f0da5 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/diagrams/Diagrams.textile
@@ -197,6 +197,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
@@ -218,6 +219,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