Connections and Routing

Connections figures are used to display a line between two points. The Connection interface extends IFigure. The provided PolylineConnection  implementation can be used in most cases. The source and target endpoints of a connection are each defined using a ConnectionAnchor. These endpoints, along with any other points on the connection, are set by the connection's ConnectionRouter. Usually every connection in a drawing has the same router instance. Connections with common endpoints can share anchor instances as well.

Connection Usage

Connections are created and added just like any other figure. Usually, connections should be displayed above other elements of a drawing using Layers. Unlike normal figures, you must not set the bounds of a connection. Instead, you must provide the source and target anchors and let the connection router calculate the connection's points.  The connection then determines its own bounding box.

A connection has a simple router by default - one that can connect the source and target anchors. But additional routers are available and can be set on the connection. Some routers can handle constraints for the connection such as a list of bendpoints through which the connection passes. Note that when setting a routing constraint on a connection, you must first set the router which will use that constraint.

A convenient way to share the router with all connections and to place connections above the drawing is to use a ConnectionLayer. The layer has a connection router property which it shares with every child that's a connection. You can update this property and easily change every connection's router at once.

Routing and Anchors

A connection always has a router and it must set at least two points on the connection: the source and target endpoints. By default, or when set to null, the connection's routing will be performed by an internal default router. The ends are placed with the help of anchors. An anchor is a fixed or calculated location, usually associated with some figure. For example, the ChopboxAnchor finds the point at which a line going to the reference point intersects a box, such as the bounds of a figure. The reference point is either the anchor at the opposite end, or a bendpoint or some other point nearest to the anchor. Anchors notify the connection when their anchor points has changed.


A ChopboxAnchor calculates the connection endpoint by finding the reference's intersection with a rectangle

The router calculates the endpoints and any other points in the middle of the connection. It then sets the points on the connection by calling setPoints(PointList). The connection's existing point list can be reused to reduce garbage, but the points must be set on the connection anyway so that it knows about any changes made.

Adding Decorations and Children to Connections

Like most figures, PolylineConnection supports the addition of children. The children might be arrowheads or labels that decorate the connection. The placement of each type of decoration can vary, so a DelegatingLayout is used to delegate to each child's constraint object, a Locator. PolygonDecoration can be used to create render a rotatable shape at the end of a connection. The end of a connection can be labeled by adding a Label with a ConnectionEndpointLocator. A connection will extend its bounds beyond what would be required to paint just the polyline.


A connection with 2 child decorations

Connection Layout

Connections extend the process of validation and layout to include routing. Since layout is the process of positioning children, routing must come first. This allows a child's locator to operate on the connection's newly-routed points.

During the validation step, the connection must remember its old bounds and determine its new. It then must damage the appropriate regions on the update manager. The provided implementation does all of these things for you. It also requests revalidation according to certain events specific to connections, such as an anchor moving or the router changing.