Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between pages "JAR Signing" and "GEF/Developer FAQ"

(Difference between pages)
 
(Coding)
 
Line 1: Line 1:
== Overview ==
+
= General =
We are working towards signing Eclipse builds.  The goal of signing is to allow users to verify that the content they obtain from eclipse.org and subsequently execute does indeed come from that source. Signing in a nutshell works as follows:
+
  
# Eclipse builds produce content in various forms (zips, update JARS)
+
== What is GEF ==
# The Eclipse Foundation produces a signature of the build content using its private key (signature = private key + content)
+
The [http://www.example.com Graphical Editing Framework] is an open source framework dedicated to providing a rich, consistent graphical editing environment for applications on the [http://www.eclipse.org/eclipse/index.php Eclipse Platform].
# User downloads build content and signatures from eclipse.org or from mirrors
+
# The Eclipse Foundation makes available a [http://en.wikipedia.org/wiki/Public_key_infrastructure public key] for verifying signatures
+
# User consults some trusted authority to verify that the public key does indeed belong to the Eclipse Foundation
+
# Verification is performed on the user's machine (signature + public key = hash of content)
+
  
== Signing ==
+
== Why should I use GEF? ==
 +
GEF enables developers to easily create rich graphical editors within Eclipse. GEF has been used to build a variety of applications, including state diagrams, activity diagrams, class diagrams, GUI builders for AWT, Swing and SWT, and process flow editors. For more information on GEF features, please see the [http://www.eclipse.org/gef/overview.html?cvsroot=Tools_Project Project Overview].
  
=== What gets signed? ===
+
== What version of Eclipse do I need? ==
 +
A given version of GEF requires the exact same version of the Eclipse Platform.  For example, GEF 3.0.1 requires Eclipse 3.0.1.
  
By default, every JAR pushed to an update site will be signed.  This includes JARs nested at arbitrary depth within other JARs. Some JARs may be excluded if there are technical or legal reasons why they cannot be signed.  In standalone zip distribtions, all JARed plugins will be signed, and un-JARed plugins will not be signed.
+
== How do I make a suggestion for this FAQ? ==
 +
This FAQ is hosted as a Wiki. Anyone can edit this page after creating an account.
  
=== How is signing done? ===
+
== Which operating systems does GEF support? ==
 +
GEF is written in pure Java and should run on all operating systems officially supported by the Eclipse platform. It's primarily tested on Windows and Linux (GTK and Motif). See the readme file that came with your installation of GEF for specific versions.
  
Signing is performed using the JDK's [http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/jarsigner.html jarsigner]. This tool signs JARs by producing a separate signature for every file in the JAR.  The signatures are put in the MANIFEST.MF file and in a separate signature file in the META-INF directory.  For optimization purposes, the signature of the MANIFEST.MF with all embedded signatures is also computed and placed in the signature file.
+
== How is GEF licensed? ==
 +
GEF if licensed in accordance with the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License]. Third party components built using GEF are made available under their own licenses.
  
=== Where is signing done? ===
+
----
  
A critical part of the security behind signing is that the private keys used to produce the signatures are held in a secure location and never transmitted or accessible via a network. To accomplish this, the signing must be done on a secure machine that has access to the private key.  The Eclipse Foundation has set up a machine with a signing script.  The build will upload content to be signed to this machine, and a script is run to perform the signing.  Access to this machine will be given to trusted parties that want to perform signing.
+
= Download and Install =
  
=== When is signing done? ===
+
== How do I Install GEF? ==  
  
Signing will be done as part of the build process. Because this adds a significant amount of time to the build process, the releng team is investigating streamlining the build process. The process of producing a signed build is:
+
=== Download the bits manually ===
 +
[http://download.eclipse.org/tools/gef/downloads/ Download] the version of GEF that matches your installation of Eclipse. (The SDK download contains documentation and source, while the runtime download does not.) Exit Eclipse and unzip into the "eclipse" directory's parent directory. Restart Eclipse and verify that everything is installed. To do so, go to Help->About Eclipse Platform->Plug-in Details. Check the following entries:
  
# Checkout source from eclipse.org CVS repositories to build machine
+
'''Provider'''        '''Plug-in name'''
# Run build and produce a single ZIP of all plugins in update site form (all plugins in JARs)
+
Eclipse.org       Draw2d
# Send build output to eclipse.org for signing
+
Eclipse.org        Draw2d Documentation (SDK only)  
# Send signed build to update site
+
Eclipse.org       Graphical Editing Framework
# Copy zip of signed JARs back to the build machine, and package standalone zips
+
Eclipse.org        Graphical Editing Framework Documentation (SDK only)
# Copy standalone zips to test machines for automated testing
+
Eclipse.org        Graphical Editing Framework SDK (SDK only)
  
Currently the Eclipse project build machine is located remote from the Eclipse Foundation servers. This means the Eclipse source has to be transferred across the Internet, and the build output needs to be transferred back to Foundation machines for signing. These two major network bottlenecks could be removed by also using Eclipse Foundation machines for building.
+
The following directories should be present in your eclipse/plugins directory:
 +
(Note: Version numbers may differ according to download. This list assumes Eclipse build 2.1.0):
  
=== What public key (certificate) do we use? ===
+
org.eclipse.draw2d.doc.isv_2.1.0 (SDK only)  
 +
org.eclipse.draw2d_2.1.0
 +
org.eclipse.gef.doc.isv_2.1.0 (SDK only)
 +
org.eclipse.gef.source_2.1.0 (SDK only)
 +
org.eclipse.gef_2.1.0
  
The Eclipse Foundation [https://bugs.eclipse.org/bugs/show_bug.cgi?id=130943 has purchased] a signing certificate from Verisign.  Content made available on Eclipse.org will be signed with the foundation certificate.  Note this doesn't preclude other parties from later signing the JARs with their own certificates.
+
The following directories should be present in your eclipse/features directory:
 +
(Note: Version numbers may differ according to download. This list assumes Eclipse build 2.1.0):
  
=== Where are the signatures stored? ===
+
org.eclipse.gef.source_2.1.0 (SDK only)
 +
org.eclipse.gef_2.1.0
  
The signatures are stored in the JAR file, both in the MANIFEST.MF, and in a separate signature file (currently Eclipse_.sf).
+
=== Use the Eclipse Update Manager ===
 +
1. Go to the Help / Software Updates / Find and Install..."
  
== Verification ==
+
2. Choose the "Search for new features to install" option
  
=== When does verification happen? ===
+
3. Add one of the update sites below.
  
Verification can happen any time.  The common times to perform verification are:
+
Release site:
* During update. Minimally, verification happens at the time the client obtains the signed content. The Eclipse update mechanism will perform verification of any update JARs that are signed, and will prompt the user for confirmation if the certificate used for signing is not trusted. 
+
http://download.eclipse.org/tools/gef/releases/update-site/site.xml
* At load-time.  It is sometimes desirable to perform verification at load time when classes are loaded from a JAR.  The default Java class loader performs this verification automatically for any signed JAR on the classpath.  The Eclipse class loader can also be configured to perform load-time verification, but it is optional.
+
* Manual user verification.  The Eclipse about dialog will be augmented to show what plugins are signed.  From this dialog the user should be able to manually perform verification of signed content if desired.
+
  
== Miscellaneous links ==
+
Milestone site:
 +
http://download.eclipse.org/tools/gef/milestones/update-site/site.xml
  
=== Eclipse Bugzilla reports ===
+
Update site for integration builds:
 +
http://download.eclipse.org/tools/gef/updates/site-interim.xml
  
{|
+
You could also take a look at the Callisto site which by design lines up all
|-
+
the components together for a particular milestone.
! Done || Description
+
http://download.eclipse.org/callisto/releases/
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=43889 OSGi Bundle signing bug report]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=78208 Runtime signing support]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=94461 Signing indicator in About dialog]
+
|-
+
| [[Image:check.gif]]
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=130943 Purchasing signing certificates]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=132046 Signing script to signal completion]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=132048 Starting signing immediately after signing script is called]
+
|-
+
| [[Image:check.gif]]
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=134264 Bug for installing Java 1.5 on signing server]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=135044 Bug for installing Improved signing/packing application on signing server]
+
|-
+
|
+
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=130383 Bug for using OSGi verification during update]
+
|}
+
  
