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.
The GEF4 FX component provides useful additions around JavaFX as well as for integrating JavaFX with SWT. It is internally composed out of two modules, namely FX and FX.UI. There are also a couple of undeployed FX Examples and FX UI Examples.
The FX module of GEF4 FX provides enhancements for JavaFX, which can also be used independent of the Eclipse UI, e.g. visual anchors, gesture listeners, a connection implementation, or an IGeometry-based shape implementation.
FxBundle is the bundle activator.
- package: org.eclipse.gef4.fx.anchors
The Anchors package provides a visual anchor abstraction (IFXAnchor), a related abstract base implementation (AbstractFXAnchor), as well as concrete anchor implementations (FXStaticAnchor, FXChopBoxAnchor) to manage dynamic positioning of visuals in dependence of others.
IFXAnchor, AbstractFXAnchor, AnchorKey
IFXAnchor is associated with one anchorage visual and can provide positions for several anchored visuals. Every anchored visual, for which a position should be computed by the anchor, has to be attached to the anchor. In order to allow the computation of different positions for the same visual, the anchored is wrapped in an
AnchorKey, which combines a javafx.scene.Node with a java.lang.String role. For example, imagine a self-loop (an edge that connects a vertex to itself) where the same visual (the edge) is attached to one anchorage (the vertex) with two different roles: the start of the edge, and the end of the edge.
When attaching an
AnchorKey to an
IFXAnchor, you can pass-in an arbitrary info object. This object can be evaluated by anchor implementations, therefore, it is used to provide additional information about the anchored, where necessary (see FXChopboxAnchor for an example).
The abstract base implementation
AbstractFXAnchor triggers a re-computation for an attached
AnchorKey when the anchorage visual changes relative to the anchored visual or vice versa. This is realized using a VisualChangeListener. When an
AnchorKey is detached from an
IFXAnchor, no further computations will be performed for that
The anchorage visual and the positions for the anchoreds are managed using JavaFX Properties (JavaFX Properties and Binding), i.e. you can register change listeners and realize bindings based on those properties.
FXStaticAnchor is, conceivably, the most simple anchor implementation. It provides an anchor position based on a static reference position (either scene-global, or relative to its anchorage visual). This type of anchor proved itself useful as a placeholder when a position currently does not depend on an anchorage visual, but eventually will.
FXChopBoxAnchor uses reference points to compute the anchor position for the anchored visuals. One reference point is referred to as the anchorage reference point. This point is the same for every anchored. It is computed based on the geometry of the anchorage. In addition, every anchored specifies one reference point. One anchor position is computed for each pair of (anchorage-reference-point, anchored-reference-point).
The following paragraphs describe the anchor computation in detail.
Here you can see how a connection is rendered with the
FXChopBoxAnchor. The E letter shape is the anchorage visual. The blue point is the anchored visual. The green line is the connection from the anchored to the anchorage. Note that the connection is not drawn inside of the anchorage, but ends on its outline. We will see how this is implemented.
In addition to the previous screenshot, you can see the center point of the anchorage bounds here. When this point is inside of the anchorage, it is used as the anchorage reference point. If it would be used as the anchorage reference point in this case, then the connection would end at that point, i.e. in the middle of nowhere. That's why a better anchorage reference point has to be computed.
In order to find an anchorage reference point that actually is inside of the anchorage, the shape vertices of the anchorage are taken into consideration. You can see that the connection ends at one of those vertices. You may wonder how the vertex to use as the anchorage reference point is determined.
In addition to the vertices, you can see lines connecting the center of the bounds with each vertex. The lines indicate the distance of each vertex to the center. The vertex that is closest to the center is used as the anchorage reference point.
Two of the lines are highlighted and their distance is shown. The anchorage reference point is now determined (orange).
A second anchored reference point is added to demonstrate how the actual anchor position is determined. A line from each anchored reference point to the anchorage reference point is constructed and intersected with the anchorage's outline. The intersection point that is closest to the anchored reference point is used as the anchor position.
- package: org.eclipse.gef4.fx.gestures
The Gestures package provides abstractions to compose related atomic JavaFX events into gestures, i.e. FXMouseDragGesture, FXPinchSpreadGesture, and FXRotateGesture. A gesture is implemented as an abstract class, with different abstract methods for the various parts of the gesture, i.e.
release() in the case of an FXMouseDragGesture. Besides, every gesture provides a
setScene() method to register/unregister JavaFX event listeners.
FXMouseDragGesture reports mouse press, drag, and release events.
FXPinchSpreadGesture reports touch pinch and spread events, i.e. moving two fingers towards each other or away from each other.
FXRotateGesture reports touch rotate events, i.e. dragging two fingers around each other.
- package: org.eclipse.gef4.fx.listeners
VisualChangeListener examines a visual's bounds-in-local and local-to-parent-transform properties (JavaFX Properties) and reports all related visual changes. A bounds-in-local change occurs when the observed visual's effect, clip, stroke, local transformations, or geometric bounds change. A local-to-parent-transform change occurs when the observed visual undergoes a transformation change. Transformation listeners are registered for all visuals in the hierarchy up to (but excluding) the common parent of observed and a respective observer visual, so that all changes relative to the observer visual are recognized.
VisualChangeListener is realized as an abstract class (similar to the Gestures), which has to be subclassed by clients to provide concrete reactions to the visual changes.
- package: org.eclipse.gef4.fx.nodes
The Nodes package provides
- an adaptation of an org.eclipse.gef4.geometry.planar.IGeometry to javafx.scene.Node: FXGeometryNode
- a connection abstraction that is based on IFXAnchor: FXConnection
- a grid layer implementation: FXGridLayer
- a visual to display an image which is overlayed by another image on mouse hover: FXImageViewHoverOverlay
- a custom ScrollPane implementation: ScrollPaneEx
- utilities (picking nodes, querying the pointer location, transformations): FXUtils
FXGridLayer is a specific javafx.scene.layout.Pane, which displays a grid with constant spacing that can be used as a background grid.
ScrollPaneEx is an alternative to the javafx.scene.control.ScrollPane. It consists of two layers: 1) a scrolled pane, and 2) a scrollbars group. The scrollbars group contains the horizontal and vertical scrollbars. It is rendered above the scrolled pane. A content group is wrapped inside the scrolled pane and contains all content. A viewport transformation is applied to this content group, i.e. scrolling is separated from the viewport transformation.
ScrollPaneEx determines the scrollable bounds based on the content bounds and the viewport bounds (its size) and provides access to these bounds. It does also provide methods to compute a translation from a scrollbar ratio and vice versa.
FXImageViewHoverOverlay displays a base image, for which a mouse hover effect is realized that displays an overlay image instead of the base image during hovering. Transitioning from one image to the other is done by gradually changing the opacities of both images. In the given example, the base image is the grey X and the overlay image is the red X.
FXConnection, IFXDecoration, IFXConnectionRouter, FXPolyBezierConnectionRouter, FXPolylineConnectionRouter
FXConnection is an implementation of a connection with two endpoints and an arbitrary number of waypoints. One of the endpoints is referred to as the start point, the other one is referred to as the end point. The positions for endpoints and waypoints are computed using anchors, i.e. an
FXConnection provides one AnchorKey per point and manages one IFXAnchor per point. However, the API also allows directly specifying coordinates for each point, in which case an FXStaticAnchor is created internally. An
FXConnection works out-of-the-box in combination with FXChopBoxAnchor, i.e. it provides a special ReferencePointProvider implementation.
FXConnection can have a start decoration and an end decoration which are displayed at the start point, or end point, respectively. A decoration implements the
IFXDecoration interface. Decorations can be used to display an arrow at one end of a connection, for example.
FXConnection manages an FXGeometryNode, which is referred to as the curve node. The ICurve which is displayed by the curve node is computed by an
IFXConnectionRouter. The router receives the coordinates of all points of the connection (start point, way points, end point). Currently, two connection routers are provided: 1) the
FXPolylineConnectionRouter (default), and 2) the
FXPolyBezierConnectionRouter. The first one computes a org.eclipse.gef4.geometry.planar.Polyline (only straight line segments) from the given points while the second one computes a org.eclipse.gef4.geometry.planar.PolyBezier (consecutive Bezier curves with smooth continuity) from the given points.
FXUtils class contains utility functionality, such as querying the current mouse pointer location, picking nodes at a current position on the scene graph, and performing local-to-parent, local-to-scene, parent-to-local, and scene-to-local transformations of geometries (GEF4 IGeometry).
The FX.UI module of GEF4 FX provides enhanced support for integrating JavaFX with SWT and the Eclipse UI.
- package: org.eclipse.gef4.fx.ui.canvas
FXCanvasEx is a replacement for the javafx.embed.swt.FXCanvas, providing support for various functionality which is missing. The
FXCanvasEx forwards SWT GestureEvents (touch events) to JavaFX, notifies all SWT FocusListeners (additional to forwarding them to JavaFX), and supports changing the SWT Cursor based on the javafx.scene.Cursor.
- package: org.eclipse.gef4.fx.ui.controls
The Controls package provides a counterpart to the JavaFX/SWT integration, i.e. embedding SWT Controls into a JavaFX scene graph.
FXControlAdapter extends javafx.scene.layout.Region and allows to embed an SWT Control into a JavaFX scene graph. The control will automatically be re-created using an IControlFactory whenever the JavaFX scene graph changes, and its bounds will be updated whenever the
FXControlAdapter is resized or relocated.
IControlFactory is responsible for creating an SWT Control (for an FXControlAdapter).
- package: org.eclipse.gef4.fx.ui.gestures
The Gestures package provides support for the conversion of SWT GestureEvent (touch events) to corresponding JavaFX events when embedding a JavaFX scene graph into an SWT application (via javafx.embed.swt.FXCanvas).
SwtToFXGestureConverter can be used to register listeners on an javafx.embed.swt.FXCanvas for an automatic conversion of SWT GestureEvents to corresponding JavaFX events (javafx.scene.input.RotateEvent, javafx.scene.input.ScrollEvent, javafx.scene.input.SwipeEvent, javafx.scene.input.ZoomEvent). It is internally used by FXCanvasEx to transfer gesture events from SWT to JavaFX.