[495119] Complete documentation about compartments layout

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

8 files changed, 114 insertions, 0 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index ccb1043b0f..70611da4ed 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -102,6 +102,11 @@
 			<code>ViewpointRegistry</code> will not register it and a warning is logged in the error log view to inform the user.
 		</p>
 		<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>
 		<h3 id="DeveloperVisibleChanges">Developer-Visible Changes</h3>
 		<h4 id="Changesinorg.eclipse.sirius">Changes in 
 			<code>org.eclipse.sirius</code>
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
index 4a0c7a648f..660a4b682d 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -14,6 +14,8 @@ If a viewpoint  has been defined with a more recent version of Sirius than the o
 
 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.
+
 h3. Developer-Visible Changes
 
 h4. Changes in @org.eclipse.sirius@
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