- A decoration is a high level description of graphics to be painted onto a canvas, generally corresponding to a box but can also describe other shapes, too. In addition to being paintable, decorations support interaction and interpolation.
DecorationImagedescribes an image (as obtained via
ImageProvider) to be inscribed within a decoration, accepting many of the same arguments as
paintImage. The alignment, repetition, and box fit determine how the image is laid out within the decoration and, if enabled, horizontal reflection will be applied for right-to-left locales.
DecorationImage.createPainter) performs the actual painting; this is a thin wrapper around
paintImagethat resolves the
ImageProviderand applies any clipping and horizontal reflection.
Shadowsubclass that additionally describes spread distance (i.e., the amount of dilation to apply to the casting element’s mask before computing the shadow). Shadows are typically arranged into a list to support a single decoration casting multiple shadows.
BorderRadiusGeometrydescribes the border radii of a particular box (via
BorderRadiusDirectionaldepending on text direction sensitivity).
BorderRadiusGeometryis composed of four immutable
BorderSidedescribes a single side of a border; the precise interpretation is determined by the enclosing
ShapeBordersubclass. Each side has a color, a style (via
BorderStyle), and a width. A width of
0.0will enable hairline rendering; that is, the border will be 1 physical pixel wide (
BorderStyle.noneis necessary to prevent the border from rendering). When hairline rendering is utilized, pixels may appear darker if they are painted multiple times by the given path. Border sides may be merged provided that they share a common style and color. Doing so produces a new
BorderSidehaving a width equal to the sum of its constituents.
ShapeBorderis the base class of all shape outlines, including those used by box decorations; in essence, it describes a single shape with edges of defined width (typically via
BorderSide). Shape borders can be interpolated and combined (via the addition operator or
ShapeBorder.add). Additionally, borders may be scaled (affecting properties like border width and radii) and painted directly to a canvas (via
ShapeBorder.paint); painting may be adjusted based on text direction. Paths describing the shape’s inner and outer edges may also be queried (via
BoxBorderis a subclass of
ShapeBorderthat is further specialized by
BorderDirectional(the latter adding text direction sensitivity). These instances describe a set of four borders corresponding to the cardinal directions; their precise arrangement is left undefined until rendering. Borders may be combined (via
Border.merge) provided that all associated sides share a style and color. If so, the corresponding widths are added together.
- Borders must be made concrete by providing a rectangle and, optionally, a
BoxShape. The provided rectangle determines how the borders are actually rendered; uniform borders are more efficient ot paint.
BoxShapedescribes how a box decoration (or border) is to be rendered into its bounds. If rectangular, painting is coincident with the bounds. If circular, the box is painted as a uniform circle with diameter matching the smaller of the bounding dimensions.
- Decoration describes an adaptive collection of graphical effects that may be applied to an arbitrary rectangle (e.g., box). Decorations optionally specify a padding (via
Decoration.padding) to ensure that any additional painting within a box (e.g., from a child widget; note that decorations do not perform clipping) does not overlap with the decoration’s own painting. Additionally, certain decorations can be marked as complex (via
Decoration.isComplex) to enable caching.
- Decorations support hit testing (via
Decoration.hitTest). A size is provided so that the decoration may be scaled to a particular box. The given offset describes a position within this box relative to its top-left corner. An optional
TextDirectionsupports containers that are sensitive to this parameter.
- Decorations support linear interpolation (via
Decoration.lerpTo). The “t” parameter represents a position on a timeline with 0 corresponding to 0% (i.e., the pre-state) and 1 corresponding to 100% (i.e., the post-state); note that values outside of this range are possible. If the source or destination value is null (indicating that a true interpolation isn’t possible), a default interpolation should be computed that reasonably approximates a true interpolation.
Decorationsubclass that describes the appearance of a graphical box. Boxes are composed of a number of elements, including a border, a drop shadow, and a background. The background is itself comprised of color, gradient, and image layers. While typically rectangular, boxes may be given rounded corners or even a circular shape (via
BoxPaintersubclass capable of rendering the described box given different
ShapeDecorationis analogous to
BoxDecorationbut supports rendering into any shape (via
ShapeBorder). Rendering occurs in layers: first a fill color is painted, then a gradient, and finally an image. Next, the
ShapeBorderis painted (clipping the previous layers); the border also serves as the casting element for all associated shadows.
ShapeDecorationalso uses a
BoxPaintersubclass for rendering.
- Shape decorations may be obtained from box decorations (via
ShapeDecoration.fromBoxDecoration) since the latter is derived from the former. In general, box decorations are more efficient since they do not need to represent arbitrary shapes; however, shapes support a wider arrange of interpolation (e.g., rectangle to circle).
DecoratedBoxincorporates a decoration into the widget hierarchy. Decorations can be painted in the foreground or background via
DecorationPosition(i.e., in front of or behind the child, respectively). Generally,
Containeris used to incorporate a
DecoratedBoxinto the UI.
NotchedShapedescribes the difference of two shapes (i.e., a guest shape is subtracted from a host shape). A path describing this shape is obtained by specifying two bounding rectangles (i.e., the host and the guest) sharing a coordinate space. The
AutomaticNotchedShapesubclass uses these bounds to determine the concrete dimensions of
ShapeBorderinstances before computing their difference.
BoxPainterprovides a base class for instances capable of rendering a
Decorationto a canvas given an
ImageConfiguration. The configuration specifies the final size, scale, and locale to be used when rendering; this information allows an otherwise abstract decoration to be made concrete. Since decorations may rely on asynchronous image providers,
BoxPainter.onChangednotifies client code when the associated resources have changed (i.e, so that painting may be repeated).