Package org.eclipse.gef.fx.nodes

Class Connection

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.Group
org.eclipse.gef.fx.nodes.Connection
All Implemented Interfaces:
javafx.css.Styleable, EventTarget
public class Connection extends Group
A (binary) Connection is a visual curveProperty, whose appearance is defined through a single start and end point, and a set of control points, which may be 'connected', i.e. be attached to an IAnchor. The exact curveProperty shape is determined by an IConnectionRouter, which is responsible of computing an ICurve geometry for a given Connection (which is then rendered using a GeometryNode).

Whether the control points are interpreted as way points (that lie on the curveProperty) or as 'real' control points depends on the IConnectionInterpolator. While PolylineInterpolator and PolyBezierInterpolator interpret control points to be way points, other routers may e.g. interpret them as the control points of a BezierCurve.

In addition to the curveProperty shape, the visual appearance of a Connection can be controlled via start and end decorations. They will be rendered 'on-top' of the curveProperty shape and the curveProperty shape will be properly clipped at the decorations (so it does not paint through).

  • Property Details

  • Constructor Details

    • Connection

      public Connection()
      Constructs a new Connection whose start and end point are set to null.

  • Method Details

    • addAnchor

      protected void addAnchor(AnchorKey anchorKey, IAnchor anchor)
      Inserts the given IAnchor into the anchorsUnmodifiableProperty() of this Connection. The given AnchorKey is attached to the IAnchor. Furthermore, a PCL for the AnchorKey is registered on the position property of the IAnchor and the visualization is refreshed.
      Parameters:
      anchorKey - The AnchorKey under which the IAnchor is to be registered.
      anchor - The IAnchor which is inserted.

    • addControlAnchor

      public void addControlAnchor(int index, IAnchor anchor)
      Adds the given IAnchor as a control point anchor for the given index into the anchorsUnmodifiableProperty() of this Connection.
      Parameters:
      index - The position where the IAnchor is inserted within the control point anchorsByKeys of this Connection.
      anchor - The IAnchor which determines the position of the corresponding control point.

    • addControlPoint

      public void addControlPoint(int index, Point controlPoint)
      Adds an StaticAnchor yielding the given Point as a control point anchor for the given index into the anchorsUnmodifiableProperty() of this Connection.
      Parameters:
      index - The position where the IAnchor is inserted within the control point anchorsByKeys of this Connection.
      controlPoint - The position for the specified control point.

    • anchorsUnmodifiableProperty

      public ReadOnlyListProperty<IAnchor> anchorsUnmodifiableProperty()
      Returns an unmodifiable read-only list property, which contains the IAnchors that determine the start point, control points, and end point of this Connection.
      See Also:

    • createPCL

      protected MapChangeListener<? super AnchorKey,? super Point> createPCL(AnchorKey anchorKey)
      Creates a position change listener (PCL) which refreshes this Connection upon anchor position changes corresponding to the given AnchorKey.
      Parameters:
      anchorKey - The AnchorKey for which a position change will trigger a refresh() with the returned PCL.
      Returns:
      A position change listener to refresh this Connection when the position for the given AnchorKey changes.

    • curveProperty

      public ObjectProperty<Node> curveProperty()
      Returns a property wrapping the curve Node.
      See Also:

    • endDecorationProperty

      public ObjectProperty<Node> endDecorationProperty()
      Returns an ObjectProperty wrapping the end decoration Node.
      See Also:

    • getAnchor

      public IAnchor getAnchor(int index)
      Returns the anchor at the given index. The start anchor will be provided for index == 0, the end anchor for the last defined index. Control anchorsByKeys will be returned for all indices in between.
      Parameters:
      index - The index of the anchor to retrieve.
      Returns:
      The anchor at the given index.

    • getAnchorIndex

      protected int getAnchorIndex(AnchorKey anchorKey)
      Returns the anchor index for the given AnchorKey.
      Parameters:
      anchorKey - The AnchorKey for which the anchor index is determined.
      Returns:
      The anchor index for the given AnchorKey or -1 in case the anchor key is not contained.

    • getAnchorKey

      protected AnchorKey getAnchorKey(int anchorIndex)
      Returns the AnchorKey for the given anchor index, i.e. the reverse of getAnchorIndex(AnchorKey).
      Parameters:
      anchorIndex - The anchor index for which to determine the AnchorKey.
      Returns:
      The AnchorKey for the given anchor index.

    • getAnchorsUnmodifiable

      public ObservableList<IAnchor> getAnchorsUnmodifiable()
      Returns a List containing the IAnchors which are assigned to this Connection in the order: start anchor, control point anchorsByKeys, end anchor.
      Returns:
      A List containing the IAnchors which are assigned to this Connection.

    • getCenter

      public Point getCenter()
      Computes the 'logical' center point of the Connection, which is the middle control point position (in case the curveProperty consists of an even number of segment) or the middle point of the middle segment.
      Returns:
      The logical center of this Connection.

    • getControlAnchor

      public IAnchor getControlAnchor(int index)
      Returns the control anchor for the given control anchor index which is currently assigned, or null if no control anchor is assigned for that index.
      Parameters:
      index - The control anchor index determining which control anchor to return.
      Returns:
      The control anchor for the given index, or null.

    • getControlAnchorIndex

      protected int getControlAnchorIndex(AnchorKey key)
      Returns the control anchor index for the given AnchorKey, i.e. 0 for the first control anchor, 1 for the seconds, etc.
      Parameters:
      key - The AnchorKey whose control anchor index is returned.
      Returns:
      The control anchor index for the given AnchorKey.
      Throws:
      IllegalArgumentException - when there currently is no control anchor assigned to this Connection for the given AnchorKey.

    • getControlAnchorKey

      protected AnchorKey getControlAnchorKey(int index)
      Returns the AnchorKey for the given control anchor index.
      Parameters:
      index - The control anchor index for which the AnchorKey is returned.
      Returns:
      The AnchorKey for the given control anchor index.

    • getControlAnchors

      public List<IAnchor> getControlAnchors()
      Returns a List containing the control anchorsByKeys currently assigned to this Connection.
      Returns:
      A List containing the control anchorsByKeys currently assigned to this Connection.

    • getControlPoint

      public Point getControlPoint(int index)
      Returns the control Point for the given control anchor index within the coordinate system of this Connection which is determined by querying the anchor position for the corresponding control anchor, or null if no control anchor is assigned for the given index.
      Parameters:
      index - The control anchor index for which to return the anchor position.
      Returns:
      The start Point of this Connection, or null.

    • getControlPoints

      public List<Point> getControlPoints()
      Returns a List containing the control Points of this Connection.
      Returns:
      A List containing the control Points of this Connection.

    • getCurve

      public Node getCurve()
      Returns the Node which displays the curveProperty geometry. Will be a GeometryNode by default.
      Returns:
      The Node which displays the curveProperty geometry.

    • getEndAnchor

      public IAnchor getEndAnchor()
      Returns the currently assigned end anchor, or null if no end anchor is assigned.
      Returns:
      The currently assigned end anchor, or null.

    • getEndAnchorKey

      protected AnchorKey getEndAnchorKey()
      Returns the end AnchorKey for this Connection. An end AnchorKey uses the curveProperty node as its anchored and "end" as its role.
      Returns:
      The end AnchorKey for this Connection.

    • getEndDecoration

      public Node getEndDecoration()
      Returns the end decoration Node of this Connection, or null.
      Returns:
      The end decoration Node of this Connection, or null.

    • getEndPoint

      public Point getEndPoint()
      Returns the end Point of this Connection within its coordinate system which is determined by querying the anchor position for the end anchor key, or null when no end anchor is assigned.
      Returns:
      The end Point of this Connection, or null.

    • getEndPointHint

      public Point getEndPointHint()
      Returns the currently set end position hint or null if no hint is present.
      Returns:
      The currently set end position hint or null if no hint is present.

    • getInterpolator

      public IConnectionInterpolator getInterpolator()
      Returns the IConnectionInterpolator of this Connection.
      Returns:
      The IConnectionInterpolator of this Connection.

    • getPoint

      public Point getPoint(int index)
      Returns the point at the given index. The start point will be provided for index == 0, the end point for the last defined index. Control points will be returned for all indices in between.
      Parameters:
      index - The index of the point to retrieve.
      Returns:
      The point at the given index.
      See Also:

    • getPointsUnmodifiable

      public ObservableList<Point> getPointsUnmodifiable()
      Returns the Points constituting this Connection within its coordinate system in the order: start point, control points, end point.
      Returns:
      The Points constituting this Connection.

    • getRouter

      public IConnectionRouter getRouter()
      Returns the IConnectionRouter of this Connection.
      Returns:
      The IConnectionRouter of this Connection.

    • getStartAnchor

      public IAnchor getStartAnchor()
      Returns the currently assigned start anchor, or null if no start anchor is assigned.
      Returns:
      The currently assigned start anchor, or null.

    • getStartAnchorKey

      protected AnchorKey getStartAnchorKey()
      Returns the start AnchorKey for this Connection. A start AnchorKey uses the curveProperty node as its anchored and "start" as its role.
      Returns:
      The start AnchorKey for this Connection.

    • getStartDecoration

      public Node getStartDecoration()
      Returns the start decoration Node of this Connection, or null.
      Returns:
      The start decoration Node of this Connection, or null.

    • getStartPoint

      public Point getStartPoint()
      Returns the start Point of this Connection within its coordinate system which is determined by querying the anchor position for the start anchor key, or null when no start anchor is assigned.
      Returns:
      The start Point of this Connection, or null.

    • getStartPointHint

      public Point getStartPointHint()
      Returns the currently set start position hint or null if no hint is present.
      Returns:
      The currently set start position hint or null if no hint is present.

    • interpolatorProperty

      public ObjectProperty<IConnectionInterpolator> interpolatorProperty()
      Returns the IConnectionInterpolator property.
      See Also:

    • isConnected

      public boolean isConnected(IAnchor anchor)
      Return true in case the anchor is bound to an anchorage unequal to this connection.
      Parameters:
      anchor - The anchor to test
      Returns:
      true if the anchor is connected, false otherwise.

    • isConnected

      public boolean isConnected(int index)
      Returns whether the (start, end, or control) anchor at the respective index is connected.
      Parameters:
      index - The index, referring to the start, end, or a control point.
      Returns:
      true if the anchor at the given index is connected, false otherwise.

    • isControlConnected

      public boolean isControlConnected(int index)
      Returns true if the currently assigned control anchor for the given index is bound to an anchorage. Otherwise returns false.
      Parameters:
      index - The control anchor index of the control anchor to test for connectedness.
      Returns:
      true if the currently assigned control anchor for the given index is bound to an anchorage, otherwise false.

    • isEndConnected

      public boolean isEndConnected()
      Returns true if the currently assigned end anchor is bound to an anchorage. Otherwise returns false.
      Returns:
      true if the currently assigned end anchor is bound to an anchorage, otherwise false.

    • isStartConnected

      public boolean isStartConnected()
      Returns true if the currently assigned start anchor is bound to an anchorage. Otherwise returns false.
      Returns:
      true if the currently assigned start anchor is bound to an anchorage, otherwise false.

    • maxHeight

      public double maxHeight(double width)
      Overrides:
      maxHeight in class Node

    • maxWidth

      public double maxWidth(double height)
      Overrides:
      maxWidth in class Node

    • minHeight

      public double minHeight(double width)
      Overrides:
      minHeight in class Group

    • minWidth

      public double minWidth(double height)
      Overrides:
      minWidth in class Group

    • pointsUnmodifiableProperty

      public ReadOnlyListProperty<Point> pointsUnmodifiableProperty()
      Returns an unmodifiable read-only list property, which contains the points (start, control, end) that constitute this connection.
      See Also:

    • reattachAnchorKeys

      protected void reattachAnchorKeys(Node oldAnchored, Node newAnchored)
      Re-attaches all AnchorKeys that are managed by this Connection.
      Parameters:
      oldAnchored - The previous anchored Node.
      newAnchored - The new anchored Node.

    • refresh

      protected void refresh()
      Refreshes the visualization in response to anchor, position, transformation, etc. changes. This method is safe against reentrance, i.e. changes performed by refresh() are allowed to lead to another refresh() call. However, when this method is called reentrant, it returns immediately.

      The process of refreshing a Connection is somewhat complicated as it involves transforming points according to a transformation change, removing volatile anchors, computing new parameters for its anchors, inserting volatile anchors, computing a curve geometry, and updating the visualization to that geometry. In addition, the position change listeners registered at the individual AbstractAnchor.positionsUnmodifiableProperty() need to be disabled during refresh() to prevent ConcurrentModificationException. The process can be described by the following steps:

      1. The connection unregisters all position change listeners.
      2. The connection queries all points from its anchors and transforms them from curve to connection coordinates (curve-to-connection-transform, c2ctx).
      3. The router removes all (previously inserted) volatile anchors.
      4. => The connection's points are refreshed in-place, because removal of anchors calls removeAnchor(AnchorKey, IAnchor), which updates the points straight away.
      5. The router queries the (updated, user-defined) points from the connection and computes parameters for the anchors based on these points (and other criteria).
      6. => The router computes the DynamicAnchor.AnchoredReferencePoint parameter value within the coordinate system of the connection.
      7. => The parameter is then bound to a binding that depends on the c2ctx, which transforms the Point from the coordinate system of the connection to the coordinate system of the getCurve().
      8. The anchors compute new positions for the AnchorKeys for which new parameters were provided or parameter values changed.
      9. The router queries the positions from the anchors and transforms them manually, because the connection did not yet update its points.
      10. The router inserts volatile anchors according to the routing strategy.
      11. The connection refreshes its points manually, because the position change listeners are disabled.
      12. The interpolator computes a new curve geometry and applies it to the connection.
      13. => The c2ctx changes, that's why the parameters are recomputed from the bindings, which triggers a recomputation of the anchor positions.
      14. The connection refreshed its points manually again.
      15. The connection registers all position change listeners.

    • removeAllControlAnchors

      public void removeAllControlAnchors()
      Removes all control points of this Connection.

    • removeAllControlPoints

      public void removeAllControlPoints()
      Removes all control points of this Connection.

    • removeAnchor

      protected void removeAnchor(AnchorKey anchorKey, IAnchor anchor)
      Removes the given AnchorKey (and corresponding IAnchor) from this Connection.
      Parameters:
      anchorKey - The AnchorKey to remove.
      anchor - The corresponding IAnchor.

    • removeControlAnchor

      public void removeControlAnchor(int index)
      Removes the control anchor specified by the given index from this Connection.
      Parameters:
      index - The index specifying which control anchor to remove.

    • removeControlPoint

      public void removeControlPoint(int index)
      Removes the control point specified by the given control anchor index from this Connection.
      Parameters:
      index - The control anchor index specifying which control point to remove.

    • routerProperty

      public ObjectProperty<IConnectionRouter> routerProperty()
      Returns a writable property containing the IConnectionRouter of this connection.
      See Also:

    • setAnchor

      protected void setAnchor(AnchorKey anchorKey, IAnchor anchor)
      Replaces the anchor currently registered for the given AnchorKey with the given IAnchor.
      Parameters:
      anchorKey - The AnchorKey under which the IAnchor is to be registered.
      anchor - The IAnchor which is inserted.

    • setAnchors

      public void setAnchors(List<IAnchor> anchors)
      Replaces all anchors of this Connection with the given IAnchors, i.e. the first given IAnchor replaces the currently assigned start anchor, the last given IAnchor replaces the currently assigned end anchor, and the intermediate IAnchors replace the currently assigned control anchorsByKeys.
      Parameters:
      anchors - The new IAnchors for this Connection.
      Throws:
      IllegalArgumentException - when less than 2 IAnchors are given.

    • setControlAnchor

      public void setControlAnchor(int index, IAnchor anchor)
      Sets the control anchor for the given control anchor index to the given IAnchor.
      Parameters:
      index - The control anchor index of the control anchor to replace.
      anchor - The new control IAnchor for that index.

    • setControlAnchors

      public void setControlAnchors(List<IAnchor> anchors)
      Replaces all control anchorsByKeys of this Connection with the given List of IAnchors.
      Parameters:
      anchors - The new control IAnchors for this Connection.

    • setControlPoint

      public void setControlPoint(int index, Point controlPoint)
      Sets the control anchor for the given control anchor index to an StaticAnchor which yields the given Point.
      Parameters:
      index - The control anchor index of the control anchor to replace.
      controlPoint - The new control Point for the respective index within local coordinates of the Connection.

    • setControlPoints

      public void setControlPoints(List<Point> controlPoints)
      Replaces all control anchorsByKeys of this Connection with StaticAnchors yielding the given Points.
      Parameters:
      controlPoints - The new control Points for this Connection.

    • setCurve

      public void setCurve(Node curve)
      Sets the Node that is used to render the connection.
      Parameters:
      curve - The new curveProperty node.

    • setEndAnchor

      public void setEndAnchor(IAnchor anchor)
      Sets the end IAnchor of this Connection to the given value.
      Parameters:
      anchor - The new end IAnchor for this Connection.

    • setEndDecoration

      public void setEndDecoration(Node decoration)
      Sets the end decoration Node of this Connection to the given value.
      Parameters:
      decoration - The new end decoration Node for this Connection.

    • setEndPoint

      public void setEndPoint(Point endPoint)
      Sets the end anchor of this Connection to an StaticAnchor yielding the given Point.
      Parameters:
      endPoint - The new end Point within local coordinates of the Connection.

    • setEndPointHint

      public void setEndPointHint(Point endPositionHint)
      Sets the end position hint to the given value.
      Parameters:
      endPositionHint - The new end position hint.

    • setInterpolator

      public void setInterpolator(IConnectionInterpolator interpolator)
      Sets the IConnectionInterpolator of this Connection to the given IConnectionInterpolator.
      Parameters:
      interpolator - The new IConnectionInterpolator for this Connection.

    • setPoints

      public void setPoints(List<Point> points)
      Replaces all anchors of this Connection with the given IAnchors, i.e. the first given IAnchor replaces the currently assigned start anchor, the last given IAnchor replaces the currently assigned end anchor, and the intermediate IAnchors replace the currently assigned control anchorsByKeys.
      Parameters:
      points - The new Points for this Connection.
      Throws:
      IllegalArgumentException - when less than 2 IAnchors are given.

    • setRouter

      public void setRouter(IConnectionRouter router)
      Sets the IConnectionRouter of this Connection to the given value.
      Parameters:
      router - The new IConnectionRouter for this Connection.

    • setStartAnchor

      public void setStartAnchor(IAnchor anchor)
      Sets the start IAnchor of this Connection to the given value.
      Parameters:
      anchor - The new start IAnchor for this Connection.

    • setStartDecoration

      public void setStartDecoration(Node decoration)
      Sets the start decoration Node of this Connection to the given value.
      Parameters:
      decoration - The new start decoration Node for this Connection.

    • setStartPoint

      public void setStartPoint(Point startPoint)
      Sets the start anchor of this Connection to an StaticAnchor yielding the given Point.
      Parameters:
      startPoint - The new start Point within local coordinates of the Connection.

    • setStartPointHint

      public void setStartPointHint(Point startPositionHint)
      Sets the start position hint to the given value.
      Parameters:
      startPositionHint - The new start position hint.

    • startDecorationProperty

      public ObjectProperty<Node> startDecorationProperty()
      Returns an ObjectProperty wrapping the start decoration Node.
      See Also: