GEF/GEF4/Graphics

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 Graphics component provides a level of abstraction over different drawing toolkits (natives). At the moment, SWT and AWT backends are in development. Its goal is to be as complete as possible, i.e. you should have access to all the functionality that you have access to when working directly with one of the natives (SWT or AWT). Of course, this is not always viable. But we aim to provide at least the greatest common divisor of the functionality that is offered by the individual natives and additionally, decent simulations for operations which are not offered by all natives.

[Note: You can tryout the examples in your local GEF4 installation. Every example shown in this documentation exists in the org.eclipse.gef4.graphics.examples project under the org.eclipse.gef4.graphics.examples.doc package. The examples are easily found via their identification number which is written atop the source code.]

As you can see in this example, the SwtGraphics is an IGraphics implementation. It can be constructed via a SWT GC which is passed-in to the paintControl() event handler. The renderScene() method does not know anything about the actual IGraphics implemention that is used. That's why we would not need to adjust our rendering code when switching to AWT, for example. You may wonder why we have to call the cleanUp() method on the IGraphics. In the case of SWT, this is necessary to fully free the system resources that will be allocated during the rendering process.

When looking at the code, there are two important observations:

The GEF4 Geometry component is integrated into the IGraphics interface, so that we can easily display geometry objects. Notably, the power of the draw() and fill() operations is directly coupled with the power of the Geometry component. All drawing primitives, such as lines, rectangles, ellipses, and many more, are represented by corresponding Geometry objects.

The drawing operations of the IGraphics are influenced by a set of attributes which are managed by the IGraphics (draw-color, fill-color, etc.). A full set of attributes is referred to as a GraphicsState.

There are four different drawing operations available on an IGraphics: draw(), fill(), write(), and paint().

Using the IGraphics#draw(ICurve) and IGraphics#draw(Path) methods, you can display the (contour of the) passed-in geometry object.

For a reference of all available geometry objects, take a look at the GEF4 Geometry component (GEF/GEF4/Geometry).

Analogical, the IGraphics#fill(IShape), IGraphics#fill(IMultiShape), and IGraphics#fill(Path) methods will fill the interior of the passed-in geometry object.

Using the IGraphics#paint(Image) method, you can display the passed-in Image object.

Using the IGraphics#write(String) method, you can display the passed-in String object.

States Stack

The IGraphics interface provides a state-stack-mechanism which can be used to elegantly avoid setting some attributes manually. Moreover, this stack is qualified for the transformation matrix and the clipping area, because the corresponding objects are seldom set explicitly but rather modified based on their current values.

On the top of the stack is the currently in-use GraphicsState. This is the GraphicsState you are accessing when calling any of the IGraphics#get*(*), IGraphics#is*(*), or IGraphics#set*(*) methods. You can duplicate the currently in-use GraphicsState on the states stack by calling IGraphics#pushState(). If you wish to reactivate a previously stored GraphicsState, use the IGraphics#popState() method. It will remove the top stack element, leaving the previously pushed GraphicsState as the new top stack element. To reactivate a previously stored GraphicsState without taking it from the stack, you can use the IGraphics#restoreState() method.

// TODO: states tack example using push/pop/restore

Additionally, you can query an IGraphics for the currently in-use GraphicsState using the IGraphics#getState() method. Analogously, you can set the currently in-use GraphicsState for an IGraphics using the IGraphics#setState(GraphicsState) method.

// TODO: getState()/setState() example

IImageGraphics

The IImageGraphics interface extends the IGraphics interface. If you want to render into an Image you have to construct an IImageGraphics for that Image. You can easily create it using the IGraphics#createImageGraphics(Image) method.

When drawing into a destination Image using an IImageGraphics, the drawing operations may be deferred. You can force an update of the destination Image by calling IImageGraphics#updateImage() or when destructing the IImageGraphics using IImageGraphics#cleanUp().

GraphicsState

A GraphicsState represents one set of IGraphics attributes. The following list presents all available attributes, default values, and a short description of the attributes.

Draw-specific attributes:

Draw-Pattern = blackSpecifies the draw-pattern which consists of a Color, a Gradient, an Image, and a Mode. The pattern's mode specifies which of the three values (Color, Gradient, and Image) is queried for the drawing color.

LineCap = FLATSpecifies how to display unconnected end points of displayed lines. A FLAT LineCap will not extend a drawn line beyond its unconnected end points. A ROUND LineCap will draw a semi-circle at the unconnected end points of a displayed line. A SQUARE LineCap will extend a drawn line beyond its unconnected end points by half the line's width.

