View source for Sirius/Tutorials/Mindstorms/VisualizationTool

=Visualization Tool=

==Objectives==
Create a basic Diagram to display the instructions of a Mindstorms choreography.
* Nodes 
** '''Grab''' actions
** '''Release''' actions
** '''GoForward''' actions
** '''Rotate''' actions
* Edges
** Link between an instruction and its '''next''' instruction 

[[File:Mindstorms-3-1.png]]

== Sirius concepts==
During this step, you will mainly use these Sirius concepts:
During this step, you will mainly use these Sirius concepts:
* '''Viewpoint Specification Project'''
** The Eclipse project that defines a Sirius modeling tool
** Contains a odesign file that describes the representations and Java services used by the tool
* '''Viewpoint'''
** A viewpoint defines Sirius representations (diagrams, tables, matrices, trees) dedicated to a specific need
* '''Diagram Description'''
** Describes a kind of graphical representation for your model
** It defines which  elements  to display on the diagram, how (style) and the tools to edit them
* '''Node'''
** Describes  model elements displayed via an image or a simple shape
** It defines how to find  the model elements to display 
** It defines a graphical style (shape, label, color, …)
* '''Relation Based Edge'''
** Describes the relation between two objects
** The relation can be computed
** It defines graphical style (color, line style, size, routing style, …)

