Skip to content

Commit

Permalink
[403] Add a new FAQ page with the old FAQ & cookbook wiki pages content
Browse files Browse the repository at this point in the history 
Bug: #403
Signed-off-by: Pierre-Charles David <[email protected]>
  • Loading branch information
@pcdavid
pcdavid committed Sep 13, 2024
1 parent c9f090b commit ebf7310
Show file tree
Hide file tree
Showing 4 changed files with 255 additions and 0 deletions.
139 changes: 139 additions & 0 deletions plugins/org.eclipse.sirius.doc/doc/specifier/FAQ.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
<?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"/>
<title>FAQ</title>
<link type="text/css" rel="stylesheet" href="../resources/bootstrap.css"/>
<link type="text/css" rel="stylesheet" href="../resources/custom.css"/>
</head>
<body>
<h1 id="SiriusDesktopFAQ">Sirius Desktop FAQ</h1>
<p>This document answers some common questions that specifiers can have when creating advanced Sirius modelers.</p>
<h3 id="WhenIselectaelementinSiriusdiagramitreturnsainstanceofDDiagrambutiwanttogetinstancesofEObject.IsthereanywaytogetEObjectfromselectioninSiriusDiagram">When I select a element in Sirius diagram, it returns a instance of DDiagram, but i want to get instances of EObject. Is there any way to get EObject from selection in Sirius Diagram?</h3>
<p>All Sirius model elements which represent a semantic/domain element implement the
<code>org.eclipse.sirius.viewpoint.DSemanticDecorator</code> interface, which provides the
<code>getTarget()</code> method (actually an EMF EReference) to access the underlying
<code>EObject</code>.
</p>
<p>This is the case for:</p>
<ul>
<li>all &#8220;top-level&#8221; representations (diagrams, which in practice are instances of
<code>DSemanticDiagram</code> that inherit from
<code>DDiagram</code>; tables, instances of
<code>DTable</code>; and trees, instances of
<code>DTree</code>@);
</li>
<li>all the individual elements (
<code>DRepresentationElement</code>) inside these representations:
<code>DNodes</code> /@DContainer@ /@DEdges@ /etc. in diagrams,
<code>DLine</code> /@DColumn@ in tables, and
<code>DTreeItem</code> in tree representations.
<code>DRepresentationElement</code> also provides
<code>getSemanticElements()</code> to access the &#8220;secondary&#8221; associated semantic elements, if any (the ones specified via &#8220;Associated Elements Expressions&#8221; in the mapping definitions).
</li>
</ul>
<h3 id="RetrieveaDNodeoranotherSiriusrepresentationelementfromgivensemanticelement">Retrieve a DNode (or another Sirius representation element) from given semantic element</h3>
<p>This is the opposite operation of the previous section.</p>
<p>Sirius maintains an session-scoped inverse cross-referencer which can be used to find &#8220;who references who&#8221; even in the absence of explicit navigable references in the model.
<br/>Sirius representation elements have a reference to the semantic model they represents, so you can use it for this kind of task.
<br/>The most convenient way is to use the
<code>org.eclipse.sirius.business.api.query.EObjectQuery</code> :
</p>
<pre><code> Collection&lt;EObject&gt; result = new EObjectQuery(mySemanticElement).getInverseReferences(ViewpointPackage.Literals.DSEMANTIC_DECORATOR__TARGET);
</code></pre>
<p>Note that this will find all the
<code>DSemanticDecorators</code> which represent
<code>mySemanticElement</code> in the whole session (all representations included), which may or may not be what you want.
<br/>If you need more precision, you will have to filter the result (using
<code>EObjectQuery#getRepresentation(DRepresentation)</code> for example to restrict to a specific diagram).
</p>
<h3 id="Haveeditorpropertiesviewinreadonly">Have editor/properties view in read-only</h3>
<p>To control the permission on object edition, Sirius use an implementation of
<code>IPermissionAuthority</code> .
<br/>A default one named
<code>ReadOnlyPermissionAuthority</code> is used by Sirius, to enable the read-only mode you can the following code snippet:
</p>
<pre><code>IPermissionAuthority permissionAuthority = IPermissionAuthorityRegistry.getPermissionAuthority(session.getTransactionalEditingDomain().getResourceSet());
if (permissionAuthority instanceof ReadOnlyPermissionAuthority) {
((ReadOnlyPermissionAuthority) permissionAuthority).activate();
}
</code></pre>
<p>To better control permissions, you can provide your own
<code>IPermissionAuthority</code> implementation using the
<code>PermissionProvider</code> extension point.
</p>
<h3 id="Enabledirecteditonbeginendlabels">Enable direct edit on begin/end labels</h3>
<p>In addition to its &#8220;main&#8221; label, an edge on a diagram can also have optional labels at the beginning (source-side) and/or end (target-side).
<br/>However direct edit tools associate with the edge only allow to edit the main label, not the begin/end ones.
<br/>Currently the only way to overcome this limitation is to programmatically contribute additional edit policies on the corresponding GMF Edit Parts.
<br/>
<a href="https://github.com/ObeoNetwork/UML-Designer/">UML Designer</a> does this for UML associations: see the code
<a href="https://github.com/ObeoNetwork/UML-Designer/blob/master/plugins%2Forg.obeonetwork.dsl.uml2.design%2Fsrc%2Forg%2Fobeonetwork%2Fdsl%2Fuml2%2Fdesign%2Finternal%2Feditpart%2FUMLEditPartProvider.java">here</a> for how this can be implemented.
</p>
<h3 id="SetCoordinatesPositionatnodecreationusingaNodeCreationTool">Set Coordinates/Position at node creation using a Node Creation Tool</h3>
<p>You can define the location and size of additional created nodes/edges by using the &#8220;CreateView/CreateEdgeView&#8221; operation in the creation tool and calling a Java service to use
<code>org.eclipse.sirius.diagram.ui.business.api.view.SiriusLayoutDataManager</code> API.
<br/>Sirius will use this singleton to know the location and size with which to create the nodes/edges.
<br/>After having called
<code>CreateView</code> operation to get the
<code>DDiagramElement</code> created, you can call a Java service as sub operation (a
<code>ChangeContext</code> for example), and in this Java service call:
</p>
<pre><code>LayoutData layoutData = SiriusLayoutDataManager.INSTANCE.getData(createdView, true);
// Update the layout data
</code></pre>
<p>
<em>Warning</em>: The getData() method does not always return layout data as it does not always exist. See next section for another way of doing this.
</p>
<h3 id="SetCoordinatesPositionatnodecreationusinganexistingnode">Set Coordinates/Position at node creation using an existing node</h3>
<p>Inside a tool which creates a new node one can use an existing node to set the location and size of the node.
<br/>The tip is to inject a new
<code>RootLayoutData</code> into the
<code>SiriusLayoutDataManager</code> .
<br/>This layout data must concern the graphical container of the new node.
<br/>When Sirius creates the new node, it looks into the
<code>LayoutDataManager</code> if hints exist.
</p>
<p>The following method use an existing node to retrieve its location and size and use them to define the location and size of the next created node.
<br/>One could also modify the coordinates before putting them into the layout data manager.
<br/>The code uses the
<code>getEditPart()</code> method defined in the next section.
</p>
<pre><code>private void setGraphicalHintsFromExistingNode(DDiagramElement existingNode) {
// Give hints about location and size
IGraphicalEditPart editPart = getEditPart(existingNode);
if (editPart instanceof ShapeEditPart) {
ShapeEditPart part = (ShapeEditPart)editPart;
SiriusLayoutDataManager.INSTANCE.addData(new RootLayoutData(existingNode.eContainer(), part.getLocation(), part.getSize()));
}
}
</code></pre>
<h3 id="HowtogettheEditPartcorrespondingtoaDDiagramElement">How to get the EditPart corresponding to a DDiagramElement?</h3>
<pre><code> private IGraphicalEditPart getEditPart(DDiagramElement diagramElement) {
IEditorPart editor = EclipseUIUtil.getActiveEditor();
if (editor instanceof DiagramEditor) {
Session session = new EObjectQuery(diagramElement).getSession();
View gmfView = SiriusGMFHelper.getGmfView(diagramElement, session);
</code></pre> IGraphicalEditPart result = null;
if (gmfView != null &amp;&amp; editor instanceof DiagramEditor) {
final Map&lt;?, ?&gt; editPartRegistry = ((DiagramEditor) editor).getDiagramGraphicalViewer().getEditPartRegistry();
final Object editPart = editPartRegistry.get(gmfView);
if (editPart instanceof IGraphicalEditPart) {
result = (IGraphicalEditPart) editPart;
return result;
}
}
}
return null;
}
<h3 id="HowtogetallDiagramsinasession">How to get all Diagrams in a session?</h3>
<p>Use the
<code>DialectManager</code> singleton:
</p>
<pre><code>DialectManager.INSTANCE.getAllRepresentations(session);
</code></pre>
<p>Also, if you only need the Name/Description of all diagrams, it might be better to use</p>
<pre><code>DialectManager.INSTANCE.getAllRepresentationDescriptors(session);
</code></pre>
</body>
</html>
112 changes: 112 additions & 0 deletions plugins/org.eclipse.sirius.doc/doc/specifier/FAQ.textile
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
h1. Sirius Desktop FAQ

This document answers some common questions that specifiers can have when creating advanced Sirius modelers.

h3. When I select a element in Sirius diagram, it returns a instance of DDiagram, but i want to get instances of EObject. Is there any way to get EObject from selection in Sirius Diagram?

All Sirius model elements which represent a semantic/domain element implement the @org.eclipse.sirius.viewpoint.DSemanticDecorator@ interface, which provides the @getTarget()@ method (actually an EMF EReference) to access the underlying @EObject@.

This is the case for:
* all "top-level" representations (diagrams, which in practice are instances of @DSemanticDiagram@ that inherit from @DDiagram@; tables, instances of @DTable@; and trees, instances of @DTree@@);
* all the individual elements (@DRepresentationElement@) inside these representations: @DNodes@ /@DContainer@ /@DEdges@ /etc. in diagrams, @DLine@ /@DColumn@ in tables, and @DTreeItem@ in tree representations. @DRepresentationElement@ also provides @getSemanticElements()@ to access the "secondary" associated semantic elements, if any (the ones specified via "Associated Elements Expressions" in the mapping definitions).

h3. Retrieve a DNode (or another Sirius representation element) from given semantic element

This is the opposite operation of the previous section.

Sirius maintains an session-scoped inverse cross-referencer which can be used to find "who references who" even in the absence of explicit navigable references in the model.
Sirius representation elements have a reference to the semantic model they represents, so you can use it for this kind of task.
The most convenient way is to use the @org.eclipse.sirius.business.api.query.EObjectQuery@ :

bc.
Collection<EObject> result = new EObjectQuery(mySemanticElement).getInverseReferences(ViewpointPackage.Literals.DSEMANTIC_DECORATOR__TARGET);

Note that this will find all the @DSemanticDecorators@ which represent @mySemanticElement@ in the whole session (all representations included), which may or may not be what you want.
If you need more precision, you will have to filter the result (using @EObjectQuery#getRepresentation(DRepresentation)@ for example to restrict to a specific diagram).

h3. Have editor/properties view in read-only

To control the permission on object edition, Sirius use an implementation of @IPermissionAuthority@ .
A default one named @ReadOnlyPermissionAuthority@ is used by Sirius, to enable the read-only mode you can the following code snippet:

bc.
IPermissionAuthority permissionAuthority = IPermissionAuthorityRegistry.getPermissionAuthority(session.getTransactionalEditingDomain().getResourceSet());
if (permissionAuthority instanceof ReadOnlyPermissionAuthority) {
((ReadOnlyPermissionAuthority) permissionAuthority).activate();
}

To better control permissions, you can provide your own @IPermissionAuthority@ implementation using the @PermissionProvider@ extension point.

h3. Enable direct edit on begin/end labels

In addition to its "main" label, an edge on a diagram can also have optional labels at the beginning (source-side) and/or end (target-side).
However direct edit tools associate with the edge only allow to edit the main label, not the begin/end ones.
Currently the only way to overcome this limitation is to programmatically contribute additional edit policies on the corresponding GMF Edit Parts.
"UML Designer":https://github.com/ObeoNetwork/UML-Designer/ does this for UML associations: see the code "here":https://github.com/ObeoNetwork/UML-Designer/blob/master/plugins%2Forg.obeonetwork.dsl.uml2.design%2Fsrc%2Forg%2Fobeonetwork%2Fdsl%2Fuml2%2Fdesign%2Finternal%2Feditpart%2FUMLEditPartProvider.java for how this can be implemented.

h3. Set Coordinates/Position at node creation using a Node Creation Tool

You can define the location and size of additional created nodes/edges by using the "CreateView/CreateEdgeView" operation in the creation tool and calling a Java service to use @org.eclipse.sirius.diagram.ui.business.api.view.SiriusLayoutDataManager@ API.
Sirius will use this singleton to know the location and size with which to create the nodes/edges.
After having called @CreateView@ operation to get the @DDiagramElement@ created, you can call a Java service as sub operation (a @ChangeContext@ for example), and in this Java service call:

bc.
LayoutData layoutData = SiriusLayoutDataManager.INSTANCE.getData(createdView, true);
// Update the layout data

_Warning_: The getData() method does not always return layout data as it does not always exist. See next section for another way of doing this.

h3. Set Coordinates/Position at node creation using an existing node

Inside a tool which creates a new node one can use an existing node to set the location and size of the node.
The tip is to inject a new @RootLayoutData@ into the @SiriusLayoutDataManager@ .
This layout data must concern the graphical container of the new node.
When Sirius creates the new node, it looks into the @LayoutDataManager@ if hints exist.

The following method use an existing node to retrieve its location and size and use them to define the location and size of the next created node.
One could also modify the coordinates before putting them into the layout data manager.
The code uses the @getEditPart()@ method defined in the next section.

bc.
private void setGraphicalHintsFromExistingNode(DDiagramElement existingNode) {
// Give hints about location and size
IGraphicalEditPart editPart = getEditPart(existingNode);
if (editPart instanceof ShapeEditPart) {
ShapeEditPart part = (ShapeEditPart)editPart;
SiriusLayoutDataManager.INSTANCE.addData(new RootLayoutData(existingNode.eContainer(), part.getLocation(), part.getSize()));
}
}

h3. How to get the EditPart corresponding to a DDiagramElement?

bc.
private IGraphicalEditPart getEditPart(DDiagramElement diagramElement) {
IEditorPart editor = EclipseUIUtil.getActiveEditor();
if (editor instanceof DiagramEditor) {
Session session = new EObjectQuery(diagramElement).getSession();
View gmfView = SiriusGMFHelper.getGmfView(diagramElement, session);

IGraphicalEditPart result = null;
if (gmfView != null && editor instanceof DiagramEditor) {
final Map<?, ?> editPartRegistry = ((DiagramEditor) editor).getDiagramGraphicalViewer().getEditPartRegistry();
final Object editPart = editPartRegistry.get(gmfView);
if (editPart instanceof IGraphicalEditPart) {
result = (IGraphicalEditPart) editPart;
return result;
}
}
}
return null;
}

h3. How to get all Diagrams in a session?

Use the @DialectManager@ singleton:

bc.
DialectManager.INSTANCE.getAllRepresentations(session);

Also, if you only need the Name/Description of all diagrams, it might be better to use

bc.
DialectManager.INSTANCE.getAllRepresentationDescriptors(session);
3 changes: 3 additions & 0 deletions plugins/org.eclipse.sirius.doc/doc/specifier/Sirius Specifier Manual.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,9 @@ <h1 id="SiriusSpecifierManual">Sirius Specifier Manual</h1>
<em>Viewpoint Specification Models</em>
</a>, and the various languages supported.
</li>
<li>"
<strong>Frequently Asked Questions</strong>:FAQ.html answers some common questions that specifiers can have when creating advanced Sirius modelers.
</li>
</ul>
<p>For more information on Sirius, please refer to the
<a href="../user/Sirius%20User%20Manual.html">
Expand Down
1 change: 1 addition & 0 deletions plugins/org.eclipse.sirius.doc/doc/specifier/Sirius Specifier Manual.textile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ You will find the following sections:
* "*Model Operations*":general/Model_Operations.html describes the small language which can be used throughout "_Viewpoint Specification Models_":../Glossary.html#VSM to describe behavior (for example for tools).
* "*Colors*":general/Colors.html explains how colors can be specified for all kinds of representations.
* "*Queries and Interpreted Expressions*":general/Writing_Queries.html explains the general rules to follow to write the expressions used inside "_Viewpoint Specification Models_":../Glossary.html#VSM, and the various languages supported.
* "*Frequently Asked Questions*:FAQ.html answers some common questions that specifiers can have when creating advanced Sirius modelers.

For more information on Sirius, please refer to the "*Sirius User Manual*":../user/Sirius%20User%20Manual.html, which describes how end-users can use the designers you created.

Expand Down

0 comments on commit ebf7310

Please sign in to comment.