RoundedPolygon.pillStar constructor

RoundedPolygon.pillStar({ double width = 2, double height = 1, int numVerticesPerRadius = 8, double innerRadiusRatio = 0.5, CornerRounding rounding = CornerRounding.unrounded, CornerRounding? innerRounding, List<CornerRounding>? perVertexRounding, double vertexSpacing = 0.5, double startLocation = 0, double centerX = 0, double centerY = 0, })

A pillStar shape is like a RoundedPolygon.pill except it has inner and outer radii along its pill-shaped outline, just like a RoundedPolygon.star has inner and outer radii along its circular outline. The parameters for a RoundedPolygon.pillStar are similar to those of a RoundedPolygon.star except, like RoundedPolygon.pill, it has a width and height to determine the general shape of the underlying pill. Also, there is a subtle complication with the way that inner and outer vertices proceed along the circular ends of the shape, depending on the magnitudes of the rounding, innerRounding, and innerRadiusRatio parameters. For example, a shape with outer vertices that lie along the curved end outline will necessarily have inner vertices that are closer to each other, because of the curvature of that part of the shape. Conversely, if the inner vertices are lined up along the pill outline at the ends, then the outer vertices will be much further apart from each other.

The default approach, reflected by the default value of vertexSpacing, is to use the average of the outer and inner radii, such that each set of vertices falls equally to the other side of the pill outline on the curved ends. Depending on the values used for the various rounding and radius parameters, you may want to change that value to suit the look you want. A value of 0 for vertexSpacing is equivalent to aligning the inner vertices along the circular curve, and a value of 1 is equivalent to aligning the outer vertices along that curve.

width is the width of the resulting shape.

height is the height of the resulting shape.

numVerticesPerRadius is the number of vertices along each of the two radii.

innerRadiusRatio is the Inner radius ratio for this star shape, must be greater than 0 and less than or equal to 1. Note that a value of 1 would be similar to creating a RoundedPolygon.pill, but with more vertices. The default value is 0.5.

rounding is the CornerRounding properties of every vertex. If some vertices should have different rounding properties, then use perVertexRounding instead. The default rounding value is CornerRounding.unrounded, meaning that the polygon will use the vertices themselves in the final shape and not curves rounded around the vertices.

innerRounding is the optional rounding parameters for the vertices on the innerRadiusRatio. If null (the default value), inner vertices will use the rounding or perVertexRounding parameters instead. perVertexRounding is the CornerRounding properties of every vertex. If this parameter is not null, then it must have the same size as 2 * numVerticesPerRadius. If this parameter is null, then the polygon will use the rounding parameter for every vertex instead. The default value is null.

vertexSpacing is the factor, which determines how the vertices on the circular ends are laid out along the outline. A value of 0 aligns spaces the inner vertices the same as those along the straight edges, with the outer vertices then being spaced further apart. A value of 1 does the opposite, with the outer vertices spaced the same as the vertices on the straight edges. The default value is .5, which takes the average of these two extremes.

startLocation is a value from 0 to 1 which determines how far along the perimeter of this shape to start the underlying curves of which it is comprised. This is not usually needed or noticed by the user. But if the caller wants to manually and gradually stroke the path when drawing it, it might matter where that path outline begins and ends. The default value is 0.

centerX is the X coordinate of the center of the polygon, around which all vertices will be placed. The default center is at (0,0).

centerY is the Y coordinate of the center of the polygon, around which all vertices will be placed. The default center is at (0,0).

Throws ArgumentError if either width or height are <= 0 or if innerRadiusRatio is outside the range of (0, 1].

Implementation

factory RoundedPolygon.pillStar({
  double width = 2,
  double height = 1,
  int numVerticesPerRadius = 8,
  double innerRadiusRatio = 0.5,
  CornerRounding rounding = CornerRounding.unrounded,
  CornerRounding? innerRounding,
  List<CornerRounding>? perVertexRounding,
  double vertexSpacing = 0.5,
  double startLocation = 0,
  double centerX = 0,
  double centerY = 0,
}) {
  if (width <= 0 || height <= 0) {
    throw ArgumentError('Pill shapes must have positive width and height.');
  }
  if (innerRadiusRatio <= 0 || innerRadiusRatio > 1) {
    throw ArgumentError('innerRadius must in (0, 1] range.');
  }
  if (vertexSpacing < 0 || vertexSpacing > 1) {
    throw ArgumentError('vertexSpacing must be in [0, 1] range.');
  }
  if (startLocation < 0 || startLocation > 1) {
    throw ArgumentError('startLocation must be in [0, 1] range.');
  }

  var pvRounding = perVertexRounding;
  // If no per-vertex rounding supplied and caller asked for inner rounding,
  // create per-vertex rounding list based on supplied outer/inner rounding
  // parameters.
  if (pvRounding == null && innerRounding != null) {
    pvRounding = [
      for (var i = 0; i < numVerticesPerRadius; i++) ...[
        rounding,
        innerRounding,
      ],
    ];
  }

  return RoundedPolygon.fromVertices(
    _pillStarVerticesFromNumVerts(
      numVerticesPerRadius,
      width,
      height,
      innerRadiusRatio,
      vertexSpacing,
      startLocation,
      centerX,
      centerY,
    ),
    rounding: rounding,
    perVertexRounding: pvRounding,
    centerX: centerX,
    centerY: centerY,
  );
}