blob: 776e9ea3a5e13556d3c1d1e4d59146fc8a74e900 [file] [log] [blame]
<?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>viewpoint-eef</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="UsingtheExtendedEditingFrameworkwithSirius">Using the Extended Editing Framework with Sirius</h1>
<p>
<code>Authors</code> Goulwen Le Fur
</p>
<ol class="toc" style="list-style: disc;">
<li>
<a href="#UsingtheExtendedEditingFrameworkwithSirius">Using the Extended Editing Framework with Sirius</a>
<ol style="list-style: disc;">
<li>
<a href="#EEFPropertiesviewsandwizardsgeneration">EEF Properties views and wizards generation</a>
<ol style="list-style: disc;">
<li>
<a href="#InitializingandsettingupEEFmodels">Initializing and setting up EEF models</a>
</li>
<li>
<a href="#GeneratingEEFcode">Generating EEF code</a>
</li>
</ol>
</li>
<li>
<a href="#Settingupplugin.xmlfile">Setting up plugin.xml file</a>
<ol style="list-style: disc;">
<li>
<a href="#DeclaringAdapterFactoriesandPropertiesEditionPartProviders">Declaring AdapterFactories and PropertiesEditionPartProviders</a>
</li>
<li>
<a href="#Declaringpropertiessheets">Declaring properties sheets</a>
</li>
</ol>
</li>
<li>
<a href="#Testingpropertiesview">Testing properties view</a>
</li>
<li>
<a href="#Optionaltaskstabsoptimization">Optional tasks (tabs optimization)</a>
<ol style="list-style: disc;">
<li>
<a href="#MovingEEFpropertysheettabsontop">Moving EEF property sheet tabs on top</a>
</li>
<li>
<a href="#Multipletabs">Multiple tabs </a>
</li>
<li>
<a href="#ProgrammaticallyhideandshowEEFpropertysheettabs">Programmatically hide and show EEF property sheet tabs</a>
</li>
<li>
<a href="#HideSiriusbuiltinpropertysheetsectionsandthecorrespondingtabs">Hide Sirius built-in property sheet sections (and the corresponding tabs)</a>
</li>
</ol>
</li>
<li>
<a href="#OpeningEEFwizardonadoubleclick">Opening EEF wizard on a double click</a>
</li>
</ol>
</li>
</ol>
<p>The purpose of this
<strong>Quickstart</strong> is to present how to integrate <a href="http://www.eclipse.org/modeling/emft/?project=eef" target="_blank">EEF</a> properties views and wizards with a Sirius diagram representation.
</p>
<h2 id="EEFPropertiesviewsandwizardsgeneration">EEF Properties views and wizards generation</h2>
<p>The tutorial <a href="http://wiki.eclipse.org/EEF/Tutorials/First_Generation" target="_blank">EEF : First generation</a> describes the process to generate EEF properties views and wizards. Here is the main steps.</p>
<h3 id="InitializingandsettingupEEFmodels">Initializing and setting up EEF models</h3>
<p>Initialize EEF generation models with the action
<em>EEF &gt; Initialize EEF models</em> in the contextual menu of your genmodel file.
</p>
<p>
<img class="shadow" border="0" src="images/1 - Initializing EEF models.png"/>
</p>
<p>The created files use a simple strategy to define EEF properties. You can change theses settings to improve the logic of your properties.
<br/>If you plan to use EEF properties only in a designer (for diagrams, tables, ... but not on the EMF treeviewer), you can configure the Sirius contributor ID for the EEF views. Open the generated EEFGen model, under the root element
<em>Model</em>, select the
<em>Gen Edition Context</em> and set the value
<strong>org.eclipse.sirius.diagram.ui</strong> to the
<em>Descriptors contributorID</em> properties.
</p>
<p>
<img class="shadow" border="0" src="images/2 - VP Contributor ID.png"/>
</p>
<p>In order to
<strong>optimize EEF performance with Sirius</strong>, change the root class of the generated EEF components to a dedicated Sirius aware components. This can be done by defining the value of the
<em>Leaf Components Super Class</em> to
<strong>org.eclipse.sirius.eef.components.SiriusAwarePropertiesEditingComponent</strong>.
</p>
<p>
<img class="shadow" border="0" src="images/2-1 - Leaf Components.png"/>
</p>
<p>Another interesting properties can be changed in this model, the generation directory. Default initialization set this value to the folder
<em>src-gen</em> of the plug-in containing the EEF models.
</p>
<h3 id="GeneratingEEFcode">Generating EEF code</h3>
<p>Before lauching code generation, make sure the directory pointed by this value is in the build path of the plug-in.</p>
<p>Add a dependency to EEF runtime
<strong>org.eclipse.emf.eef.runtime</strong> to the plug-in where you will generate the code.
</p>
<p>
<img class="shadow" border="0" src="images/3 - EEF runtime dependency.png"/>
</p>
<h2 id="Settingupplugin.xmlfile">Setting up plugin.xml file</h2>
<p>EEF generates the java code needed for properties views and wizards. It generates also an sample
<em>plugin.xml</em> file with the extension points you have to declare.
</p>
<h3 id="DeclaringAdapterFactoriesandPropertiesEditionPartProviders">Declaring AdapterFactories and PropertiesEditionPartProviders</h3>
<p>First part of the generated
<em>plugin.xml</em> file (
<code>&lt;!-- EEF Extensions --&gt;</code> ) declare
<code>AdapterFactory</code> and
<code>PropertiesEditionPartProvider</code> needed by the EEF runtime. Copy this settings without any changes to the
<em>plugin.xml</em> file of your plug-in.
</p>
<p>
<img class="shadow" border="0" src="images/4 - Copying EEF extensions.png"/>
</p>
<h3 id="Declaringpropertiessheets">Declaring properties sheets</h3>
<p>Second part of the generated
<em>plugin.xml</em> file (
<code>&lt;!-- Tabbed properties views extension --&gt;</code>) has extensions for tabbed properties sheets.
</p>
<p>There is two options at this moment :</p>
<ul>
<li>if you have set the Sirius contributor idea during the EEF models initialization step, all you have to do is to copy the second part of the generated
<em>plugin.xml</em> file in your plugin.xml file
</li>
<li>if you haven&#8217;t set the Sirius contributor idea, you might want to use the EEF properties in several contexts. In this case, you have to duplicate the second part settings for each context (i.e. for each contributor ID you want to contribute EEF properties). And for each contributor ID you have to change the contributor ID field for each extension point :</li>
</ul>
<pre><code>
&lt;extension
point="org.eclipse.ui.views.properties.tabbed.propertySections"&gt;
&lt;propertySections
contributorId="org.eclipse.sirius.diagram.ui"&gt;
&lt;propertySection
class="org.eclipse.emf.samples.conference.parts.forms.ConferencePropertiesEditionPartForm"
filter="org.eclipse.emf.samples.conference.providers.ConferencePropertiesEditionProvider$EditionFilter"
id="org.eclipse.emf.samples.conference.section.Conference"
tab="Base"&gt;
&lt;/propertySection&gt;
</code></pre>
<pre> ...
</pre>
<pre><code> &lt;/propertySections&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<p>Note: this configuration can also be cloned to be used with Sirius tables and trees (by using the following property contributor ids
<br/>
<code>org.eclipse.sirius.table.ui.EditorID</code> and
<code>org.eclipse.sirius.tree.ui.EditorID</code>).
</p>
<p>A
<code>propertySection</code> must be declared for each
<strong>tab</strong> generated in the
<code>org.eclipse.ui.views.properties.tabbed.propertyTabs</code> extension.
</p>
<p>Note: if you have not set
<strong>Descriptors Contributor ID</strong> in the
<code>.eefgen</code> model and you override the
<code>org.eclipse.sirius.diagram.ui</code>,
<code>org.eclipse.sirius.table.ui.EditorID</code> or
<code>org.eclipse.sirius.tree.ui.EditorID</code> contributorId, do not forget to remove the use of
<code>org.eclipse.emf.eef.runtime.ui.utils.EEFLabelProvider</code> as labelProvider. Otherwise you will get a Sirius type name as title of the properties view instead of the type name of the semantic model element.
</p>
<h2 id="Testingpropertiesview">Testing properties view</h2>
<p>After this settings, the generated properties views must be available from a Sirius diagram. You can run an eclipse application to test it.</p>
<p>
<img class="shadow" border="0" src="images/5 - Properties view testing.png"/>
</p>
<h2 id="Optionaltaskstabsoptimization">Optional tasks (tabs optimization)</h2>
<h3 id="MovingEEFpropertysheettabsontop">Moving EEF property sheet tabs on top</h3>
<p>By default, the EEF property sheets tab appear at last in the properties tabs.</p>
<p>It is possible to move them to make them appear at the top of the tab list :</p>
<p>
<img class="shadow" border="0" src="images/6 - Property sheet on top.png"/>
</p>
<p>To do this, you have to modify the
<code>org.eclipse.ui.views.properties.tabbed.propertyTabs</code> section by changing the property category of your tabs. Instead of using the ones that have been created in the current
<code>plugin.xml</code> (through the
<code>org.eclipse.ui.views.properties.tabbed.propertyContributor</code> extension point), it is possible to use the ones defined by Sirius :
</p>
<ul>
<li>
<code>semantic &amp; extension</code>
</li>
<li>
<code>semantic</code>
</li>
<li>
<code>extension</code>
</li>
<li>
<code>behaviors</code>
</li>
<li>...</li>
</ul>
<p>(please refer to the
<code>plugin.xml</code> file of
<code>org.eclipse.sirius.diagram.ui</code> for a complete list).
</p>
<p>Example :</p>
<pre><code> &lt;extension
point="org.eclipse.ui.views.properties.tabbed.propertyTabs"&gt;
&lt;propertyTabs
contributorId="org.eclipse.sirius.diagram.ui"&gt;
&lt;propertyTab
label="Base"
category="semantic &amp;amp; extension"
id="Base"&gt;
&lt;/propertyTab&gt;
&lt;/propertyTabs&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<p>It is also possible to use the
<code>afterTab</code> property to manage precisely the position of the EEF tabs (to put a tab before the first tab, use the value
<code>top</code>).
</p>
<p>Example :</p>
<pre><code> &lt;extension
point="org.eclipse.ui.views.properties.tabbed.propertyTabs"&gt;
&lt;propertyTabs
contributorId="org.eclipse.sirius.diagram.ui"&gt;
&lt;propertyTab
afterTab="top"
label="Base"
category="semantic"
id="Base"&gt;
&lt;/propertyTab&gt;
&lt;/propertyTabs&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<h3 id="Multipletabs">Multiple tabs </h3>
<p>Several conditions have to be met in order to get several tabs for a given semantic
<code>EClass</code> :
</p>
<ol>
<li>First of all,
<strong>one view must exist</strong> in the
<code>View Repository</code> of the
<code>fs.components</code> file
<strong>for each tab that has to be shown</strong> for the given semantic
<code>EClass</code>
</li>
<li>The
<code>Properties Edition Component</code> associated to the semantic
<code>Eclass</code> must reference these views
</li>
<li>In the
<code>plugin.xml</code> file :
<ol>
<li>One
<code>propertyTab</code> XML node must exist for each expected tab (
<code>org.eclipse.ui.views.properties.tabbed.propertyTabs</code> extension point). The
<code>id</code> must match the view names in the EEF
<code>components</code> file.
</li>
<li>One
<code>propertySection</code> XML node must exist for each expected tab(
<code>org.eclipse.ui.views.properties.tabbed.propertySections</code> extension point), the
<code>tab</code> attribute referencing the tabs defined in the
<code>propertyTabs</code> section.
</li>
</ol>
</li>
</ol>
<p>To illustrate it, let&#8217;s imagine that we have a semantic model that describes a filesystem in which we want to get two tabs (
<code>File Basic</code> and
<code>File Advanced</code>) for the semantic
<code>File</code>
<code>EClass</code>.
</p>
<p>Let&#8217;s consider that we also have an
<code>components</code> file containing (at least) :
</p>
<ol>
<li>A view named
<code>File Basic</code>
</li>
<li>A view named
<code>File Advanced</code>
</li>
<li>A
<code>Properties Edition Component</code> binded to the semantic
<code>File</code>
<code>Eclass</code> and referencing both
<code>File Basic</code> and
<code>File Advanced</code> views
</li>
</ol>
<p>In the
<code>plugin.xml</code> file, the tabs declaration should appear like this (notice that in this sample we use Sirius categories in order to make our tabs appear at first as described in the previous paragraph, which is not mandatory) :
</p>
<pre><code>&lt;extension point="org.eclipse.ui.views.properties.tabbed.propertyTabs"&gt;
&lt;propertyTabs contributorId="org.eclipse.sirius.diagram.ui"&gt;
&lt;!--
Other declarations : Base, ...
--&gt;
&lt;propertyTab
label="File Advanced"
category="semantic &amp;amp; extension"
id="File Advanced"&gt;
&lt;/propertyTab&gt;
&lt;propertyTab
label="File Basic"
category="semantic &amp;amp; extension"
id="File Basic"&gt;
&lt;/propertyTab&gt;
&lt;/propertyTabs&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<p>And the property sections declaration should appear like this :</p>
<pre><code>&lt;extension point="org.eclipse.ui.views.properties.tabbed.propertySections"&gt;
&lt;propertySections contributorId="org.eclipse.sirius.diagram.ui"&gt;
&lt;!--
Other declarations : Base, ...
--&gt;
&lt;propertySection
class="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
filter="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
id="fileAdvanced"
tab="File Advanced"&gt;
&lt;/propertySection&gt;
&lt;propertySection
class="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
filter="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
id="fileBasic"
tab="File Basic"&gt;
&lt;/propertySection&gt;
&lt;/propertySections&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<p>Here is the result :</p>
<p>
<img class="shadow" border="0" src="images/7 - Multiple tabs.png"/>
</p>
<h3 id="ProgrammaticallyhideandshowEEFpropertysheettabs">Programmatically hide and show EEF property sheet tabs</h3>
<p>It is possible to hide and show EEF tabbed property sheet tabs by providing a filter to the property sections (
<code>org.eclipse.jface.viewers.IFilter</code>).
</p>
<p>The most simple way to do this is to create a class that extends
<code>org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection</code> (this class brings a utility method (
<code>resolveSemanticObject</code>)) that helps to retrieve the semantic object that is targeted by a Sirius UI part).
</p>
<p>Example #1 (based on a test of the semantic object) : </p>
<pre><code>public class SemanticBasedPropertySectionFilter extends PropertiesEditionSection {
@Override
public boolean select(Object toTest) {
EObject semanticObject = resolveSemanticObject(toTest);
if (semanticObject instanceof MySemanticEClass) {
boolean mustBeShown = true;
// Code here the conditional tests...
return mustBeShown;
}
return false;
}
}
</code></pre>
<p></p>
<p>Example #2 (based on a test of the Sirius diagram identifier) :</p>
<pre><code>public class SiriusIdBasedPropertySectionFilter extends IFilter {
@Override
public boolean select(Object toTest) {
EditPart editPart = (EditPart) toTest;
View view = (View) editPart.getModel();
Diagram diagram = view.getDiagram();
EObject element = diagram.getElement();
String diagramId = ((DDiagram) element).getDescription().getName();
return "&lt;my diagram id&gt;".equals(diagId);
}
}
</code></pre>
<p></p>
<p>The filter has to be referenced from the
<code>plugin.xml</code> file in the
<strong>
<code>filter</code>
</strong> attribute of the corresponding
<code>propertySection</code> :
</p>
<pre><code>&lt;propertySection
class="org.eclipse.emf.eef.runtime.ui.properties.sections.PropertiesEditionSection"
filter="org.mypackage.MyPropertySectionFilter"
id="fileBasic"
tab="File Basic"&gt;
&lt;/propertySection&gt;
</code></pre>
<p></p>
<h3 id="HideSiriusbuiltinpropertysheetsectionsandthecorrespondingtabs">Hide Sirius built-in property sheet sections (and the corresponding tabs)</h3>
<p>The current plugin (
<code>org.eclipse.sirius.eef.adapters</code>) provides an extension mechanism that allows one to hide several Sirius built-in sections (and the corresponding tabs).
</p>
<p>To be used, as a pre-requisite, a property section contributor must be defined (org.eclipse.ui.views.properties.tabbed.propertyContributor extension point) with the following section descriptor provider (
<code>org.eclipse.sirius.eef.section.SiriusFilteringSectionDescriptor</code>):
</p>
<pre><code>&lt;extension point="org.eclipse.ui.views.properties.tabbed.propertyContributor"&gt;
&lt;propertyContributor
contributorId="org.eclipse.sirius.table.ui.EditorID"
sectionDescriptorProvider="org.eclipse.sirius.eef.section.SiriusFilteringSectionDescriptor"&gt;
...
&lt;/propertyContributor&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<p>At this point, it is possible to declare which section have to be hidden for which contributor id. The following example shows how to hide the Semantic section from the Sirius diagrams property sheet and the Core and Semantic sections from the Sirius table property sheet :</p>
<pre><code>&lt;extension
point="org.eclipse.sirius.eef.adapters.sectionFilters"&gt;
&lt;propertyContributorFilters
contributorId="org.eclipse.sirius.diagram.ui"&gt;
&lt;sectionFilter
id="property.section.semantic"&gt;
&lt;/sectionFilter&gt;
&lt;/propertyContributorFilters&gt;
&lt;propertyContributorFilters
contributorId="org.eclipse.sirius.table.ui.EditorID"&gt;
&lt;sectionFilter
id="org.eclipse.sirius.table.ui.section.core"&gt;
&lt;/sectionFilter&gt;
&lt;sectionFilter
id="org.eclipse.sirius.table.ui.section.semantic"&gt;
&lt;/sectionFilter&gt;
&lt;/propertyContributorFilters&gt;
&lt;/extension&gt;
</code></pre>
<p></p>
<h2 id="OpeningEEFwizardonadoubleclick">Opening EEF wizard on a double click</h2>
<p>An external java call is available to open a EEF Wizard editing the current selected element. This action can be used for the double click. In a tool section, create a
<em>Double Click Descriptor</em> and name it
<strong>Open EEF Wizard</strong>. The
<em>operation</em> of this element is only an
<em>External Java Call</em>. Name it
<strong>Open EEF Wizard Action</strong> and define the
<em>id</em>
<strong>org.eclipse.sirius.eef.actions.openPropertiesWizard</strong>.
</p>
<p>Finally, make a reference to this descriptor from each mapping you want to have a EEF Wizard on double click.</p>
<p>
<img class="shadow" border="0" src="images/8 - Double click descriptor.png"/>
</p>
<p>A double click on the selected mapping must open a EEF Wizard</p>
<p>
<img class="shadow" border="0" src="images/9 - EEF Wizard on VP.png"/>
</p>
</body>
</html>