LineJoin = BEVELSpecifies how to display the connection point of two displayed lines. A BEVEL LineJoin fills the bent corner triangular. A MITER LineJoin fills the bent corner up to the intersection point of the two outermost lines if its distance to the middle intersection is less than or equal to the MiterLimit. In case of exceeding the MiterLimit, the BEVEL LineJoin is used.

Line-Width = 1Specifies the width of displayed lines.

Miter-Limit = 10Restricts the use of the MITER LineJoin, because for low intersection angles, the intersection point may lie far away from the original connection point. Its value is the maximal quotient of the distance between the intersection point and the connection point and the line width.

Fill-specific attributes:

Fill-Pattern = blackSpecifies the fill-pattern which consists of a Color, a Gradient, an Image, and a Mode. The pattern's mode specifies which of the three values (Color, Gradient, and Image) is queried for the filling color.

Write-specific attributes:

Write-Pattern = blackSpecifies the write-pattern which consists of a Color, a Gradient, an Image, and a Mode. The pattern's Mode specifies which of the three values (Color, Gradient, and Image) is queried for the color to write the text in.

InterpolationHint = QUALITYWhen displaying a transformed Image, the InterpolationHint specifies whether to apply a fast and low-quality (InterpolationHint#SPEED) interpolation, or to apply a slower but higher-quality (InterpolationHint#QUALITY) interpolation.

Xor-Mode-Emulation = falseIf enabled, xor-mode rendering is always emulated if the current native does not provide xor-mode rendering on all platforms. If disabled, xor-mode rendering may be emulated on some platforms but it is delegated to the current native when possible.

Pattern

// TODO: image fill example

// TODO: gradient write example

Font

package: org.eclipse.gef4.graphics.font

A Font object stores font family, size, and style.

Color

package: org.eclipse.gef4.graphics.color

A Color object stores the red, green, blue, and alpha component of a color in the RGBA color space.

Gradient

A Gradient object stores a linear or radial, cyclic or acyclic, multi-stop color gradient. Therefore it manages a list of gradient-stops which consist of a percentual distance from the gradient's start location and a Color object. The gradient-stops specify the colors of the gradient at the stops' distances. Note that no gamma-correction is applied to the gradients.

A linear gradient is defined by a start and an end Point. In the example, the top-left and top-right corners of the Rectangle to fill are used. The three stops define color transitions from white to red and from red to black.

A radial gradient is defined by an Ellipse (border) and a focus Point. The focus Point determines where the gradient starts, i.e. the percentual distance at that Point is 0. The three stops define color transitions from white to red and from red to black.

The CycleMode defines the colors of a gradient outside of the gradient area. For linear gradients, this is beyond their start and end points. For radial gradients, this is beyond their boundary (Ellipse). You can choose one of three CycleModes:

NO_CYCLEThe Color of the nearest gradient-stop is used outside of the gradient area.

REFLECTThe gradient-stops are reflected outside of the gradient area.

REPEATThe gradient-stops are repeated outside of the gradient area.

Image

package: org.eclipse.gef4.graphics.image

Image Operations

package: org.eclipse.gef4.graphics.image.operations

How to

The "How to..." sections explain how to use specific functionality of the GEF4 Graphics component. You can try out the various presented code snippets using the HowToSnippets demo in the org.eclipse.gef4.graphics.examples project under the org.eclipse.gef4.graphics.examples.doc package.

How to transform the coordinate system

How to use the states stack

How to do off-screen rendering

The IGraphics interface facilitates the creation of an IImageGraphics for the currently used native. The IImageGraphics is associated with an Image to draw into.

How to draw geometric primitives

How-to snippet 001

How-to snippet 002

The GEF4 Geometry component provides many geometric abstractions. It is integrated into the GEF4 Graphics component. Therefore, the GEF4 Graphics component allows for rendering those geometric abstractions. You can use the draw() and fill() methods of the IGraphics in order to draw the contour of a geometric abstraction or fill it with a color, a gradient, or an image.

The list of provided geometric primitives contains all of the standard geometric objects, such as arcs, lines, ellipses, paths, polygons, polylines, rectangles, and rounded rectangles. Complementary, additional abstractions for the use of Bezier curves are provided, namely curved-polygons and polybeziers where the edges are arbitrary Bezier curves.

As you can see, a Bezier curve approaches the polyline of its control points. The first control point is called the start point, the last control point is called the end point, and the intermediate control points are called the handle points of the Bezier curve. The number of control points determines the curve's degree. A degree 0 (1 control point) Bezier curve represents a single point. A degree 1 curve represents a straight line segment. Higher degree Bezier curves generally proceed along a meandering path.