Difference between revisions of "GEF/GEF4/Geometry/Tutorial"

Revision as of 06:14, 5 March 2012

Description

This is a small tutorial for the GEF4 Geometry API.

REPL

The GEF 4 Geometry module includes an examples-package where you can find a graphical REPL (Read - Evaluate - Print - Loop). To try out the new API, just insert the code snippets given in this tutorial and see what happens :)

1. Class hierarchy

The GEF 4 Geometry API is based on a skeleton of interfaces and implementation categories. The interfaces classify the individual figures into groups as follows:

2. General behaviour

You can find all the shapes in the org.eclipse.gef4.geometry.shapes package. In the majority of cases, you will get along with those predeclared shapes. If you feel the need of another one that is not provided there, you can draw the joker (Path) which can be used to work with complicated composed shapes. But we will begin by demonstrating the other shapes first.

Shape construction

You are able to create a shape via its constructor:

   Point p1 = new Point(100, 100);
   Point p2 = new Point(200, 200);
   Line line = new Line(p1, p2);

Alternatively, every constructor is able to handle primitive data types:

   Line line = new Line(100, 100, 200, 200);
   Ellipse e = new Ellipse(100, 100, 100, 100); // x, y, w, h

Besides this constructor contract, each shape can bake a copy of its own via its getCopy() method.

   Line line2 = line.getCopy();

Transformations

If you want to transform a shape, there are several ways to do this. You may use...

• ...the general AffineTransform class using the shape.getTransformed(transformation) method
• ...short-cut methods for the individual tranformations

You can easily rotate a Rectangle by calling its getRotated(angle) method:

   Rectangle quad = new Rectangle(100, 100, 100, 100);
   Polygon rhomb = quad.getRotated(Angle.fromDeg(45));

As you can see, the resulting shape is not a Rectangle anymore. This is due to the fact, that Rectangles are always parallel to the x- and y-axis.

If you want to rotate a Rectangle by an integer multiple of 90° and get a Rectangle back, you have to use the polygon.getBounds() method on the Polygon that the getRotated(angle) method returns:

   Rectangle rect = new Rectangle(100, 100, 200, 50);
   Rectangle rotated = rect.getRotated(Angle.fromDeg(90)).getBounds();

Translation and scaling are directly available on each shape, too:

   Rectangle rect = new Rectangle(100, 100, 200, 50);
   Rectangle big = rect.getScaled(2);
   Rectangle small = rect.getScaled(0.5);
   Rectangle translated = rect.getTranslated(-50, 50);
   //...

Rotation and scaling do always use a relative point to rotate around and scale away from, respectively. If you omit it, the transformation will use the mid-point of the shape as the relative point for the transformation. This behaviour is considered to be least surprising, although some people might expect the scaling and the rotation to be relative to (0, 0) which is true for Points and Vectors.

Interaction of shapes

In addition to shape construction and shape transformations, figures can interact with each other. You can test them for intersection or overlap, and you can compute the points of intersection of two shapes and the overlapping section of two shapes, respectively.

To do so, the shapes implement various methods, namely intersects(), overlaps(), getIntersections() and getOverlap() which provide you with information on the relationship of two shapes.

For example, you may wish to compute the points of intersection between an ellipse an a line:

   Point[] intersections = ellipse.getIntersections(line);

Or you are dealing with two overlapping curves and you want to get the overlap:

   CubicCurve overlap = c1.getOverlap(c2);

Regions

TODO... delegates to the AWT functionality.