RoundedPolygon.pillStar constructor

RoundedPolygon.pillStar({
  1. double width = 2,
  2. double height = 1,
  3. int numVerticesPerRadius = 8,
  4. double innerRadiusRatio = 0.5,
  5. CornerRounding rounding = CornerRounding.unrounded,
  6. CornerRounding? innerRounding,
  7. List<CornerRounding>? perVertexRounding,
  8. double vertexSpacing = 0.5,
  9. double startLocation = 0,
  10. Offset center = Offset.zero,
})

Creates a pill star about center, width wide and height high: a RoundedPolygon.pill with inner and outer radii along its outline, the way a RoundedPolygon.star has them along a circle, with numVerticesPerRadius vertices on each.

innerRadiusRatio gives the inner radius as a fraction of the outer one. It must be greater than 0 and no greater than 1, and a value of 1 gives a pill with more vertices than RoundedPolygon.pill would produce.

rounding rounds every vertex the same way. innerRounding overrides it for the inner vertices. perVertexRounding overrides both, and must have 2 * numVerticesPerRadius elements when it is not null.

How the two sets of vertices proceed along the curved ends is subtler than on a star, because of the curvature there: outer vertices lying along the curved outline force the inner ones closer together, while inner vertices lying along it force the outer ones further apart. vertexSpacing chooses between those extremes. A value of 0 spaces the inner vertices as they are spaced along the straight edges, 1 does the same for the outer vertices, and the default of 0.5 averages the two, so that each set falls equally to either side of the pill outline. Which value suits a shape depends on its rounding and radius parameters.

startLocation is how far along the perimeter the outline's curves begin, from 0 to 1. This is rarely needed or noticed, but it decides where the path starts and ends for a caller stroking it gradually.

Throws ArgumentError if numVerticesPerRadius is less than 3, if either width or height is not greater than 0, if innerRadiusRatio is outside the range 0 (exclusive) to 1, or if vertexSpacing or startLocation is outside the range 0 to 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,
  Offset center = Offset.zero,
}) {
  if (numVerticesPerRadius < 3) {
    throw ArgumentError('numVerticesPerRadius must be at least 3.');
  }
  if (width <= 0 || height <= 0) {
    throw ArgumentError('Pill shapes must have positive width and height.');
  }
  if (innerRadiusRatio <= 0 || innerRadiusRatio > 1) {
    throw ArgumentError('innerRadiusRatio must be 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,
      center,
    ),
    rounding: rounding,
    perVertexRounding: pvRounding,
    center: center,
  );
}