Types

What types are used to describe positions?

• OffsetBase represents a 2-dimensional (2D), axis-aligned vector. Subclasses are immutable and comparable using standard operators.

• Offset is an OffsetBase subclass that may be understood as a point in cartesian space or a vector. Offsets may be manipulated algebraically using standard operators; the & operator allows a Rect to be constructed by combining the offset with a Size (the offset identifies the rectangle’s top left corner). Offsets can be interpolated.

• Point is a dart class for representing a 2D point on the cartesian plane.

What types are used to describe magnitudes?

• Size is an OffsetBase subclass that represents a width and a height. Geometrically, Size describes a rectangle with its top left corner coincident with the origin. Size includes a number of methods describing a rectangle with dimensions matching the current instance and a top left corner coincident with a specified offset. Sizes may be manipulated algebraically using standard operators; the + operator expands the size according to a provided delta (via Offset). Sizes can be interpolated.

• Radius describes either a circular or elliptical radius. The radius is expressed as intersections of the x and y-axes. Circular radii have identical values. Radii may be manipulated algebraically using standard operators and interpolated.

What types are used to describe regions?

• Rect is an immutable, 2D, axis-aligned, floating-point rectangle whose coordinates are relative to a given origin. A rectangle can be described in various ways (e.g., by its center, by a bounding circle, by the magnitude of its left, top, right, and bottom edges, etc.) or constructed by combining an Offset and a Size. Rectangles can be inflated, deflated, combined, intersected, translated, queried, and more. Rectangles can be compared for equality and interpolated.

• RRect augments a Rect with four independent radii (via Radius) corresponding to its corners. Rounded rectangles can be described in various ways (e.g., by offsets to each of its sides and one or more radii, by a bounding box fully enclosing the rounded rectangle with one or more radii, etc.). Rounded rectangles define a number of sub-rectangles: a bounding rectangle (RRect.outerRect), an inner rectangle with left and right edges matching the base rectangle and top and bottom edges inset to coincide with the rounded corners' centers (RRect.wideMiddleRect), a similar rectangle but with the sets reversed (RRect.tallMiddleRect), and a rectangle that is the intersection of these two (RRect.middleRect). A rounded rectangle is said to describe a “stadium” if it possesses a side with no straight segment (e.g., entirely drawn by the two rounded corners). Rounded rectangles can be interpolated.

What types are used to describe coordinate spaces?

• Axis represents the X- or Y-axis (horizontal or vertical, respectively) relative to a coordinate space. The coordinate space can be arbitrarily transformed and therefore need not be parallel to the screen’s edges.

• AxisDirection applies directionality to an axis. The value represents the direction in which values increase along an associated axis, with the origin rooted at the opposite end (e.g., AxisDirection.down positions the origin at the top with positive values growing downward).

• GrowthDirection is the direction of growth relative to the current axis direction (e.g., how items are ordered along the axis). GrowthDirection.forward implies an ordering consistent with the axis direction (the first item is at the origin with subsequent items following). GrowthDirection.reverse is exactly the opposite (the last item is at the origin with preceding items following).

  • Growth direction does not flip the meaning of “leading” and “trailing,” it merely determines how children are ordered along a specified axis.

  • For a viewport, the origin is positioned according to an axis direction (e.g., AxisDirection.down positions the origin at the top of the screen, AxisDirection.up positions the origin at the bottom of the screen), with the growth direction determining how children are ordered starting from the origin. As a result, both pieces of information are necessary to determine where a set of slivers should actually appear.

• ScrollDirection represents the user’s scroll direction relative to the positive scroll offset direction (i.e., the direction in which positive scroll offsets increase as determined by axis direction and growth direction). Includes an idle state (ScrollDirection.idle).

  • This is typically subject to the growth direction (e.g., the scroll direction is flipped when growth is reversed).

  • Confusingly, this refers to the direction the content is moving on screen rather than where the user is scrolling (e.g., scrolling down a web page causes the page’s contents to move upward; this would be classified as ScrollDirection.reverse since this motion is opposite the axis direction).

What types are used to describe graphics?

• Color is a 32-bit immutable quantity describing alpha, red, green, and blue color channels. Alpha can be defined using an opacity value from zero to one. Colors can be interpolated and converted into a luminance value.

• Shadow represents a single drop shadow with a color, an offset from the casting element, and a blur radius characterizing the Gaussian blur applied to the shadow.

• Gradient describes one or more smooth color transitions. Gradients can be interpolated and scaled; gradients can also be used to obtain a reference to a corresponding shader. Linear, radial, and sweep gradients are supported (via LinearGradient, RadialGradient, and SweepGradient, respectively). TileMode determines how a gradient paints beyond its defined bounds. Gradients may be clamped (e.g., hold their initial and final values), repeated (e.g., restarted at their bounds), or mirrored (e.g., restarted but with initial and final values alternating).

How are tree nodes modeled?

• AbstractNode represents a node in a tree without specifying a particular child model (i.e., the tree's actual structure is left as an implementation detail). Concrete implementations must call AbstractNode.adoptChild and AbstractNode.dropChild whenever the child model changes.

  • AbstractNode.owner references an arbitrary object shared by all nodes in a subtree.

    • AbstractNode.attach assigns an owner to the node. Adopting children will attach them automatically. Used by the owner to attach the tree via its root node.

      • Subclasses should attach all children since the parent can change its attachment state at any time (i.e., after the child is adopted) and must keep its children in sync.

    • AbstractNode.detach clears a node's owner. Dropping children will detach them automatically. Used by the owner to detach the tree via its root node.

      • Subclasses should detach all children since the parent can change its attachment state at any time (i.e., after the child is adopted) and must keep its children in sync.

    • AbstractNode.attached indicates whether the node is attached (i.e., has an owner).

  • AbstractNode.parent references the parent abstract node.

    • AbstractNode.adoptChild updates a child's parent and depth. The child is attached if the parent has an owner.

    • AbstractNode.dropChild clears the child's parent. The child is detached if the parent has an owner.

  • AbstractNode.depth is an integer that increases with depth. All depths below a given node will be greater than that node's depth. Note that values need not match the actual depth of the node.

    • AbstractNode.redepthChild updates a child's depth to be greater than its parent.

    • AbstractNode.redepthChildren uses the concrete child model to call AbstractNode.redepthChild on each child.