org.jfree.util

## Class ShapeUtilities

- java.lang.Object
- - org.jfree.util.ShapeUtilities

-     public class ShapeUtilities
      extends java.lang.Object

  Utility methods for `Shape` objects.
  Author:
    David Gilbert

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.awt.Shape` | `clone(java.awt.Shape shape)` Returns a clone of the specified shape, or `null`.
    `static boolean` | `contains(java.awt.geom.Rectangle2D rect1, java.awt.geom.Rectangle2D rect2)` Checks, whether the given rectangle1 fully contains rectangle 2 (even if rectangle 2 has a height or width of zero!).
    `static java.awt.Shape` | `createDiagonalCross(float l, float t)` Creates a diagonal cross shape.
    `static java.awt.Shape` | `createDiamond(float s)` Creates a diamond shape.
    `static java.awt.Shape` | `createDownTriangle(float s)` Creates a triangle shape that points downwards.
    `static java.awt.Shape` | `createLineRegion(java.awt.geom.Line2D line, float width)` Creates a region surrounding a line segment by 'widening' the line segment.
    `static java.awt.Shape` | `createRegularCross(float l, float t)` Creates a diagonal cross shape.
    `static java.awt.Shape` | `createTranslatedShape(java.awt.Shape shape, double transX, double transY)` Creates and returns a translated shape.
    `static java.awt.Shape` | `createTranslatedShape(java.awt.Shape shape, RectangleAnchor anchor, double locationX, double locationY)` Translates a shape to a new location such that the anchor point (relative to the rectangular bounds of the shape) aligns with the specified (x, y) coordinate in Java2D space.
    `static java.awt.Shape` | `createUpTriangle(float s)` Creates a triangle shape that points upwards.
    `static void` | `drawRotatedShape(java.awt.Graphics2D g2, java.awt.Shape shape, double angle, float x, float y)` Draws a shape with the specified rotation about `(x, y)`.
    `static boolean` | `equal(java.awt.geom.Arc2D a1, java.awt.geom.Arc2D a2)` Compares two arcs and returns `true` if they are equal or both `null`.
    `static boolean` | `equal(java.awt.geom.Ellipse2D e1, java.awt.geom.Ellipse2D e2)` Compares two ellipses and returns `true` if they are equal or both `null`.
    `static boolean` | `equal(java.awt.geom.GeneralPath p1, java.awt.geom.GeneralPath p2)` Tests two polygons for equality.
    `static boolean` | `equal(java.awt.geom.Line2D l1, java.awt.geom.Line2D l2)` Compares two lines are returns `true` if they are equal or both `null`.
    `static boolean` | `equal(java.awt.Polygon p1, java.awt.Polygon p2)` Tests two polygons for equality.
    `static boolean` | `equal(java.awt.Shape s1, java.awt.Shape s2)` Tests two shapes for equality.
    `static java.awt.geom.Point2D` | `getPointInRectangle(double x, double y, java.awt.geom.Rectangle2D area)` Returns a point based on (x, y) but constrained to be within the bounds of a given rectangle.
    `static boolean` | `intersects(java.awt.geom.Rectangle2D rect1, java.awt.geom.Rectangle2D rect2)` Checks, whether the given rectangle1 fully contains rectangle 2 (even if rectangle 2 has a height or width of zero!).
    `static java.awt.Shape` | `rotateShape(java.awt.Shape base, double angle, float x, float y)` Rotates a shape about the specified coordinates.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### clone

          public static java.awt.Shape clone(java.awt.Shape shape)

      Returns a clone of the specified shape, or `null`. At the current time, this method supports cloning for instances of `Line2D`, `RectangularShape`, `Area` and `GeneralPath`.

      `RectangularShape` includes `Arc2D`, `Ellipse2D`, `Rectangle2D`, `RoundRectangle2D`.

      Parameters:
        `shape` - the shape to clone (`null` permitted, returns `null`).
      Returns:
        A clone or `null`.

    - #### equal

          public static boolean equal(java.awt.Shape s1,
                      java.awt.Shape s2)

      Tests two shapes for equality. If both shapes are `null`, this method will return `true`.

      In the current implementation, the following shapes are supported: `Ellipse2D`, `Line2D` and `Rectangle2D` (implicit).

      Parameters:
        `s1` - the first shape (`null` permitted).
        `s2` - the second shape (`null` permitted).
      Returns:
        A boolean.

    - #### equal

          public static boolean equal(java.awt.geom.Line2D l1,
                      java.awt.geom.Line2D l2)

      Compares two lines are returns `true` if they are equal or both `null`.
      Parameters:
        `l1` - the first line (`null` permitted).
        `l2` - the second line (`null` permitted).
      Returns:
        A boolean.

    - #### equal

          public static boolean equal(java.awt.geom.Ellipse2D e1,
                      java.awt.geom.Ellipse2D e2)

      Compares two ellipses and returns `true` if they are equal or both `null`.
      Parameters:
        `e1` - the first ellipse (`null` permitted).
        `e2` - the second ellipse (`null` permitted).
      Returns:
        A boolean.

    - #### equal

          public static boolean equal(java.awt.geom.Arc2D a1,
                      java.awt.geom.Arc2D a2)

      Compares two arcs and returns `true` if they are equal or both `null`.
      Parameters:
        `a1` - the first arc (`null` permitted).
        `a2` - the second arc (`null` permitted).
      Returns:
        A boolean.

    - #### equal

          public static boolean equal(java.awt.Polygon p1,
                      java.awt.Polygon p2)

      Tests two polygons for equality. If both are `null` this method returns `true`.
      Parameters:
        `p1` - polygon 1 (`null` permitted).
        `p2` - polygon 2 (`null` permitted).
      Returns:
        A boolean.

    - #### equal

          public static boolean equal(java.awt.geom.GeneralPath p1,
                      java.awt.geom.GeneralPath p2)

      Tests two polygons for equality. If both are `null` this method returns `true`.
      Parameters:
        `p1` - path 1 (`null` permitted).
        `p2` - path 2 (`null` permitted).
      Returns:
        A boolean.

    - #### createTranslatedShape

          public static java.awt.Shape createTranslatedShape(java.awt.Shape shape,
                                             double transX,
                                             double transY)

      Creates and returns a translated shape.
      Parameters:
        `shape` - the shape (`null` not permitted).
        `transX` - the x translation (in Java2D space).
        `transY` - the y translation (in Java2D space).
      Returns:
        The translated shape.

    - #### createTranslatedShape

          public static java.awt.Shape createTranslatedShape(java.awt.Shape shape,
                                             RectangleAnchor anchor,
                                             double locationX,
                                             double locationY)

      Translates a shape to a new location such that the anchor point (relative to the rectangular bounds of the shape) aligns with the specified (x, y) coordinate in Java2D space.
      Parameters:
        `shape` - the shape (`null` not permitted).
        `anchor` - the anchor (`null` not permitted).
        `locationX` - the x-coordinate (in Java2D space).
        `locationY` - the y-coordinate (in Java2D space).
      Returns:
        A new and translated shape.

    - #### rotateShape

          public static java.awt.Shape rotateShape(java.awt.Shape base,
                                   double angle,
                                   float x,
                                   float y)

      Rotates a shape about the specified coordinates.
      Parameters:
        `base` - the shape (`null` permitted, returns `null`).
        `angle` - the angle (in radians).
        `x` - the x coordinate for the rotation point (in Java2D space).
        `y` - the y coordinate for the rotation point (in Java2D space).
      Returns:
        the rotated shape.

    - #### drawRotatedShape

          public static void drawRotatedShape(java.awt.Graphics2D g2,
                              java.awt.Shape shape,
                              double angle,
                              float x,
                              float y)

      Draws a shape with the specified rotation about `(x, y)`.
      Parameters:
        `g2` - the graphics device (`null` not permitted).
        `shape` - the shape (`null` not permitted).
        `angle` - the angle (in radians).
        `x` - the x coordinate for the rotation point.
        `y` - the y coordinate for the rotation point.

    - #### createDiagonalCross

          public static java.awt.Shape createDiagonalCross(float l,
                                           float t)

      Creates a diagonal cross shape.
      Parameters:
        `l` - the length of each 'arm'.
        `t` - the thickness.
      Returns:
        A diagonal cross shape.

    - #### createRegularCross

          public static java.awt.Shape createRegularCross(float l,
                                          float t)

      Creates a diagonal cross shape.
      Parameters:
        `l` - the length of each 'arm'.
        `t` - the thickness.
      Returns:
        A diagonal cross shape.

    - #### createDiamond

          public static java.awt.Shape createDiamond(float s)

      Creates a diamond shape.
      Parameters:
        `s` - the size factor (equal to half the height of the diamond).
      Returns:
        A diamond shape.

    - #### createUpTriangle

          public static java.awt.Shape createUpTriangle(float s)

      Creates a triangle shape that points upwards.
      Parameters:
        `s` - the size factor (equal to half the height of the triangle).
      Returns:
        A triangle shape.

    - #### createDownTriangle

          public static java.awt.Shape createDownTriangle(float s)

      Creates a triangle shape that points downwards.
      Parameters:
        `s` - the size factor (equal to half the height of the triangle).
      Returns:
        A triangle shape.

    - #### createLineRegion

          public static java.awt.Shape createLineRegion(java.awt.geom.Line2D line,
                                        float width)

      Creates a region surrounding a line segment by 'widening' the line segment. A typical use for this method is the creation of a 'clickable' region for a line that is displayed on-screen.
      Parameters:
        `line` - the line (`null` not permitted).
        `width` - the width of the region.
      Returns:
        A region that surrounds the line.

    - #### getPointInRectangle

          public static java.awt.geom.Point2D getPointInRectangle(double x,
                                                  double y,
                                                  java.awt.geom.Rectangle2D area)

      Returns a point based on (x, y) but constrained to be within the bounds of a given rectangle.
      Parameters:
        `x` - the x-coordinate.
        `y` - the y-coordinate.
        `area` - the constraining rectangle (`null` not permitted).
      Returns:
        A point within the rectangle.
      Throws:
        `java.lang.NullPointerException` - if `area` is `null`.

    - #### contains

          public static boolean contains(java.awt.geom.Rectangle2D rect1,
                         java.awt.geom.Rectangle2D rect2)

      Checks, whether the given rectangle1 fully contains rectangle 2 (even if rectangle 2 has a height or width of zero!).
      Parameters:
        `rect1` - the first rectangle.
        `rect2` - the second rectangle.
      Returns:
        A boolean.

    - #### intersects

          public static boolean intersects(java.awt.geom.Rectangle2D rect1,
                           java.awt.geom.Rectangle2D rect2)

      Checks, whether the given rectangle1 fully contains rectangle 2 (even if rectangle 2 has a height or width of zero!).
      Parameters:
        `rect1` - the first rectangle.
        `rect2` - the second rectangle.
      Returns:
        A boolean.