Chapter 4: GEF Examples

---

In this chapter, we cover some more advanced Graphical Editing Framework subjects and present our solutions and example code for useful or frequently requested techniques.

4.1 Additional concepts

In this section we look at some GEF and Draw2D concepts and features in greater detail.

4.1.1 RootEditParts

The RootEditPart is at the root of the EditPart hierarchy. It is the link between your application's root edit part and the EditPartViewer. GEF provides a few RootEditPart implementations that you can use. In order to clear up any potential confusion about which RootEditPart is appropriate for your application, we summarize the features of the various implementations below.

The code snippet in Example 4-1 illustrates the essential steps in initializing a GEF application. Notice that in an actual application, these steps may be distributed across more than one method. It shows an instance of the root EditPart being created and used to initialize the GraphicalViewer.

Example 4-1: Configuring a RootEditPart

 EditDomain editDomain = new DefaultEditDomain(null); ScalableFreeformRootEditPart root = new ScalableFreeformRootEditPart(); GraphicalViewer viewer = new ScrollingGraphicalViewer(); viewer.createControl(parent); editDomain.addViewer(viewer); viewer.setRootEditPart(root); viewer.setEditPartFactory(new EditPartFactory()); 

In selecting a root EditPart, we can first eliminate the GraphicalRootEditPart class. This implementation has been deprecated and will eventually be removed from GEF. The equivalent functionality of this EditPart can be achieved by using a ScrollingGraphicalViewer with a ScalableRootEditPart.

The three root EditParts to consider using are:

• ScalableRootEditPart

• FreeformGraphicalRootEditPart

• ScalableFreeformRootEditPart

All three of these EditParts must be used with a ScrollingGraphicalViewer, and therefore they all support scrolling using scrollbars. The main deciding criteria are whether your application requires scalability or a freeform diagram.

Remember that a freeform diagram expands automatically in all directions as the user drags figures beyond the current bounds of the diagram. This feature is generally desirable whenever you want the user to control the placement of the figures in your application. On the other hand, if your application constrains the placement of graphical objects, for example, into cells of a grid, then the freeform feature might not be desirable. Table 4-1 summarizes the main characteristics of the three root EditParts.

Table 4-1: Root EditPart characteristics

EditPart	Primary Figure	Is freeform?	Is scalable?
ScalableRootEditPart	Viewport	no	yes
FreeformGraphicalRoot EditPart	FreeformViewport	yes	no
ScalableFreeformRoot EditPart	FreeformViewport	yes	yes

4.1.2 Coordinate systems

Figures have a protected method, useLocalCoordinates(), that allows subclasses of figure to choose a coordinate system for their child figures that is either absolute or relative to the parent figure. A figure whose parent uses local coordinates will have a bounds whose upper left coordinate will be (0,0).

A figure's getClientArea returns the rectangle in which child figures are visible. It is cropped by any border/insets that are in effect for the figure, and the origin of the rectangle is set to (0,0) if the figure is using local coordinates.

The figure class includes four methods for translating coordinates between relative and absolute coordinates:

• translateToParent() - translates a point in the figure's coordinates to its value in the parent's coordinates

• translateFromParent() - translates a point in the parent's coordinates to its coordinates in this figure

• translateToRelative(), translates an absolute coordinate to a coordinate that is relative to this figure, that is, recursively translates from parent

• translateToAbsolute() - translates a coordinate that is relative to this figure to an absolute coordinate, that is, recursively translates to parent

Anchors and locator reference points work with absolute coordinates. Hit testing uses local coordinates.

4.1.3 Layers

In 3.2, "Introduction to Draw2D" on page 93, we discussed support for graphical layers using the LayeredPanes and layers classes. This feature allows us to segregate graphical elements into layers based on their functionality, and then control their visibility, z-order, and targetability. In this section we look at some of the specific ways that layers are configured in GEF's root EditParts, and the possibilities for customizing this behavior.

GEF's root EditPart classes, ScalableRootEditPart, FreeformGraphicalRootEditPart, and ScalableFreeformRootEditPart classes all expose methods that allow subclasses to modify the structure of their layers. The protected methods createLayers() and createPrintableLayers() are where these classes set up their layers. The implementation of these methods in FreeformGraphicalRootEditPart is shown in Example 4-2. This is similar to the other EditPart classes, except that it does not include scaling support. Examining this code reveals the default layer organization in GEF:

• Only the primary and connection layers are printable.

• The feedback layer is on the top of the z-order, followed by the handle layer, and finally the printable layers.

• Within the printable layers, the connection layer is on top of the primary drawing layer.

Example 4-2: Layer creation methods in FreeformGraphicalRootEditPart

 protected void createLayers(LayeredPane layeredPane) {    layeredPane.add(getPrintableLayers(), PRINTABLE_LAYERS);    layeredPane.add(new FreeformLayer(), HANDLE_LAYER);    layeredPane.add(new FeedbackLayer(), FEEDBACK_LAYER); } /**  * Creates a layered pane and the layers that should be printed.  * @see org.eclipse.gef.print.PrintGraphicalViewerOperation  * @return a new LayeredPane containing the printable layers  */ protected LayeredPane createPrintableLayers() {    FreeformLayeredPane layeredPane = new FreeformLayeredPane();    layeredPane.add(new FreeformLayer(), PRIMARY_LAYER);    layeredPane.add(new ConnectionLayer(), CONNECTION_LAYER);    return layeredPane; } 

The EditParts that support scaling, that is, ScalableRootEditPart and ScalableFreeformRootEditPart, also contain the method:

    protected ScalableFreeformLayeredPane createScaledLayers(); 

By subclassing these root EditPart classes, you can gain control over the ordering of layers, or customize which layers are printable or scalable. There are probably few cases where it would be useful to modify the configuration of the "stock" layers. One application that has been discussed is to place connections under rather than over the primary figure layer. Although this can have some aesthetic advantages, if you are considering this, keep in mind that it will be possible for your figures to completely cover connections, making them difficult to access. It becomes more problematic when your application includes container nodes, because connections between nodes in a container will be occluded.

A more likely customization scenario is to create additional, custom layers, for example, to provide annotation layers that can be turned on and off, and selectively printed.

---