=== Other signing links ===
+
== Why isn't GEF showing up in Eclipse? ==  
 +
After installing GEF by extracting it to the necessary directories, it may be necessary to accept the changes within Eclipse. This can be accomplished by going to Help->Software Updates->Manage Configuration and right-clicking on Eclipse Platform. Select "Detected Changes..." from the menu and click Finish to complete the installation. This is the most common cause of the install not showing up in the aforementioned Plug-in Details view.
  
* [https://www.verisign.com/products-services/security-services/code-signing/digital-ids-code-signing/index.html Verisign code signing products]
+
== How do I Run the Logic Example? ==
* [http://java.sun.com/j2se/1.5.0/docs/guide/security/time-of-signing.html Sun docs on timestamps in signatures]
+
[http://download.eclipse.org/tools/gef/downloads/ Download] the example that matches your version of GEF.  Exit Eclipse and unzip into the eclipse directory.  Restart Eclipse and verify it was installed by going to Help->About Eclipse Platform->Plug-in Details and checking for Logic GEF Example in the list.  Next, create a simple Project. Then run the Logic Wizard. The wizard can be found at File->New->Other (Control+N), under the Examples heading. Select the simple project as the container in which the wizard will place the example document. The document should open automatically when you press Finish.
* [http://opentsa.org/ Web site of open source time stamp protocol implementation]
+
 
* [http://www.digistamp.com/ Time stamping service]
+
== Where do I find the documentation? ==
 +
The 3.1 documentation is now available [http://help.eclipse.org/help31 online].  [[Image:help_menu-1.png]]
 +
 
 +
The latest documentation is available in the SDK download. After unzipping this build into your Eclipse installation directory, start Eclipse (and possibly restart after updating via the update manager), click on the Help menu and then Help Contents.
 +
 
 +
When the Help window opens, there will be a section called GEF and Draw2d Plug-in Developer Guide. [[Image:help_toc.png]]
 +
 
 +
In this section, you'll find Developer Guides which contain high-level descriptions of GEF and Draw2d, as well as API References containing javadoc. 
 +
[[Image:gef_dev_guide.png]]
 +
 
 +
== How do I checkout GEF via CVS? ==
 +
Open the CVS Repositories View using the Window menu.  Right-click on the view and select "New" --> "Repository Location..."
 +
Enter the data shown here. Check out both the GEF and Draw2d plug-ins from the head stream for the most recent versions.
 +
[[Image:FAQ_CVS.gif]]
 +
 
 +
----
 +
 
 +
= Developer =
 +
 
 +
== When should I use GEF and when should I use just Draw2d? ==
 +
The simple answer to this question lies in their names. Draw2d is for drawing. GEF (or Graphical Editing Framework) is for editing.
 +
 
 +
Draw2d is used for rendering and layout. If all you want is to display data, all you need is Draw2d. If, on the other hand, you want to be able to manipulate that data, you should use GEF. GEF adds important functionality for editing -- commands for changing your model, a palette and tools for selecting and manipulating the edit parts that represent your model, direct edit, accessibility support such as keyboard navigation, native drag and drop, and much more that I've probably missed.
 +
 
 +
There may be only a few of these functions that you need -- for instance, you may just want to add drag and drop support so that you can drag files from the navigator or a file explorer and drop them onto your application/view, but otherwise only need to display the dropped data and not manipulate it. This is where the line gets blurred. You'll need to weigh the advantages and disadvantages of both options. On the one hand, you could move to GEF, get a bunch of functionality that you don't need and increase the complexity of your code. Or you could stick with Draw2d and implement the functionality you need yourself, maintaining a much simpler implementation. For the above example, I would personally implement the drag and drop function myself and stick with Draw2d. However, you should also consider future needs. You may want more of these functions down the road and moving to GEF now may be helpful.
 +
 
 +
== How do I redistribute GEF with my application? ==
 +
First off, you should probably check out the [http://www.eclipse.org/legal/legalfaq.html Eclipse.org Legal FAQ], the [http://www-106.ibm.com/developerworks/library/os-cplfaq.html CPL FAQ], and/or the [http://www.eclipse.org/legal/cpl-v10.html CPL] itself. More information forthcoming.
 +
 
 +
== How do I ask questions? ==
 +
Questions about the use of GEF in user projects that are not addressed in this FAQ should be posted to the [news://news.eclipse.org/eclipse.tools.gef GEF newsgroup]. Questions and comments regarding the implementation of GEF itself should be posted to the [https://dev.eclipse.org/mailman/listinfo/gef-dev GEF mailing list].
 +
 
 +
== How do I report a bug or request a feature? ==
 +
GEF, like the Eclipse project, uses [http://www.bugzilla.org/ Bugzilla] as its bug and feature tracking system. Entering a bug\feature report is as simple as filling in a web form on the [http://dev.eclipse.org/bugs/ eclipse bugzilla page]. The first time you enter a bug you will need to [http://dev.eclipse.org/bugs/createaccount.cgi create a new bugzilla account] for yourself by providing an email address and choosing a password. Before submitting a bug, please be sure to check the list of [https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=GEF&short_desc=&short_desc_type=allwordssubstr&long_desc=&long_desc_type=allwordssubstr&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&order=Reuse+same+sort+as+last+time open GEF bugs] and [https://bugs.eclipse.org/bugs/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&product=GEF&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&changedin=7&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= recently closed GEF bugs].
 +
 
 +
== Can I develop a standalone GEF application without use of the Eclipse platform? ==
 +
The official answer is No, this is not supported. The main reason involves the use of an Eclipse-specific file titled plugin.properties which GEF uses for string externalizations. However, since GEF is an open source project, modifications to the GEF codebase could potentially allow a GEF editor external to Eclipse.
 +
 
 +
== How can I get started on my GEF-based editor? ==
 +
The best place to investigate initially is the [http://www.eclipse.org/gef/developer/faq.html#install_doc GEF documentation]. This provides high-level concepts of GEF and Draw2d. There is also a sample GEF editor that can be downloaded at the [http://download.eclipse.org/tools/gef/downloads/ GEF download page] . The source code is made entirely available.
 +
 
 +
----
 +
 
 +
= Coding =
 +
 
 +
== How do I instrument domain model changes that support undo/redo ==
 +
 
 +
You can define custom request types that represent model changes for your
 +
domain.  An example would be how the logic example increments / decrements
 +
the LED model item.  The IncrementDecrementAction creates a new request constant -->
 +
...
 +
request = new Request(INCREMENT_REQUEST);
 +
...
 +
 
 +
Then the request is sent to the selected objects on the diagram surface. If the selected object is an LEDEditPart, then it has a custom EditPolicy installed on it's EditPolicy.COMPONENT_ROLE (LEDEditPolicy) that is used to handle model changes.  This EditPolicy is instrumented to understand the INCREMENT_REQUEST in it's getCommand method. It then returns a custom command that can handle undo/redo that will get executed on the command stack. 
 +
 
 +
@see LEDEditPolicy#IncrementDecrementCommand
 +
 
 +
If the request is not understood by the selected EditPart (i.e. no EditPolicy installed on EditPolicy.COMPONENT_ROLE), then a null command is returned.  This can indicate to the action that it should be disabled for the user.
 +
 
 +
== How do I do move an element from one container to another ==
 +
If you're moving an element from one container into another, first you need to consider the model changes that persist the container changes.  To do that, an EditPolicy for removing the model element on the source (ContainerEditPolicy) is needed and an EditPolicy for adding the model element (XYLayoutEditPolicy).
 +
 
 +
If we consider moving a LED from the diagram to a Circuit:
 +
First to remove it from the owned container using the OrphanChildCommand in Logic designer which will remove it from the first container.
 +
@see LogicContainerEditPolicy#getOrphanChildrenCommand
 +
 
 +
Then it is added to the target container using an AddCommand
 +
@see LogicXYLayoutEditPolicy#getAddCommand
 +
 
 +
These instrument the model changes.  Then the EditParts will listen to the model changes accordingly.  Both the DiagramEditPart and CircuitEditPart are LogicContainerEditPart which override the method getModelChildren.  Subsequent calls to refreshChildren will synchronize the EditPart children with the model children.  Alternatively, for performance they can listen to the model changes specifically which will invoke addChild or removeChild based on the corresponding event.
 +
@see LogicEditPart@propertyChange
 +
 
 +
== How do I do "X" when the User double-clicks? ==
 +
Mouse events are handled by a Draw2D event dispatcher.  When using GEF, a DomainEventDispatcher is used which allows heterogeneous handling of mouse events.  Mouse presses in general can either be processed by a Figure, or by a Tool.  A double-click is also a click, so the first event is a MouseDown, followed by a DoubleClick event.  When a MouseDown is dispatched, the event dispatcher will continue to send events to either the Figure or Tool until the Mouse is released.  So this means if the Tool processes MouseDown, it continues to get DoubleClick, dragging, and MouseUp.  If a Figure consumes the MouseDown event, it will receive these events.
 +
 
 +
The GEF SelectionTool already processes double-click and will send a SelectionRequest to the target EditPart under the mouse of the type REQ_OPEN.  The request is sent by calling EditPart.performRequest(Request).  This is the preferred way to do something in response to double-clicks.
 +
 
 +
== How do I find the location of the context menu? ==
 +
Often, GEF clients want to know the location of the context menu so that, for instance, new parts can be created or pasted at that location. The context menu can be brought up via the keyboard (Shift+F10) and there's no guarantee that the mouse cursor will be over the editor (or even the active window) when the context menu comes up. Hence, we recommend to do this in a location-neutral manner. For instance, new parts can be added to the top-left visible corner of the selected container, or the location can be determined based on the location of the part that was copied.

Revision as of 16:36, 20 April 2006

General

What is GEF

The Graphical Editing Framework is an open source framework dedicated to providing a rich, consistent graphical editing environment for applications on the Eclipse Platform.

Why should I use GEF?

GEF enables developers to easily create rich graphical editors within Eclipse. GEF has been used to build a variety of applications, including state diagrams, activity diagrams, class diagrams, GUI builders for AWT, Swing and SWT, and process flow editors. For more information on GEF features, please see the Project Overview.

What version of Eclipse do I need?

A given version of GEF requires the exact same version of the Eclipse Platform. For example, GEF 3.0.1 requires Eclipse 3.0.1.

How do I make a suggestion for this FAQ?

This FAQ is hosted as a Wiki. Anyone can edit this page after creating an account.

Which operating systems does GEF support?

GEF is written in pure Java and should run on all operating systems officially supported by the Eclipse platform. It's primarily tested on Windows and Linux (GTK and Motif). See the readme file that came with your installation of GEF for specific versions.

How is GEF licensed?

GEF if licensed in accordance with the Eclipse Public License. Third party components built using GEF are made available under their own licenses.


Download and Install

How do I Install GEF?

Download the bits manually

Download the version of GEF that matches your installation of Eclipse. (The SDK download contains documentation and source, while the runtime download does not.) Exit Eclipse and unzip into the "eclipse" directory's parent directory. Restart Eclipse and verify that everything is installed. To do so, go to Help->About Eclipse Platform->Plug-in Details. Check the following entries:

Provider Plug-in name Eclipse.org Draw2d Eclipse.org Draw2d Documentation (SDK only) Eclipse.org Graphical Editing Framework Eclipse.org Graphical Editing Framework Documentation (SDK only) Eclipse.org Graphical Editing Framework SDK (SDK only)

The following directories should be present in your eclipse/plugins directory: (Note: Version numbers may differ according to download. This list assumes Eclipse build 2.1.0):

org.eclipse.draw2d.doc.isv_2.1.0 (SDK only) org.eclipse.draw2d_2.1.0 org.eclipse.gef.doc.isv_2.1.0 (SDK only) org.eclipse.gef.source_2.1.0 (SDK only) org.eclipse.gef_2.1.0

The following directories should be present in your eclipse/features directory: (Note: Version numbers may differ according to download. This list assumes Eclipse build 2.1.0):

org.eclipse.gef.source_2.1.0 (SDK only) org.eclipse.gef_2.1.0

Use the Eclipse Update Manager

1. Go to the Help / Software Updates / Find and Install..."

2. Choose the "Search for new features to install" option

3. Add one of the update sites below.

Release site: http://download.eclipse.org/tools/gef/releases/update-site/site.xml

Milestone site: http://download.eclipse.org/tools/gef/milestones/update-site/site.xml

Update site for integration builds: http://download.eclipse.org/tools/gef/updates/site-interim.xml

You could also take a look at the Callisto site which by design lines up all the components together for a particular milestone. http://download.eclipse.org/callisto/releases/

Why isn't GEF showing up in Eclipse?

After installing GEF by extracting it to the necessary directories, it may be necessary to accept the changes within Eclipse. This can be accomplished by going to Help->Software Updates->Manage Configuration and right-clicking on Eclipse Platform. Select "Detected Changes..." from the menu and click Finish to complete the installation. This is the most common cause of the install not showing up in the aforementioned Plug-in Details view.

How do I Run the Logic Example?

Download the example that matches your version of GEF. Exit Eclipse and unzip into the eclipse directory. Restart Eclipse and verify it was installed by going to Help->About Eclipse Platform->Plug-in Details and checking for Logic GEF Example in the list. Next, create a simple Project. Then run the Logic Wizard. The wizard can be found at File->New->Other (Control+N), under the Examples heading. Select the simple project as the container in which the wizard will place the example document. The document should open automatically when you press Finish.

Where do I find the documentation?

The 3.1 documentation is now available online. Help menu-1.png

The latest documentation is available in the SDK download. After unzipping this build into your Eclipse installation directory, start Eclipse (and possibly restart after updating via the update manager), click on the Help menu and then Help Contents.

When the Help window opens, there will be a section called GEF and Draw2d Plug-in Developer Guide. Help toc.png

In this section, you'll find Developer Guides which contain high-level descriptions of GEF and Draw2d, as well as API References containing javadoc. Gef dev guide.png

How do I checkout GEF via CVS?

Open the CVS Repositories View using the Window menu. Right-click on the view and select "New" --> "Repository Location..." Enter the data shown here. Check out both the GEF and Draw2d plug-ins from the head stream for the most recent versions. File:FAQ CVS.gif


Developer

When should I use GEF and when should I use just Draw2d?

The simple answer to this question lies in their names. Draw2d is for drawing. GEF (or Graphical Editing Framework) is for editing.

Draw2d is used for rendering and layout. If all you want is to display data, all you need is Draw2d. If, on the other hand, you want to be able to manipulate that data, you should use GEF. GEF adds important functionality for editing -- commands for changing your model, a palette and tools for selecting and manipulating the edit parts that represent your model, direct edit, accessibility support such as keyboard navigation, native drag and drop, and much more that I've probably missed.

There may be only a few of these functions that you need -- for instance, you may just want to add drag and drop support so that you can drag files from the navigator or a file explorer and drop them onto your application/view, but otherwise only need to display the dropped data and not manipulate it. This is where the line gets blurred. You'll need to weigh the advantages and disadvantages of both options. On the one hand, you could move to GEF, get a bunch of functionality that you don't need and increase the complexity of your code. Or you could stick with Draw2d and implement the functionality you need yourself, maintaining a much simpler implementation. For the above example, I would personally implement the drag and drop function myself and stick with Draw2d. However, you should also consider future needs. You may want more of these functions down the road and moving to GEF now may be helpful.

How do I redistribute GEF with my application?

First off, you should probably check out the Eclipse.org Legal FAQ, the CPL FAQ, and/or the CPL itself. More information forthcoming.

How do I ask questions?

Questions about the use of GEF in user projects that are not addressed in this FAQ should be posted to the GEF newsgroup. Questions and comments regarding the implementation of GEF itself should be posted to the GEF mailing list.

How do I report a bug or request a feature?

GEF, like the Eclipse project, uses Bugzilla as its bug and feature tracking system. Entering a bug\feature report is as simple as filling in a web form on the eclipse bugzilla page. The first time you enter a bug you will need to create a new bugzilla account for yourself by providing an email address and choosing a password. Before submitting a bug, please be sure to check the list of open GEF bugs and recently closed GEF bugs.

Can I develop a standalone GEF application without use of the Eclipse platform?

The official answer is No, this is not supported. The main reason involves the use of an Eclipse-specific file titled plugin.properties which GEF uses for string externalizations. However, since GEF is an open source project, modifications to the GEF codebase could potentially allow a GEF editor external to Eclipse.

How can I get started on my GEF-based editor?

The best place to investigate initially is the GEF documentation. This provides high-level concepts of GEF and Draw2d. There is also a sample GEF editor that can be downloaded at the GEF download page . The source code is made entirely available.


Coding

How do I instrument domain model changes that support undo/redo

You can define custom request types that represent model changes for your domain. An example would be how the logic example increments / decrements the LED model item. The IncrementDecrementAction creates a new request constant --> ... request = new Request(INCREMENT_REQUEST); ...

Then the request is sent to the selected objects on the diagram surface. If the selected object is an LEDEditPart, then it has a custom EditPolicy installed on it's EditPolicy.COMPONENT_ROLE (LEDEditPolicy) that is used to handle model changes. This EditPolicy is instrumented to understand the INCREMENT_REQUEST in it's getCommand method. It then returns a custom command that can handle undo/redo that will get executed on the command stack.

@see LEDEditPolicy#IncrementDecrementCommand

If the request is not understood by the selected EditPart (i.e. no EditPolicy installed on EditPolicy.COMPONENT_ROLE), then a null command is returned. This can indicate to the action that it should be disabled for the user.

How do I do move an element from one container to another

If you're moving an element from one container into another, first you need to consider the model changes that persist the container changes. To do that, an EditPolicy for removing the model element on the source (ContainerEditPolicy) is needed and an EditPolicy for adding the model element (XYLayoutEditPolicy).

If we consider moving a LED from the diagram to a Circuit: First to remove it from the owned container using the OrphanChildCommand in Logic designer which will remove it from the first container. @see LogicContainerEditPolicy#getOrphanChildrenCommand

Then it is added to the target container using an AddCommand @see LogicXYLayoutEditPolicy#getAddCommand

These instrument the model changes. Then the EditParts will listen to the model changes accordingly. Both the DiagramEditPart and CircuitEditPart are LogicContainerEditPart which override the method getModelChildren. Subsequent calls to refreshChildren will synchronize the EditPart children with the model children. Alternatively, for performance they can listen to the model changes specifically which will invoke addChild or removeChild based on the corresponding event. @see LogicEditPart@propertyChange

How do I do "X" when the User double-clicks?

Mouse events are handled by a Draw2D event dispatcher. When using GEF, a DomainEventDispatcher is used which allows heterogeneous handling of mouse events. Mouse presses in general can either be processed by a Figure, or by a Tool. A double-click is also a click, so the first event is a MouseDown, followed by a DoubleClick event. When a MouseDown is dispatched, the event dispatcher will continue to send events to either the Figure or Tool until the Mouse is released. So this means if the Tool processes MouseDown, it continues to get DoubleClick, dragging, and MouseUp. If a Figure consumes the MouseDown event, it will receive these events.

The GEF SelectionTool already processes double-click and will send a SelectionRequest to the target EditPart under the mouse of the type REQ_OPEN. The request is sent by calling EditPart.performRequest(Request). This is the preferred way to do something in response to double-clicks.

How do I find the location of the context menu?

Often, GEF clients want to know the location of the context menu so that, for instance, new parts can be created or pasted at that location. The context menu can be brought up via the keyboard (Shift+F10) and there's no guarantee that the mouse cursor will be over the editor (or even the active window) when the context menu comes up. Hence, we recommend to do this in a location-neutral manner. For instance, new parts can be added to the top-left visible corner of the selected container, or the location can be determined based on the location of the part that was copied.

Back to the top