==Video==
Watch the [https://youtu.be/hOU62wf3bYs video] (22'02)

[[File:MindstormsVideo3.png|link=https://youtu.be/hOU62wf3bYs]]

==Detailed script==
===Create a Sirius project and a first diagram definition===
* Select the '''Sirius''' perspective (button on the top right)
* Create a '''Viewpoint Specification Project''' named <code>fr.obeo.dsl.tuto.mindstorms.design</code>
** '''Viewpoint Specification Model name''': <code>mindstorms.odesign</code>
* Import the Archive File [https://www.eclipse.org/sirius/resources/mindstorms-tutorial/icons-designer.zip icons-designer.zip] into this project

'''Note''': all the next actions have to be performed in the '''.odesign file''' (except the creation of Java services)

* Update the '''Viewpoint''' created by default (<code>MyViewpoint</code>)
** '''Id''' = <code>Mindstorms</code>
** '''Model File Extension''' = <code>mindstorms</code>

* In this viewpoint, create a '''Representation''' of type '''Diagram Description''' 
** '''Id''' = <code>Choreography Diagram</code>
** '''Domain Class''' = <code>mindstorms::Choreography</code>
** Reference the '''mindstorms''' metamodel
*** in '''metamodels''' tab, add the <code>http://www.obeo.fr/dsl/mindstorms/1.0.0</code> package from the registry (enter <code>*mindstorms</code> in the selection field)

'''Note:''' from now, if you save the '''.odesign''' file, you should be able to create a blank '''Choreography Diagram''' on the sample model:

* Open the sample project and activate the '''Mindstorms''' viewpoint (right-click on the project + menu '''Viewpoint Selection''') 
* Create a diagram (right-click on the root '''Choreography''' in the Model Explorer and select '''New representation''') : this diagram is still empty because we didn’t define its structure yet
 
* Your environment should look like this:
** Split the editors zone to display both the '''mindstorms.odesign''' file and the newly created '''Choreography Diagram''' (drag to the right the diagram’s tab title)

[[File:Mindstorms-3-2.png|800px]]

===Display each kind of instruction with a dedicated icon===
* In the '''Default Layer''', create a '''Diagram Element''' of type '''Node''' that displays the '''Grab''' instructions of the current choreography
** '''Id''' = <code>CD_Grab</code> 
** '''Domain class''' = <code>mindstorms::Grab</code>
** '''Semantic Candidate Expression''' = <code>feature:instructions</code>

** Create a '''Style''' of type '''Workspace Image''' for this '''Node'''
*** '''Image Path''' = <code>Grab.svg</code> (prefixed by its path)
*** In the '''Label''' tab : '''Show Icon''' = <code>false</code>
*** Remove the value of '''Label Expression'''
*** '''Label Position''' = <code>border</code>

* Copy & Paste '''CD_Grab''' to create a '''Node''' that displays '''Release''' instructions
** Change these values on the '''Node''':
*** '''Id''' = <code>CD_Release</code>
*** '''Domain class''' = <code>mindstorms::Release</code>
** Change these values on the '''Workspace Image'''
*** '''Image Path''' = <code>Release.svg</code> (prefixed by its path)

* Copy & Paste '''CD_Grab''' to create a '''Node''' that displays '''GoForward''' instructions
** Change these values on the '''Node''':
*** '''Id''' = <code>CD_GoForward</code>
*** '''Domain class''' = <code>mindstorms::GoForward</code>
** Change these values on the '''Workspace Image'''
*** '''Image Path''' = <code>GoForward.svg</code> (prefixed by its path)
*** '''Label Expression''' = <code>aql:self.cm+' cm'</code>

* Copy & Paste '''CD_Grab''' to create a '''Node''' that displays '''Rotate''' instructions
** Change these values on the Node:
*** '''Id''' = <code>CD_RotateLeft</code>
*** '''Domain class''' = <code>mindstorms::Rotate</code>
*** In the '''Advanced tab''' : '''Precondition Expression''' = <code>aql:self.degrees>=0</code>
** Change these values on the '''Workspace Image'''
*** '''Image Path''' = <code>Rotate_Left.svg</code> (prefixed by its path)
*** '''Label Expression''' = <code>aql:if self.random then '?' else self.degrees+'°' endif</code>

* Create a '''Style Customizations''' section on the '''Default Layer''' and add a '''Style Customization''' to display a specific image for Rotate to right instructions
** '''Predicate Expression''' = <code>aql:self.degrees<0</code>
** Add a '''Property Customization (by expression)'''
*** '''Applied On''' = <code>Rotate_Left.svg</code>
*** '''Property Name''' = <code>workspacePath</code>
*** '''Value Expression''' = <code>/fr.obeo.dsl.tuto.mindstorms.design/icons/Rotate_Right.svg</code>

* Copy & Paste '''CD_Grab''' to create a '''Node''' that displays '''Choreography''' instructions
** Change these values on the Node:
*** '''Id''' = <code>CD_SubChoreography</code>
*** '''Domain class''' = <code>mindstorms::Choreography</code>
** Change these values on the '''Workspace Image'''
*** '''Image Path''' = <code>Choreography.svg</code> (prefixed by its path)
*** '''Label Expression''' = <code>feature:name</code>

* The diagram on the sample model should look like this:
** click on the '''Arrange All''' button if necessary (the first one on the left in the tabbar)

[[File:Mindstorms-3-3.png]]

===Display the relations between the instructions===
* Define a service that computes the next instruction of a given instruction.
** To be able to write Java code that references the Mindstorms concepts, declare the EMF implementation of the metamodel in the project
*** Edit the '''META-INF/MANIFEST.MF''' file 
*** In the '''Dependencies''' tab, add  <code>fr.obeo.dsl.tuto.mindstorms</code> to the '''Required Plugins'''
** Copy the source code of the '''Method''' named '''getNextInstruction''' from the file [https://www.eclipse.org/sirius/resources/mindstorms-tutorial/methods.txt methods.txt] into the class '''Services.java''' (in the '''src''' folder) 

 
* In the '''Default layer''', create a '''Relation Based Edge''' that displays the links between an '''Instruction''' and its '''next''' Instruction
** '''Id''' = <code>CD_Next</code>
** '''Source mapping''' = <code>CD_GoForward, CD_Grab, CD_Release, CD_RotateLeft, CD_RotateRight, CD_Choreography</code>
** '''Target mapping''' = <code>CD_GoForward, CD_Grab, CD_Release, CD_RotateLeft, CD_RotateRight, CD_Choreography</code>
** '''Target Finder Expression''' = <code>service:getNextInstruction()</code>
* In the '''Diagram Definition''', Create a '''Composite Layout''' to force linked objects to be displayed from left to right ('''Direction''' = <code>Left to Right</code>)

* The diagram on the sample model should look like this:

[[File:Mindstorms-3-1.png]]

==Installing the solution==

The solution of this step is provided in [https://www.eclipse.org/sirius/resources/mindstorms-tutorial/solution2.zip solution2.zip].

'''Warning''': If you delete your current design project and load the solution, you should close the sample project and reopen it, in order the new version to be taken into account