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.