GEF/GEF4/SwtFX

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page.

Introduction

The GEF4 SWT-FX component provides abstractions for the combined rendering of lightweight (shape and canvas figures) and non-lightweight (SWT widgets) objects. The API is inspired by concepts of JavaFX, such as the event system (event bubbling and capturing). It is intended to replace the core of Draw2d.

The component is subdivided into different packages:

• org.eclipse.gef4.swt.fx, partially implemented
  Contains classes and interfaces for the combined rendering of ligthweight IFigures and heavyweight SWT widgets. This is accomplished by hooking in the SWT widget hierarchy.
• org.eclipse.gef4.swt.fx.events, partially implemented
  Contains the event system of the component. It is highly inspired by the JavaFX event system.
• org.eclipse.gef4.swt.fx.gc / org.eclipse.gef4.swt.fx.canvas, implemented
  Contains a GraphicsContext implementation similar to the JavaFX GraphicsContext2D using SWT under the hood. (Much source code of the old Graphics component found its way into this package.)
• org.eclipse.gef4.swt.fx.layout, planned
  Contains default layout managers and corresponding functionality.

Key abstractions

The SWT-FX component uses a Group widget as the root of its hierarchy. This Group extends the SWT Composite class. Therefore you can create it just like any other SWT widget and you can put any other SWT widget into it.

(Side note, event system: Although also SWT widgets can be placed in a Group, only INodes can use the event system provided by the component.)

[SWT Control] <|--- [SWT Composite] <|--- [Group] -.-|> [INode]
[Group] ---> * [IFigure]
[Group] ---> * [SWT Control]
[IFigure] -.-|> [INode]

As you can see in this diagram, a Group is used as a container for IFigures and SWT widgets. An IFigure, on the other hand, cannot be used as a container. This distinction reduces complexity.

IFigure

An IFigure represents a visual on the screen. There are two IFigure implementations available per default:

• A ShapeFigure consists of a geometric object such as Rectangle, Ellipse, or Line. It is used to display that shape.
• A CanvasFigure consists of a raster image to draw into using a GraphicsContext.

IFigure: IBounds:

+ getBounds() : IBounds                     + getShape() : IShape
+ getPaintState() : GraphicsContextState    + getTransform() : AffineTransform
+ paint(GraphicsContext)                    + getTransformedShape() : IShape
+ requestFocus() : boolean
+ update()

As you can see in this diagram, each IFigure is associated with an IBounds and a GraphicsContextState. The IBounds describe the IFigures bounding shape. The IBounds are used in hit testing, etc. The GraphicsContextState stores all graphics related attributes of an IFigure, such as the drawing color, or the font size. The paint(GraphicsContext) method is called to draw the IFigure using the passed-in GraphicsContext.

Group

A Group serves as a general container for heavyweight SWT widgets and lightweight GEF4 figures.

Group:

+ addFigures(IFigure...)
+ getFigureAt(Point) : IFigure
+ getFigures() : List<IFigure>
+ setFocusFigure(IFigure) : boolean

Event system

The provided event system is similar to JavaFX's event system:

   [TODO: class diagram of our event system]
   [MAYBE: comparison to JavaFX]

In comparison to SWT, the event system uses typed event objects, exclusively. The event object classes are organized hierarchical, so that you can define event listeners for "superordinate" event types.

   [Event] <|--- [InputEvent] <|--- [MouseEvent]
                              <|--- [KeyEvent]

   (fig: InputEvent is a superordinate event type.)

If several event listeners can react to an occured event, the one with the most special event type will be called first. Assuming you would define an event listener for InputEvents and a listener for MouseEvents, the MouseEvent listener would be called before the InputEvent listener, when a MouseEvent occurs.

To be able to react to events, you have to implement the IEventTarget interface. An IEventTarget is responsible for building an EventDispatchChain. In general, all the parent nodes (up to the root) are prepended to the EventDispatchChain. INode extends the IEventTarget interface, therefore Group and IFigure are already able to react to events.

Every INode manages an IEventDispatcher to add and remove event listeners to the node and to dispatch incoming events to the correct listeners. The IEventDispatcher differentiates between event handlers and event filters. Both are implementations of the IEventHandler interface, but they are executed during different phases of event propagation.

1. Target Selection
   When an event occurs, the event target (Group or IFigure) is determined at
   first. Several rules exist to select the target:
    * keyboard events => focus target
    * mouse events => mouse target
    * other => cursor target

2. Route Construction
   The selected IEventTarget is utilized to get the EventDispatchChain for
   further event processing.

3. Event Capturing
   The event object travels along the EventDispatchChain -- usually starting at
   the root -- up to the event target. On its way, all registered event filters
   can process, and eventually consume, the event. Event processing terminates,
   if an event is consumed.

4. Event Bubbling
   If the event reaches the selected IEventTarget, it will travel down the
   EventDispatchChain down to the root. On its way, all registered event
   handlers can process, and eventually consume, the event.