Commit 8294b96f authored by Adam Barth's avatar Adam Barth

Complete dartdocs for painting.dart (#4003)

parent 4e1108e7
...@@ -38,6 +38,9 @@ enum BorderStyle { ...@@ -38,6 +38,9 @@ enum BorderStyle {
/// A side of a border of a box. /// A side of a border of a box.
class BorderSide { class BorderSide {
/// Creates the side of a border.
///
/// By default, the border is 1.0 logical pixels wide and solid black.
const BorderSide({ const BorderSide({
this.color: const Color(0xFF000000), this.color: const Color(0xFF000000),
this.width: 1.0, this.width: 1.0,
...@@ -134,6 +137,9 @@ class BorderSide { ...@@ -134,6 +137,9 @@ class BorderSide {
/// A border of a box, comprised of four sides. /// A border of a box, comprised of four sides.
class Border { class Border {
/// Creates a border.
///
/// All the sides of the border default to [BorderSide.none].
const Border({ const Border({
this.top: BorderSide.none, this.top: BorderSide.none,
this.right: BorderSide.none, this.right: BorderSide.none,
...@@ -222,6 +228,7 @@ class Border { ...@@ -222,6 +228,7 @@ class Border {
); );
} }
/// Paints the border within the given rect on the given canvas.
void paint(Canvas canvas, Rect rect, { void paint(Canvas canvas, Rect rect, {
BoxShape shape: BoxShape.rectangle, BoxShape shape: BoxShape.rectangle,
double borderRadius: null double borderRadius: null
...@@ -373,14 +380,19 @@ class Border { ...@@ -373,14 +380,19 @@ class Border {
/// A shadow cast by a box. /// A shadow cast by a box.
/// ///
/// Note: BoxShadow can cast non-rectangular shadows if the box is /// BoxShadow can cast non-rectangular shadows if the box is non-rectangular
/// non-rectangular (e.g., has a border radius or a circular shape). /// (e.g., has a border radius or a circular shape).
///
/// This class is similar to CSS box-shadow. /// This class is similar to CSS box-shadow.
class BoxShadow { class BoxShadow {
/// Creates a box shadow.
///
/// By default, the shadow is solid black with zero [offset], [blurRadius],
/// and [spreadRadius].
const BoxShadow({ const BoxShadow({
this.color, this.color: const Color(0xFF000000),
this.offset, this.offset: Offset.zero,
this.blurRadius, this.blurRadius: 0.0,
this.spreadRadius: 0.0 this.spreadRadius: 0.0
}); });
...@@ -393,6 +405,7 @@ class BoxShadow { ...@@ -393,6 +405,7 @@ class BoxShadow {
/// The standard deviation of the Gaussian to convolve with the box's shape. /// The standard deviation of the Gaussian to convolve with the box's shape.
final double blurRadius; final double blurRadius;
/// The amount the box should be inflated prior to applying the blur.
final double spreadRadius; final double spreadRadius;
/// The [blurRadius] in sigmas instead of logical pixels. /// The [blurRadius] in sigmas instead of logical pixels.
...@@ -479,11 +492,17 @@ abstract class Gradient { ...@@ -479,11 +492,17 @@ abstract class Gradient {
/// Abstract const constructor. This constructor enables subclasses to provide /// Abstract const constructor. This constructor enables subclasses to provide
/// const constructors so that they can be used in const expressions. /// const constructors so that they can be used in const expressions.
const Gradient(); const Gradient();
/// Creates a [Shader] for this gradient to fill the given rect.
Shader createShader(Rect rect); Shader createShader(Rect rect);
} }
/// A 2D linear gradient. /// A 2D linear gradient.
class LinearGradient extends Gradient { class LinearGradient extends Gradient {
/// Creates a linear graident.
///
/// The [colors] argument must not be null. If [stops] is non-null, it must
/// have the same length as [colors].
const LinearGradient({ const LinearGradient({
this.begin: FractionalOffset.centerLeft, this.begin: FractionalOffset.centerLeft,
this.end: FractionalOffset.centerRight, this.end: FractionalOffset.centerRight,
...@@ -510,13 +529,14 @@ class LinearGradient extends Gradient { ...@@ -510,13 +529,14 @@ class LinearGradient extends Gradient {
/// The colors the gradient should obtain at each of the stops. /// The colors the gradient should obtain at each of the stops.
/// ///
/// Note: This list must have the same length as [stops]. /// If [stops] is non-null, this list must have the same length as [stops].
final List<Color> colors; final List<Color> colors;
/// A list of values from 0.0 to 1.0 that denote fractions of the vector from start to end. /// A list of values from 0.0 to 1.0 that denote fractions of the vector from
/// start to end.
/// ///
/// Note: If specified, this list must have the same length as [colors]. Otherwise the colors /// If non-null, this list must have the same length as [colors]. Otherwise
/// are distributed evenly between [begin] and [end]. /// the colors are distributed evenly between [begin] and [end].
final List<double> stops; final List<double> stops;
/// How this gradient should tile the plane. /// How this gradient should tile the plane.
...@@ -573,6 +593,10 @@ class LinearGradient extends Gradient { ...@@ -573,6 +593,10 @@ class LinearGradient extends Gradient {
/// A 2D radial gradient. /// A 2D radial gradient.
class RadialGradient extends Gradient { class RadialGradient extends Gradient {
/// Creates a radial graident.
///
/// The [colors] argument must not be null. If [stops] is non-null, it must
/// have the same length as [colors].
const RadialGradient({ const RadialGradient({
this.center: FractionalOffset.center, this.center: FractionalOffset.center,
this.radius: 0.5, this.radius: 0.5,
...@@ -598,7 +622,7 @@ class RadialGradient extends Gradient { ...@@ -598,7 +622,7 @@ class RadialGradient extends Gradient {
/// The colors the gradient should obtain at each of the stops. /// The colors the gradient should obtain at each of the stops.
/// ///
/// Note: This list must have the same length as [stops]. /// If [stops] is non-null, this list must have the same length as [stops].
final List<Color> colors; final List<Color> colors;
/// A list of values from 0.0 to 1.0 that denote concentric rings. /// A list of values from 0.0 to 1.0 that denote concentric rings.
...@@ -606,7 +630,9 @@ class RadialGradient extends Gradient { ...@@ -606,7 +630,9 @@ class RadialGradient extends Gradient {
/// The rings are centered at [center] and have a radius equal to the value of /// The rings are centered at [center] and have a radius equal to the value of
/// the stop times [radius]. /// the stop times [radius].
/// ///
/// Note: This list must have the same length as [colors]. /// If non-null, this list must have the same length as [colors]. Otherwise
/// the colors are distributed evenly between the [center] and the ring at
/// [radius].
final List<double> stops; final List<double> stops;
/// How this gradient should tile the plane. /// How this gradient should tile the plane.
...@@ -855,51 +881,96 @@ void paintImage({ ...@@ -855,51 +881,96 @@ void paintImage({
/// FractionalOffset(1.0, 0.0) represents the top right of the Size, /// FractionalOffset(1.0, 0.0) represents the top right of the Size,
/// FractionalOffset(0.0, 1.0) represents the bottom left of the Size, /// FractionalOffset(0.0, 1.0) represents the bottom left of the Size,
class FractionalOffset { class FractionalOffset {
/// Creates a fractional offset.
///
/// The [dx] and [dy] arguments must not be null.
const FractionalOffset(this.dx, this.dy); const FractionalOffset(this.dx, this.dy);
/// The distance fraction in the horizontal direction.
///
/// A value of 0.0 cooresponds to the leftmost edge. A value of 1.0
/// cooresponds to the rightmost edge.
final double dx; final double dx;
/// The distance fraction in the vertical direction.
///
/// A value of 0.0 cooresponds to the topmost edge. A value of 1.0
/// cooresponds to the bottommost edge.
final double dy; final double dy;
/// The top left corner.
static const FractionalOffset topLeft = const FractionalOffset(0.0, 0.0); static const FractionalOffset topLeft = const FractionalOffset(0.0, 0.0);
/// The center point along the top edge.
static const FractionalOffset topCenter = const FractionalOffset(0.5, 0.0); static const FractionalOffset topCenter = const FractionalOffset(0.5, 0.0);
/// The top right corner.
static const FractionalOffset topRight = const FractionalOffset(1.0, 0.0); static const FractionalOffset topRight = const FractionalOffset(1.0, 0.0);
/// The bottom left corner.
static const FractionalOffset bottomLeft = const FractionalOffset(0.0, 1.0); static const FractionalOffset bottomLeft = const FractionalOffset(0.0, 1.0);
/// The center point along the bottom edge.
static const FractionalOffset bottomCenter = const FractionalOffset(0.5, 1.0); static const FractionalOffset bottomCenter = const FractionalOffset(0.5, 1.0);
/// The bottom right corner.
static const FractionalOffset bottomRight = const FractionalOffset(1.0, 1.0); static const FractionalOffset bottomRight = const FractionalOffset(1.0, 1.0);
/// The center point along the left edge.
static const FractionalOffset centerLeft = const FractionalOffset(0.0, 0.5); static const FractionalOffset centerLeft = const FractionalOffset(0.0, 0.5);
/// The center point along the right edge.
static const FractionalOffset centerRight = const FractionalOffset(1.0, 0.5); static const FractionalOffset centerRight = const FractionalOffset(1.0, 0.5);
/// The center point, both horizontally and vertically.
static const FractionalOffset center = const FractionalOffset(0.5, 0.5); static const FractionalOffset center = const FractionalOffset(0.5, 0.5);
/// Returns the negation of the given fractional offset.
FractionalOffset operator -() { FractionalOffset operator -() {
return new FractionalOffset(-dx, -dy); return new FractionalOffset(-dx, -dy);
} }
/// Returns the difference between two fractional offsets.
FractionalOffset operator -(FractionalOffset other) { FractionalOffset operator -(FractionalOffset other) {
return new FractionalOffset(dx - other.dx, dy - other.dy); return new FractionalOffset(dx - other.dx, dy - other.dy);
} }
/// Returns the sum of two fractional offsets.
FractionalOffset operator +(FractionalOffset other) { FractionalOffset operator +(FractionalOffset other) {
return new FractionalOffset(dx + other.dx, dy + other.dy); return new FractionalOffset(dx + other.dx, dy + other.dy);
} }
/// Scales the fractional offset in each dimension by the given factor.
FractionalOffset operator *(double other) { FractionalOffset operator *(double other) {
return new FractionalOffset(dx * other, dy * other); return new FractionalOffset(dx * other, dy * other);
} }
/// Divides the fractional offset in each dimension by the given factor.
FractionalOffset operator /(double other) { FractionalOffset operator /(double other) {
return new FractionalOffset(dx / other, dy / other); return new FractionalOffset(dx / other, dy / other);
} }
/// Integer divides the fractional offset in each dimension by the given factor.
FractionalOffset operator ~/(double other) { FractionalOffset operator ~/(double other) {
return new FractionalOffset((dx ~/ other).toDouble(), (dy ~/ other).toDouble()); return new FractionalOffset((dx ~/ other).toDouble(), (dy ~/ other).toDouble());
} }
/// Computes the remainder in each dimension by the given factor.
FractionalOffset operator %(double other) { FractionalOffset operator %(double other) {
return new FractionalOffset(dx % other, dy % other); return new FractionalOffset(dx % other, dy % other);
} }
/// Returns the offset that is this fraction in the direction of the given offset.
Offset alongOffset(Offset other) { Offset alongOffset(Offset other) {
return new Offset(dx * other.dx, dy * other.dy); return new Offset(dx * other.dx, dy * other.dy);
} }
/// Returns the offset that is this fraction within the given size.
Offset alongSize(Size other) { Offset alongSize(Size other) {
return new Offset(dx * other.width, dy * other.height); return new Offset(dx * other.width, dy * other.height);
} }
/// Returns the point that is this fraction within the given rect.
Point withinRect(Rect rect) { Point withinRect(Rect rect) {
return new Point(rect.left + dx * rect.width, rect.top + dy * rect.height); return new Point(rect.left + dx * rect.width, rect.top + dy * rect.height);
} }
...@@ -915,6 +986,12 @@ class FractionalOffset { ...@@ -915,6 +986,12 @@ class FractionalOffset {
@override @override
int get hashCode => hashValues(dx, dy); int get hashCode => hashValues(dx, dy);
/// Linearly interpolate between two EdgeInsets.
///
/// If either is null, this function interpolates from [FractionalOffset.topLeft].
// TODO(abarth): Consider interpolating from [FractionalOffset.center] instead
// to remove upper-left bias.
static FractionalOffset lerp(FractionalOffset a, FractionalOffset b, double t) { static FractionalOffset lerp(FractionalOffset a, FractionalOffset b, double t) {
if (a == null && b == null) if (a == null && b == null)
return null; return null;
...@@ -931,6 +1008,9 @@ class FractionalOffset { ...@@ -931,6 +1008,9 @@ class FractionalOffset {
/// A background image for a box. /// A background image for a box.
class BackgroundImage { class BackgroundImage {
/// Creates a background image.
///
/// The [image] argument must not be null.
BackgroundImage({ BackgroundImage({
ImageResource image, ImageResource image,
this.fit, this.fit,
...@@ -1041,13 +1121,23 @@ enum BoxShape { ...@@ -1041,13 +1121,23 @@ enum BoxShape {
/// An immutable description of how to paint a box. /// An immutable description of how to paint a box.
class BoxDecoration extends Decoration { class BoxDecoration extends Decoration {
/// Creates a box decoration.
///
/// * If [backgroundColor] is null, this decoration does not paint a background color.
/// * If [backgroundImage] is null, this decoration does not paint a background image.
/// * If [border] is null, this decoration does not paint a border.
/// * If [borderRadius] is null, this decoration use more efficient background
/// painting commands. The [borderRadius] argument must be be null if [shape] is
/// [BoxShape.circle].
/// * If [boxShadow] is null, this decoration does not paint a shadow.
/// * If [gradient] is null, this decoration does not paint gradients.
const BoxDecoration({ const BoxDecoration({
this.backgroundColor, // null = don't draw background color this.backgroundColor,
this.backgroundImage, // null = don't draw background image this.backgroundImage,
this.border, // null = don't draw border this.border,
this.borderRadius, // null = use more efficient background drawing; note that this must be null for circles this.borderRadius,
this.boxShadow, // null = don't draw shadows this.boxShadow,
this.gradient, // null = don't allocate gradient objects this.gradient,
this.shape: BoxShape.rectangle this.shape: BoxShape.rectangle
}); });
......
...@@ -4,7 +4,16 @@ ...@@ -4,7 +4,16 @@
import 'dart:ui' show Color, lerpDouble, hashValues; import 'dart:ui' show Color, lerpDouble, hashValues;
/// A color represented using [alpha], [hue], [saturation], and [value].
///
/// An [HSVColor] is represented in a parameter space that's motivated by human
/// perception. The representation is useful for some color computations (e.g.,
/// rotating the hue through the colors of the rainbow).
class HSVColor { class HSVColor {
/// Creates a color.
///
/// All the arguments must not be null and be in their respective ranges. See
/// the fields for each parameter for a description of their ranges.
const HSVColor.fromAHSV(this.alpha, this.hue, this.saturation, this.value); const HSVColor.fromAHSV(this.alpha, this.hue, this.saturation, this.value);
/// Alpha, from 0.0 to 1.0. /// Alpha, from 0.0 to 1.0.
...@@ -19,18 +28,22 @@ class HSVColor { ...@@ -19,18 +28,22 @@ class HSVColor {
/// Value, from 0.0 to 1.0. /// Value, from 0.0 to 1.0.
final double value; final double value;
/// Returns a copy of this color with the alpha parameter replaced with the given value.
HSVColor withAlpha(double alpha) { HSVColor withAlpha(double alpha) {
return new HSVColor.fromAHSV(alpha, hue, saturation, value); return new HSVColor.fromAHSV(alpha, hue, saturation, value);
} }
/// Returns a copy of this color with the hue parameter replaced with the given value.
HSVColor withHue(double hue) { HSVColor withHue(double hue) {
return new HSVColor.fromAHSV(alpha, hue, saturation, value); return new HSVColor.fromAHSV(alpha, hue, saturation, value);
} }
/// Returns a copy of this color with the saturation parameter replaced with the given value.
HSVColor withSaturation(double saturation) { HSVColor withSaturation(double saturation) {
return new HSVColor.fromAHSV(alpha, hue, saturation, value); return new HSVColor.fromAHSV(alpha, hue, saturation, value);
} }
/// Returns a copy of this color with the value parameter replaced with the given value.
HSVColor withValue(double value) { HSVColor withValue(double value) {
return new HSVColor.fromAHSV(alpha, hue, saturation, value); return new HSVColor.fromAHSV(alpha, hue, saturation, value);
} }
......
...@@ -11,14 +11,14 @@ import 'basic_types.dart'; ...@@ -11,14 +11,14 @@ import 'basic_types.dart';
/// Typically used for an offset from each of the four sides of a box. For /// Typically used for an offset from each of the four sides of a box. For
/// example, the padding inside a box can be represented using this class. /// example, the padding inside a box can be represented using this class.
class EdgeInsets { class EdgeInsets {
/// Constructs insets from offsets from the left, top, right, and bottom. /// Creates insets from offsets from the left, top, right, and bottom.
const EdgeInsets.fromLTRB(this.left, this.top, this.right, this.bottom); const EdgeInsets.fromLTRB(this.left, this.top, this.right, this.bottom);
/// Constructs insets where all the offsets are value. /// Creates insets where all the offsets are value.
const EdgeInsets.all(double value) const EdgeInsets.all(double value)
: left = value, top = value, right = value, bottom = value; : left = value, top = value, right = value, bottom = value;
/// Constructs insets with only the given values non-zero. /// Creates insets with only the given values non-zero.
const EdgeInsets.only({ const EdgeInsets.only({
this.left: 0.0, this.left: 0.0,
this.top: 0.0, this.top: 0.0,
...@@ -26,11 +26,12 @@ class EdgeInsets { ...@@ -26,11 +26,12 @@ class EdgeInsets {
this.bottom: 0.0 this.bottom: 0.0
}); });
/// Constructs insets with symmetrical vertical and horizontal offsets. /// Creates insets with symmetrical vertical and horizontal offsets.
const EdgeInsets.symmetric({ double vertical: 0.0, const EdgeInsets.symmetric({ double vertical: 0.0,
double horizontal: 0.0 }) double horizontal: 0.0 })
: left = horizontal, top = vertical, right = horizontal, bottom = vertical; : left = horizontal, top = vertical, right = horizontal, bottom = vertical;
/// Creates insets that match the given window padding.
EdgeInsets.fromWindowPadding(ui.WindowPadding padding) EdgeInsets.fromWindowPadding(ui.WindowPadding padding)
: left = padding.left, top = padding.top, right = padding.right, bottom = padding.bottom; : left = padding.left, top = padding.top, right = padding.right, bottom = padding.bottom;
...@@ -61,10 +62,16 @@ class EdgeInsets { ...@@ -61,10 +62,16 @@ class EdgeInsets {
/// An EdgeInsets with top and bottom as well as left and right flipped. /// An EdgeInsets with top and bottom as well as left and right flipped.
EdgeInsets get flipped => new EdgeInsets.fromLTRB(left, top, right, bottom); EdgeInsets get flipped => new EdgeInsets.fromLTRB(left, top, right, bottom);
/// Returns a new rect that is bigger than the given rect in each direction by
/// the amount of inset in each direction. Specifically, the left edge of the
/// rect is moved left by [left], the top edge of the rect is moved up by
/// [top], the right edge of the rect is moved right by [right], and the
/// bottom edge of the rect is moved down by [bottom].
Rect inflateRect(Rect rect) { Rect inflateRect(Rect rect) {
return new Rect.fromLTRB(rect.left - left, rect.top - top, rect.right + right, rect.bottom + bottom); return new Rect.fromLTRB(rect.left - left, rect.top - top, rect.right + right, rect.bottom + bottom);
} }
/// Returns the difference between two EdgeInsets.
EdgeInsets operator -(EdgeInsets other) { EdgeInsets operator -(EdgeInsets other) {
return new EdgeInsets.fromLTRB( return new EdgeInsets.fromLTRB(
left - other.left, left - other.left,
...@@ -74,6 +81,7 @@ class EdgeInsets { ...@@ -74,6 +81,7 @@ class EdgeInsets {
); );
} }
/// Returns the sum of two EdgeInsets.
EdgeInsets operator +(EdgeInsets other) { EdgeInsets operator +(EdgeInsets other) {
return new EdgeInsets.fromLTRB( return new EdgeInsets.fromLTRB(
left + other.left, left + other.left,
...@@ -83,6 +91,7 @@ class EdgeInsets { ...@@ -83,6 +91,7 @@ class EdgeInsets {
); );
} }
/// Scales the EdgeInsets in each dimension by the given factor.
EdgeInsets operator *(double other) { EdgeInsets operator *(double other) {
return new EdgeInsets.fromLTRB( return new EdgeInsets.fromLTRB(
left * other, left * other,
...@@ -92,6 +101,7 @@ class EdgeInsets { ...@@ -92,6 +101,7 @@ class EdgeInsets {
); );
} }
/// Divides the EdgeInsets in each dimension by the given factor.
EdgeInsets operator /(double other) { EdgeInsets operator /(double other) {
return new EdgeInsets.fromLTRB( return new EdgeInsets.fromLTRB(
left / other, left / other,
...@@ -101,6 +111,7 @@ class EdgeInsets { ...@@ -101,6 +111,7 @@ class EdgeInsets {
); );
} }
/// Integer divides the EdgeInsets in each dimension by the given factor.
EdgeInsets operator ~/(double other) { EdgeInsets operator ~/(double other) {
return new EdgeInsets.fromLTRB( return new EdgeInsets.fromLTRB(
(left ~/ other).toDouble(), (left ~/ other).toDouble(),
...@@ -110,6 +121,7 @@ class EdgeInsets { ...@@ -110,6 +121,7 @@ class EdgeInsets {
); );
} }
/// Computes the remainder in each dimension by the given factor.
EdgeInsets operator %(double other) { EdgeInsets operator %(double other) {
return new EdgeInsets.fromLTRB( return new EdgeInsets.fromLTRB(
left % other, left % other,
......
...@@ -8,6 +8,13 @@ export 'dart:ui' show TextAffinity, TextPosition; ...@@ -8,6 +8,13 @@ export 'dart:ui' show TextAffinity, TextPosition;
/// A range of characters in a string of text. /// A range of characters in a string of text.
class TextRange { class TextRange {
/// Creates a text range.
///
/// The [start] and [end] arguments must not be null. Both the [start] and
/// [end] must either be greater than or equal to zero or both exactly -1.
///
/// Instead of creating an empty text range, consider using the [empty]
/// constant.
const TextRange({ this.start, this.end }); const TextRange({ this.start, this.end });
/// A text range that starts and ends at offset. /// A text range that starts and ends at offset.
...@@ -19,9 +26,13 @@ class TextRange { ...@@ -19,9 +26,13 @@ class TextRange {
static const TextRange empty = const TextRange(start: -1, end: -1); static const TextRange empty = const TextRange(start: -1, end: -1);
/// The index of the first character in the range. /// The index of the first character in the range.
///
/// If [start] and [end] are both -1, the text range is empty.
final int start; final int start;
/// The next index after the characters in this range. /// The next index after the characters in this range.
///
/// If [start] and [end] are both -1, the text range is empty.
final int end; final int end;
/// Whether this range represents a valid position in the text. /// Whether this range represents a valid position in the text.
...@@ -74,6 +85,9 @@ class TextRange { ...@@ -74,6 +85,9 @@ class TextRange {
/// A range of text that represents a selection. /// A range of text that represents a selection.
class TextSelection extends TextRange { class TextSelection extends TextRange {
/// Creates a text selection.
///
/// The [baseOffset] and [extentOffset] arguments must not be null.
const TextSelection({ const TextSelection({
int baseOffset, int baseOffset,
int extentOffset, int extentOffset,
...@@ -86,11 +100,23 @@ class TextSelection extends TextRange { ...@@ -86,11 +100,23 @@ class TextSelection extends TextRange {
end: baseOffset < extentOffset ? extentOffset : baseOffset end: baseOffset < extentOffset ? extentOffset : baseOffset
); );
/// Creates a collapsed selection at the given offset.
///
/// A collapsed selection starts and ends at the same offset, which means it
/// contains zero characters but instead serves as an insertion point in the
/// text.
///
/// The [offset] argument must not be null.
const TextSelection.collapsed({ const TextSelection.collapsed({
int offset, int offset,
this.affinity: TextAffinity.downstream this.affinity: TextAffinity.downstream
}) : baseOffset = offset, extentOffset = offset, isDirectional = false, super.collapsed(offset); }) : baseOffset = offset, extentOffset = offset, isDirectional = false, super.collapsed(offset);
/// Creates a collapsed selection at the given text position.
///
/// A collapsed selection starts and ends at the same offset, which means it
/// contains zero characters but instead serves as an insertion point in the
/// text.
TextSelection.fromPosition(TextPosition position) TextSelection.fromPosition(TextPosition position)
: baseOffset = position.offset, : baseOffset = position.offset,
extentOffset = position.offset, extentOffset = position.offset,
......
...@@ -229,6 +229,13 @@ class TextPainter { ...@@ -229,6 +229,13 @@ class TextPainter {
return _paragraph.getPositionForOffset(offset); return _paragraph.getPositionForOffset(offset);
} }
/// Returns the text range of the word at the given offset. Characters not
/// part of a word, such as spaces, symbols, and punctuation, have word breaks
/// on both sides. In such cases, this method will return a text range that
/// contains the given text position.
///
/// Word boundaries are defined more precisely in Unicode Standard Annex #29
/// <http://www.unicode.org/reports/tr29/#Word_Boundaries>.
TextRange getWordBoundary(TextPosition position) { TextRange getWordBoundary(TextPosition position) {
assert(!_needsLayout); assert(!_needsLayout);
List<int> indices = _paragraph.getWordBoundary(position.offset); List<int> indices = _paragraph.getWordBoundary(position.offset);
......
...@@ -9,6 +9,7 @@ import 'package:vector_math/vector_math_64.dart'; ...@@ -9,6 +9,7 @@ import 'package:vector_math/vector_math_64.dart';
import 'basic_types.dart'; import 'basic_types.dart';
/// Utility functions for working with matrices.
class MatrixUtils { class MatrixUtils {
MatrixUtils._(); MatrixUtils._();
...@@ -68,6 +69,7 @@ class MatrixUtils { ...@@ -68,6 +69,7 @@ class MatrixUtils {
&& a.storage[15] == b.storage[15]; && a.storage[15] == b.storage[15];
} }
/// Whether the given matrix is the identity matrix.
static bool isIdentity(Matrix4 a) { static bool isIdentity(Matrix4 a) {
assert(a != null); assert(a != null);
return a.storage[0] == 1.0 // col 1 return a.storage[0] == 1.0 // col 1
...@@ -88,6 +90,10 @@ class MatrixUtils { ...@@ -88,6 +90,10 @@ class MatrixUtils {
&& a.storage[15] == 1.0; && a.storage[15] == 1.0;
} }
/// Applies the given matrix as a perspective transform to the given point.
///
/// This function assumes the given point has a z-coordinate of 0.0. The
/// z-coordinate of the result is ignored.
static Point transformPoint(Matrix4 transform, Point point) { static Point transformPoint(Matrix4 transform, Point point) {
Vector3 position3 = new Vector3(point.x, point.y, 0.0); Vector3 position3 = new Vector3(point.x, point.y, 0.0);
Vector3 transformed3 = transform.perspectiveTransform(position3); Vector3 transformed3 = transform.perspectiveTransform(position3);
...@@ -101,6 +107,12 @@ class MatrixUtils { ...@@ -101,6 +107,12 @@ class MatrixUtils {
return math.max(a, math.max(b, math.max(c, d))); return math.max(a, math.max(b, math.max(c, d)));
} }
/// Returns a rect that bounds the result of applying the given matrix as a
/// perspective transform to the given rect.
///
/// This function assumes the given rect is in the plane with z equals 0.0.
/// The transformed rect is then projected back into the plane with z equals
/// 0.0 before computing its bounding rect.
static Rect transformRect(Rect rect, Matrix4 transform) { static Rect transformRect(Rect rect, Matrix4 transform) {
assert(rect != null); assert(rect != null);
assert(transform.determinant != 0.0); assert(transform.determinant != 0.0);
......
...@@ -41,9 +41,9 @@ enum Axis { ...@@ -41,9 +41,9 @@ enum Axis {
/// * `0.0 <= minWidth <= maxWidth <= double.INFINITY` /// * `0.0 <= minWidth <= maxWidth <= double.INFINITY`
/// * `0.0 <= minHeight <= maxHeight <= double.INFINITY` /// * `0.0 <= minHeight <= maxHeight <= double.INFINITY`
/// ///
/// Note: `double.INFINITY` is a legal value for each constraint. /// [double.INFINITY] is a legal value for each constraint.
class BoxConstraints extends Constraints { class BoxConstraints extends Constraints {
/// Constructs box constraints with the given constraints /// Creates box constraints with the given constraints.
const BoxConstraints({ const BoxConstraints({
this.minWidth: 0.0, this.minWidth: 0.0,
this.maxWidth: double.INFINITY, this.maxWidth: double.INFINITY,
...@@ -51,19 +51,30 @@ class BoxConstraints extends Constraints { ...@@ -51,19 +51,30 @@ class BoxConstraints extends Constraints {
this.maxHeight: double.INFINITY this.maxHeight: double.INFINITY
}); });
/// The minimum width that satisfies the constraints.
final double minWidth; final double minWidth;
/// The maximum width that satisfies the constraints.
///
/// Might be [double.INFINITY].
final double maxWidth; final double maxWidth;
/// The minimum height that satisfies the constraints.
final double minHeight; final double minHeight;
/// The maximum height that satisfies the constraints.
///
/// Might be [double.INFINITY].
final double maxHeight; final double maxHeight;
/// Constructs box constraints that is respected only by the given size. /// Creates box constraints that is respected only by the given size.
BoxConstraints.tight(Size size) BoxConstraints.tight(Size size)
: minWidth = size.width, : minWidth = size.width,
maxWidth = size.width, maxWidth = size.width,
minHeight = size.height, minHeight = size.height,
maxHeight = size.height; maxHeight = size.height;
/// Constructs box constraints that require the given width or height. /// Creates box constraints that require the given width or height.
const BoxConstraints.tightFor({ const BoxConstraints.tightFor({
double width, double width,
double height double height
...@@ -72,14 +83,14 @@ class BoxConstraints extends Constraints { ...@@ -72,14 +83,14 @@ class BoxConstraints extends Constraints {
minHeight = height != null ? height : 0.0, minHeight = height != null ? height : 0.0,
maxHeight = height != null ? height : double.INFINITY; maxHeight = height != null ? height : double.INFINITY;
/// Constructs box constraints that forbid sizes larger than the given size. /// Creates box constraints that forbid sizes larger than the given size.
BoxConstraints.loose(Size size) BoxConstraints.loose(Size size)
: minWidth = 0.0, : minWidth = 0.0,
maxWidth = size.width, maxWidth = size.width,
minHeight = 0.0, minHeight = 0.0,
maxHeight = size.height; maxHeight = size.height;
/// Constructs box constraints that expand to fill another box contraints. /// Creates box constraints that expand to fill another box contraints.
/// ///
/// If width or height is given, the constraints will require exactly the /// If width or height is given, the constraints will require exactly the
/// given value in the given dimension. /// given value in the given dimension.
......
...@@ -25,7 +25,7 @@ const double _kMaxHeight = 100000.0; ...@@ -25,7 +25,7 @@ const double _kMaxHeight = 100000.0;
/// Again to help simplify the class, this box tries to be 100000.0 pixels wide /// Again to help simplify the class, this box tries to be 100000.0 pixels wide
/// and high, to approximate being infinitely high but without using infinities. /// and high, to approximate being infinitely high but without using infinities.
class RenderErrorBox extends RenderBox { class RenderErrorBox extends RenderBox {
/// Constructs a RenderErrorBox render object. /// Creates a RenderErrorBox render object.
/// ///
/// A message can optionally be provided. If a message is provided, an attempt /// A message can optionally be provided. If a message is provided, an attempt
/// will be made to render the message when the box paints. /// will be made to render the message when the box paints.
......
...@@ -1316,7 +1316,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget { ...@@ -1316,7 +1316,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// Subclasses that set [sizedByParent] to true should override this function /// Subclasses that set [sizedByParent] to true should override this function
/// to compute their size. /// to compute their size.
/// ///
/// Note: This function is called only if [sizedByParent] is true. /// This function is called only if [sizedByParent] is true.
void performResize(); void performResize();
/// Do the work of computing the layout for this render object. /// Do the work of computing the layout for this render object.
......
...@@ -115,7 +115,7 @@ typedef void GlobalKeyRemoveListener(GlobalKey key); ...@@ -115,7 +115,7 @@ typedef void GlobalKeyRemoveListener(GlobalKey key);
/// [UniqueKey] instead. /// [UniqueKey] instead.
@optionalTypeArgs @optionalTypeArgs
abstract class GlobalKey<T extends State<StatefulWidget>> extends Key { abstract class GlobalKey<T extends State<StatefulWidget>> extends Key {
/// Constructs a LabeledGlobalKey, which is a GlobalKey with a label used for debugging. /// Creates a LabeledGlobalKey, which is a GlobalKey with a label used for debugging.
/// The label is not used for comparing the identity of the key. /// The label is not used for comparing the identity of the key.
factory GlobalKey({ String debugLabel }) => new LabeledGlobalKey<T>(debugLabel); // the label is purely for debugging purposes and is otherwise ignored factory GlobalKey({ String debugLabel }) => new LabeledGlobalKey<T>(debugLabel); // the label is purely for debugging purposes and is otherwise ignored
...@@ -564,7 +564,7 @@ abstract class RenderObjectWidget extends Widget { ...@@ -564,7 +564,7 @@ abstract class RenderObjectWidget extends Widget {
@override @override
RenderObjectElement createElement(); RenderObjectElement createElement();
/// Constructs an instance of the RenderObject class that this /// Creates an instance of the RenderObject class that this
/// RenderObjectWidget represents, using the configuration described by this /// RenderObjectWidget represents, using the configuration described by this
/// RenderObjectWidget. /// RenderObjectWidget.
RenderObject createRenderObject(BuildContext context); RenderObject createRenderObject(BuildContext context);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment