Eclipse Graphical Editing Framework (GEF)

The Eclipse Graphical Editing Framework (GEF) provides Eclipse-integrated end-user tools in terms of a Graphviz authoring (DOT editor, DOT Graph view) and a word cloud rendering environment (Tag Cloud view), as well as framework components (Common, Geometry, FX, MVC, Graph, Layout, Zest, DOT, and Cloudio) to create rich graphical JavaFX- and SWT-based client applications, Eclipse-integrated or standalone.

GEF participates in the annual Eclipse simultaneous release. Governance information can be found at [email protected], 'New and Noteworthy' in our CHANGELOG.

_{The current code base has been developed in parallel to that of the original Draw2d 3.x, GEF (MVC) 3.x, and Zest 1.x project components, which have been provided since 2004. Up to its graduation with the 4.0.0 (Neon) release in 2016, this code base had been referred to as 'GEF4' respectively org.eclipse.gef4, which is why these terms are still used in the 4.x (Neon) maintenance stream. In the 5.x (Oxygen) development stream, we have adopted the original project namespace to this code base, so that 'GEF' and org.eclipse.gef are now used instead, while we have started to refer to the original project components as 'GEF-Legacy', because they will only be maintained but are not developed further, providing their code base in the separate eclipse/gef-legacy repository.}

Installing the end-user tools (users)

You can install the DOT and Cloudio end-user tools (including the user guides) into your Eclipse installation via "Help -> Install New Software...", then pointing to one of the GEF update-sites¹⁾ and selecting the GEF DOT End-User Tools and GEF Cloudio End-User Tools features. Having completed the installation, the user guides can be accessed via Help -> Help Contents. They can also be accessed online in the GitHub Wiki, where they are maintained.

_{¹⁾ Please note that explicit end-user features (including the user guides) have only been created in the 5.x (Oxygen) development stream and are (for now) only available via the GEF (5.x) Master CI, GEF (5.x) Integration, and GEF (5.x) Milestones update-sites. If you want to install the end-user tools from the 4.x (Neon) maintenance stream, using the GEF4 Maintenance CI, GEF4 Integration, GEF4 Milestones, or GEF4 Releases update-site, you will have to select the GEF4 DOT, GEF4 DOT.UI, and GEF4 DOT User Guide, as well as the GEF4 Cloudio.UI and GEF4 Cloudio User Guide features instead. To access the related user documentation online, please refer to the deployed documentation at help.eclipse.org.}

Getting started with the framework components (adopters)

In order to develop graphical applications with GEF, you should first set up a proper development environment. The following sections shortly lay out how to set up an Eclipse IDE for this purpose. They conclude with running our deployed and undeployed examples to confirm everything is set up properly.

Having accomplished that, you might want to browse our developer documentation to learn about the framework components in detail. At any time, if you get stuck, feel free to contact us.

Set up an Eclipse IDE (using OpenJDK 11 and OpenJFX 11)

1. Install a recent OpenJDK (e.g. 11.0.2) and a matching OpenJFX SDK (e.g. 11.0.2) as a prerequisite.

2. Download a recent 'Eclipse IDE for Eclipse Committers' package (e.g. 2019-09 R) and start it, pointing to an empty workspace folder.

3. Select "Help -> Install New Software...". Choose to Work with https://download.eclipse.org/efxclipse/updates-nightly/site/, uncheck the Group items per category checkbox (the feature is uncategorized), and install e(fx)clipse - IDE - PDE.

4. Go to Windows -> Preferences -> Java/Installed JREs and ensure the installed OpenJDK is listed (otherwise add it manually).

5. Go to Windows -> Preferences -> Java/Installed JREs/Execution Environments and make sure JavaSE-1.8 is mapped to the installed OpenJDK (the checkbox needs to be checked, otherwise e(fx)clipse will not be able to resolve the JavaFX dependencies.)

6. Go to Windows -> Preferences -> JavaFX and make sure the JavaFX 11 + SDK setting points to the lib folder of your OpenJFX SDK.

7. Make sure to close your Eclipse instance and start it again (don't use the Restart menu entry).

Set up a Target Definition containing GEF (development snapshot)

1. Go to File -> New -> Project... and select to create a General/Project. Name it gef-integration.target or as you like, the project is to contain only a target definition.

2. Go to File -> New -> Other... then choose Plug-in Development/Target Definition and create a new empty (Nothing: Start with an empty target definition) target definition file named gef-integration.target within the newly created project.

3. Close the Target Editor that has automatically opened, open the target file with the Text Editor using the Open With context menu, then paste the following contents:³⁾

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <?pde version="3.8"?>
   <target name="gef-integration" sequenceNumber="1">
   <locations>
     <location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="planner" includeSource="true" type="InstallableUnit">
       <unit id="org.eclipse.fx.runtime.min.feature.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.sdk.ide" version="0.0.0"/>
       <unit id="org.eclipse.emf.mwe2.runtime.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.xtext.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.emf.sdk.feature.group" version="0.0.0"/>
       <repository location="https://download.eclipse.org/releases/2019-03"/>
     </location>
     <location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="planner" includeSource="true" type="InstallableUnit">
       <unit id="org.eclipse.gef.common.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.geometry.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.fx.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.mvc.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.mvc.examples.source.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.layout.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.graph.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.zest.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.zest.examples.source.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.dot.sdk.feature.group" version="0.0.0"/>
       <unit id="org.eclipse.gef.cloudio.sdk.feature.group" version="0.0.0"/>
       <repository location="http://download.eclipse.org/tools/gef/updates/integration"/>
     </location>
   </locations>
   </target>
   

4. Now open the gef-integration.target file with the Target Editor again, using the Open With context menu, let it fully resolve, then click Set as Target Platform (link in the upper right corner of the editor).

_{³⁾ If you want to develop against the 4.x (Neon) maintenance stream, you will have to use the GEF4 Integration update-site instead, and the unit ids have to be prefixed with org.eclipse.gef4 instead of org.eclipse.gef.}

Run the examples

As the deployed MVC Logo and Zest Graph examples are contained in the target definition, you only need to start a new Eclipse Runtime to run them:

1. Go to Run -> Run Configurations... then create a new Eclipse Application launch configuration.
2. On the Main tab, make sure the Execution environment points to at least JavaSE-1.8 .
3. On the Arguments tab, add -Dosgi.framework.extensions=org.eclipse.fx.osgi to VM arguments:, so that all JavaFX dependencies can be resolved wihtin the OSGi environment. If you are using OpenJDK / OpenJFX 11 or higher, further add -Defxclipse.java-modules.dir=/Library/Java/Extensions/javafx-sdk-11.0.2/lib (of course adjusting the path to point to your OpenJFX SDK lib folder)
4. Click Run.
5. Open the example views via Window -> Show View -> Other..., then selecting Other/GEF MVC Logo Example or Other/GEF Zest Graph Example.

The undeployed Geometry, FX, FX.SWT, Graph, Layout, Zest.FX, Zest.FX.JFace, DOT, and Cloudio.UI examples have to be checked out in source before. Using EGit this can easily be achieved as follows:

1. Go to File -> Import..., then select Git/Projects from Git, press Next >.
2. Select Clone URI, press Next >.
3. Paste https://github.com/eclipse/gef.git to the URI field , press Next >.
4. Select master branch, press Next >.⁴⁾
5. Confirm the local directory or change it as needed, press Next >.
6. Ensure Import existing Eclipse projects is checked, then select Working Tree and press Next >.
7. Select org.eclipse.gef.cloudio.examples.ui, org.eclipse.gef.dot.examples, org.eclipse.gef.fx.examples, org.eclipse.gef.fx.examples.swt, org.eclipse.gef.geometry.examples, org.eclipse.gef.graph.examples, org.eclipse.gef.layout.examples, org.eclipse.gef.zest.examples, and org.eclipse.gef.zest.examples.jface, press Finish.
8. Select an arbitrary example class, e.g. org.eclipse.gef.fx.examples.ConnectionSnippet, in the Package Explorer view and select Run As -> Java Application from the context menu.⁵⁾

_{⁴⁾ If you want to develop against the 4.x (Neon) maintenance stream, you will have to select the R4_0_maintenance branch instead, and all project names are still prefixed with org.eclipse.gef4 instead of org.eclipse.gef.}

_{⁵⁾ On MacOS, you will have to ensure that the Use the -XstartOnFirstThread argument when launching with SWT option is unchecked on the Arguments tab of the launch configuration, which was implicitly created, as pure JavaFX examples will otherwise not startup correctly. When starting examples that are based on the JavaFX-SWT-integration on the other hand (like e.g. org.eclipse.gef.fx.examples.swt.ButtonFXControlAdapterSnippet), the Use the -XstartOnFirstThread argument when launching with SWT option has to be enabled.}

How to proceed from here?

The first thing you will probably want to consult is the developer documentation, which explains the different framework components in detail. It is bundled by the individual SDK features that are available for the framework components and can be accessed via Help -> Help Contents if these features are installed into the Eclipse IDE (it is not sufficient to include them in a target definition for this purpose). It is further contributed to help.eclipse.org for each release, where it can be accessed online, and can further be accessed online in the GitHub Wiki, where it is maintained.⁶⁾

All further project information (forum, mailing list, issue tracker, update-site locations, release plans) can be retrieved from the project meta-data at projects.eclipse.org.

If you want to contribute, please consult the contributor guide.

_{⁶⁾ The developer documentation for the 4.x (Neon) stream is still available in its deployed form at help.eclipse.org. The related online sources in the GEF4 wiki have been removed after the final 4.1.0 (Neon.1) release of this stream had been published.}