Package se.conciliate.extensions.router

Interface EdgeRouter

public interface EdgeRouter
The EdgeRouter is responsible for layout of lines and curves as well as the construction of the points that make up a lines and curves. It's main responsiblity is to provide a shape given a list of points in space and to assist in the creation of that shape through transformations of a list of points. All operations in an EdgeRouter is considered free of side-effects except moveSegment(List, Point[], Map, Point, Shape, Shape, List) moveSegment} wich takes a mutable map.

Instances of this class will be considered stateless.
Author:
Richard

  • Method Details

    • getID

      String getID()
      Returns a unique id for this edge router, e.g. a UUID. The returned string may be no longer than 50 charachters.
      Returns:
      a unique id for this edge router

    • getName

      String getName(Locale locale)
      Returns a user friendly name for this edge router in the specified locale or, if a name is not available in that locale, a user friendly default name.
      Parameters:
      locale - The locale that the name applies to
      Returns:
      A user friendly name for this edge router

    • contains

      boolean contains(List<Point> points, Point p)
      Returns true if the point p lies on the path given by the control points. The exact result of this method is implementation dependant.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - the control points that makes up the line
      p - the point we are interested in
      Returns:
      true if p lies on the path, false otherwise

    • createShape

      Shape createShape(List<Point> points, List<IntersectionPoint> intersections, List<OverlappingSegment> overlappingSegments)
      Returns a shape of the line. Implementations must be able to handle a list that is about to be constructed, i.e any number of points. However, this method (as with other methods) will never be called for point lists constructed or routed by other routers.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - the control points that makes up the line. This list can contain any number of points but will always be constructed by instances of this router's class.
      intersections - points where intersections should be rendered.
      overlappingSegments - segments that are overlapping with other edges and therefor should not be rendered.
      Returns:
      a shape that makes up the line

    • updateEndpoints

      List<Point> updateEndpoints(List<Point> controlPoints, List<Point> modifiedPoints, Shape oldFrom, Shape newFrom, Shape oldTo, Shape newTo, Point relativeOffset)
      Returns the updated control points when shapes connected by the given control points has moved. The old connected shapes are given as well as the new connected shapes. The exact effects of this method is implementation dependant but the returned list must always connect newFrom with newTo. However, all other parameters may be disregarded by some implementations.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      controlPoints - the control points of the path going from oldFrom to oldTo
      modifiedPoints - A list of points.
      oldFrom - the shape that the sent in control points start at
      newFrom - the shape that the returned control points should start at
      oldTo - the shape that the sent in control points end at
      newTo - the shape that the returned control points should end at
      relativeOffset - An offset.
      Returns:
      a new list of control points

    • appendControlPoint

      List<Point> appendControlPoint(List<Point> points, Point p, Shape from, Shape to, List<Point[]> otherSegments)
      Returns a new list of control points where the given point p is taken into account while routing. The points parameter can be any size (including empty). This method will be called while constructing a new edge (but may be called at any time) and must therefore be able to handle a point-list of any size. However, the points will never be routed or constructed by other routers than instances of this router's class. The exact effects of this method is implementation dependant but the returned list must always connect from with to. Other parameters may be disregarded by some implementations.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - A list of points to re-route taking the new point p into account as being added to the list of points. It can be of any size but is never routed by other routers.
      p - The point to append (what this means is up to the implementation and callers can not assume that the returned value will contain the point).
      from - The shape that the points-list should be routed from
      to - The shape that the points-list should be routed to
      otherSegments - A list of segments.
      Returns:
      A re-routed list of points.

    • removeControlPoint

      List<Point> removeControlPoint(List<Point> points, Point p, Shape from, Shape to)
      Returns a new list of control points where the given point p is no longer taken into account while routing. The effect of removing a point is implementation dependant but the returned list must always connect from with to.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - The list of points to re-route, exluding the point p
      p - The point to exclude
      from - the shape that the control points should start at
      to - the shape that the control points should end at
      Returns:
      a new list of control points where the point p is no longer taken into account while routing.

    • moveControlPoint

      List<Point> moveControlPoint(List<Point> points, Point controlPoint, Point offset, Shape from, Shape to, List<Point[]> otherSegments)
      Returns a new list of control points where the given point p has moved by the specified offset. The exact effects of this method is implementation dependant but must always connect from with to. Other parameters may be disregarded by some implementations. Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - A list of control points to transform taking the sent in controlPoints and offset into account.
      controlPoint - The point to move. This point must be contained in points.
      offset - The offset by wich the controlPoint should move.
      from - the shape that the control points should start at
      to - the shape that the control points should end at
      otherSegments - A list of segments.
      Returns:
      a new list of control points where the give point p has moved by the specified offset.

    • moveSegment

      List<Point> moveSegment(List<Point> points, Point[] segment, Map<Point,Point> changes, Point offset, Shape from, Shape to, List<Point[]> otherSegments)
      Returns a new list of control points where the given segment has moved by the specified offset. This method, in contrast to other operations on this object, will have side effects since it will change the sent in map. No other side effects are allowed. The exact effects of this method is implementation dependant but should always connect from with to. Other parameters may be disregarded by some implemenations.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - The points to transform
      segment - The segment that should be moved
      changes - A mapping from the points in segment to the corresponding point in the result of this call (the returned value). This parameter may be null and its intention is to be able to track where the points on the sent in segment ends up after this call is done. If it is null, it might not be used. Otherwise, the map will be cleared and new point mappings put in. Ex: changes.get(segment[0]) will return a point that is in the returned list.
      offset - The offset to where the segment should move, relative to its current position
      from - the shape that the control points should start at
      to - the shape that the control points should end at
      otherSegments - A list of segments.
      Returns:
      a new list of control points where the given segment has moved by the given offset.
      Throws:
      IllegalArgumentException - if the segment is not a valid segment in points

    • getSegment

      Point[] getSegment(List<Point> points, Point p)
      Returns an array representing the segment closest to the point p on points.

      Note that points must not be modified, and neither must the Point objects in it.
      Parameters:
      points - The points describing the path where the caller is looking for a segment close to p
      p - a point on the line
      Returns:
      the segment closest to p on points

    • rotateLabelToFollowShape

      double rotateLabelToFollowShape(Rectangle labelBounds, List<Point> controlPoints)
      Without mutating any parameter, returns an angle that the given label bounds should be rotated by to make the label "follow" the shape of an edge made up of the given control points. What "follow" means is up to the router to determine (so always returning 0 is valid). For straight lines, a good return value is the angle of the line closest to the bounds. For curves, a more intricate algorithm may be provided (maybe the mean slope of some curve segment close to the label bounds).
      Parameters:
      labelBounds - The bounds of the label.
      controlPoints - The control points that will make up a fully constructed edge.
      Returns:
      The angle to rotate the bounds by.

    • getNewLabelBounds

      Rectangle getNewLabelBounds(Rectangle oldBounds, List<Point> controlPoints)
      Returns new label bounds that are "snapped" to the edge path in some way decided by the router.

      Note that controlPoints must not be modified, and neither must the Point objects in it. oldBounds must not be modified.
      Parameters:
      oldBounds - The old bounds of the label.
      controlPoints - The current control points of the relation.
      Returns:
      The new bounds of the label.

    • getDefaultLabelBounds

      Rectangle getDefaultLabelBounds(Dimension dim, List<Point> controlPoints)
      Returns the default label bounds. The dimension of the bounds is given as a parameter. With this dimension in mind, the method will return a rectangle (with the same dimension) located at a default position on the edge that the given control points make up. What is meant by "default" is up to the implementation.
      Parameters:
      dim - The dimension that the return value must have. This is given as a parameter mainly to let implementations calculate a good "center" of the bounds.
      controlPoints - The points of the edge. Must not be empty.
      Returns:
      A rectangle with the given dimension that is positioned in a default way. Note that an implementation is free to, but discourage from, always returning a rectangle at position (0, 0) (or any other fixed arbitrary point).

    • getDefaultControlPoints

      List<Point> getDefaultControlPoints(Shape from, Shape to, double fromAngle, double toAngle)
      Returns a default set of control points from one shape to another, giving preferred angles (in radians) that curves or lines will have with respect to the center of the respective shape. As an example, if fromAngle is 2pi (or 0) and toAngle is pi/2, the curves or line going out from the from shape should do so on the right side of the shape and the curve or line going in to the to shape should do so on the top side of the shape.

      Depending on the implementation, these preferred angles may or may not be strictly adhered to. For example, an edge router that only draws vertical and horizontal lines, a fromAngle of 3pi/4 might be interpreted exactly as pi/2 (or pi). An edge router that only draws lines from the center of the shapes might completely disregard the angles.
      Parameters:
      from - the from shape
      to - the to shape
      fromAngle - the preferred angle at which a line or curve should exit the from shape
      toAngle - the preferred angle at which a line or curve should enter the to shape
      Returns:
      a default set of control points

    • getDefaultControlPoints

      List<Point> getDefaultControlPoints(Shape from, Shape to)
      Returns a default set of control points from one shape to another.
      Parameters:
      from - The "from" shape.
      to - The "to" shape.
      Returns:
      A list of valid control points for an edge between from and to.

    • addControlPoint

      List<Point> addControlPoint(List<Point> controlPoints, Point toAdd)
      Adds a control point to the edge. The exact effect of this method is implementation dependant and all parameters may be disregarded by some implementations.
      Parameters:
      controlPoints - The current control points.
      toAdd - The new point to add. The implementation should try to add the new point as close as possible to toAdd.
      Returns:
      The new control points

    • getBreakdownLocation

      Point getBreakdownLocation(List<Point> controlPoints)
      Returns the point where the breakdown decorator should be drawn.
      Parameters:
      controlPoints - A list of control points.
      Returns:
      the point where the breakdown decorator should be drawn.

    • adjust

      void adjust(Collection<EdgeRouter.AdjustInfo> controlPoints)
      Adjusts control points from different edges to each other. The router is responsible for determining how the edges should be aligned to each other. The router can assume that all adjust infos (edges) sent, have been routed by instances of this edge router's class.

      NOTE: This method is a best effort method and callers can not assume that anything will happen. A perfectly acceptable implementation is to return directly when called - without even setting the new values of the adjust infos.
      Parameters:
      controlPoints - A collection of adjust infos, each describing the current state of an edge.

    • adjust

      void adjust(Collection<EdgeRouter.AdjustInfo> controlPoints, Set<Shape> avoid)
      Adjusts control points from different edges to each other. The router is responsible for determining how the edges should be aligned to each other. The router can assume that all adjust infos (edges) sent, have been routed by instances of this edge router's class.

      NOTE: This method is a best effort method and callers can not assume that anything will happen. A perfectly acceptable implementation is to return directly when called - without even setting the new values of the adjust infos.
      Parameters:
      controlPoints - A collection of adjust infos, each describing the current state of an edge.
      avoid - A set of shapes to make a best effort to try and avoid.