Skip to content

F
Front-End
Commit 8294b96f authored by Adam Barth's avatar Adam Barth
Browse files
Options

Complete dartdocs for painting.dart (#4003)

parent 4e1108e7
Hide whitespace changes
Inline Side-by-side
Showing with 203 additions and 32 deletions
packages/flutter/lib/src/painting/box_painter.dart
View file @ 8294b96f
......@@ -38,6 +38,9 @@ enum BorderStyle {
/// A side of a border of a box.
class BorderSide {
/// Creates the side of a border.
///
/// By default, the border is 1.0 logical pixels wide and solid black.
const BorderSide({
this.color: const Color(0xFF000000),
this.width: 1.0,
......@@ -134,6 +137,9 @@ class BorderSide {
/// A border of a box, comprised of four sides.
class Border {
/// Creates a border.
///
/// All the sides of the border default to [BorderSide.none].
const Border({
this.top: BorderSide.none,
this.right: BorderSide.none,
......@@ -222,6 +228,7 @@ class Border {
);
}
/// Paints the border within the given rect on the given canvas.
void paint(Canvas canvas, Rect rect, {
BoxShape shape: BoxShape.rectangle,
double borderRadius: null
......@@ -373,14 +380,19 @@ class Border {
/// A shadow cast by a box.
///
/// Note: BoxShadow can cast non-rectangular shadows if the box is
/// non-rectangular (e.g., has a border radius or a circular shape).
/// BoxShadow can cast non-rectangular shadows if the box is non-rectangular
/// (e.g., has a border radius or a circular shape).
///
/// This class is similar to CSS box-shadow.
class BoxShadow {
/// Creates a box shadow.
///
/// By default, the shadow is solid black with zero [offset], [blurRadius],
/// and [spreadRadius].
const BoxShadow({
this.color,
this.offset,
this.blurRadius,
this.color: const Color(0xFF000000),
this.offset: Offset.zero,
this.blurRadius: 0.0,
this.spreadRadius: 0.0
});
......@@ -393,6 +405,7 @@ class BoxShadow {
/// The standard deviation of the Gaussian to convolve with the box's shape.
final double blurRadius;
/// The amount the box should be inflated prior to applying the blur.
final double spreadRadius;
/// The [blurRadius] in sigmas instead of logical pixels.
......@@ -479,11 +492,17 @@ abstract class Gradient {
/// Abstract const constructor. This constructor enables subclasses to provide
/// const constructors so that they can be used in const expressions.
const Gradient();
/// Creates a [Shader] for this gradient to fill the given rect.
Shader createShader(Rect rect);
}
/// A 2D linear 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({
this.begin: FractionalOffset.centerLeft,
this.end: FractionalOffset.centerRight,
......@@ -510,13 +529,14 @@ class LinearGradient extends Gradient {
/// 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;
/// 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
/// are distributed evenly between [begin] and [end].
/// If non-null, this list must have the same length as [colors]. Otherwise
/// the colors are distributed evenly between [begin] and [end].
final List<double> stops;
/// How this gradient should tile the plane.
......@@ -573,6 +593,10 @@ class LinearGradient extends Gradient {
/// A 2D radial 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({
this.center: FractionalOffset.center,
this.radius: 0.5,
......@@ -598,7 +622,7 @@ class RadialGradient extends Gradient {
/// 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;
/// A list of values from 0.0 to 1.0 that denote concentric rings.
......@@ -606,7 +630,9 @@ class RadialGradient extends Gradient {
/// The rings are centered at [center] and have a radius equal to the value of
/// 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;
/// How this gradient should tile the plane.
......@@ -855,51 +881,96 @@ void paintImage({
/// FractionalOffset(1.0, 0.0) represents the top right of the Size,
/// FractionalOffset(0.0, 1.0) represents the bottom left of the Size,
class FractionalOffset {
/// Creates a fractional offset.
///
/// The [dx] and [dy] arguments must not be null.
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;
/// 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;
/// The top left corner.
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);
/// The top right corner.
static const FractionalOffset topRight = const FractionalOffset(1.0, 0.0);
/// The bottom left corner.
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);
/// The bottom right corner.
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);
/// The center point along the right edge.
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);
/// Returns the negation of the given fractional offset.
FractionalOffset operator -() {
return new FractionalOffset(-dx, -dy);
}
/// Returns the difference between two fractional offsets.
FractionalOffset operator -(FractionalOffset other) {
return new FractionalOffset(dx - other.dx, dy - other.dy);
}
/// Returns the sum of two fractional offsets.
FractionalOffset operator +(FractionalOffset other) {
return new FractionalOffset(dx + other.dx, dy + other.dy);
}
/// Scales the fractional offset in each dimension by the given factor.
FractionalOffset operator *(double other) {
return new FractionalOffset(dx * other, dy * other);
}
/// Divides the fractional offset in each dimension by the given factor.
FractionalOffset operator /(double other) {
return new FractionalOffset(dx / other, dy / other);
}
/// Integer divides the fractional offset in each dimension by the given factor.
FractionalOffset operator ~/(double other) {
return new FractionalOffset((dx ~/ other).toDouble(), (dy ~/ other).toDouble());
}
/// Computes the remainder in each dimension by the given factor.
FractionalOffset operator %(double 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) {
return new Offset(dx * other.dx, dy * other.dy);
}
/// Returns the offset that is this fraction within the given size.
Offset alongSize(Size other) {
return new Offset(dx * other.width, dy * other.height);
}
/// Returns the point that is this fraction within the given rect.
Point withinRect(Rect rect) {
return new Point(rect.left + dx * rect.width, rect.top + dy * rect.height);
}
......@@ -915,6 +986,12 @@ class FractionalOffset {
@override
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) {
if (a == null && b == null)
return null;
......@@ -931,6 +1008,9 @@ class FractionalOffset {
/// A background image for a box.
class BackgroundImage {
/// Creates a background image.
///
/// The [image] argument must not be null.
BackgroundImage({
ImageResource image,
this.fit,
......@@ -1041,13 +1121,23 @@ enum BoxShape {
/// An immutable description of how to paint a box.
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({
this.backgroundColor, // null = don't draw background color
this.backgroundImage, // null = don't draw background image
this.border, // null = don't draw border
this.borderRadius, // null = use more efficient background drawing; note that this must be null for circles
this.boxShadow, // null = don't draw shadows
this.gradient, // null = don't allocate gradient objects
this.backgroundColor,
this.backgroundImage,
this.border,
this.borderRadius,
this.boxShadow,
this.gradient,
this.shape: BoxShape.rectangle
});
......@@ -1319,7 +1409,7 @@ class _BoxDecorationPainter extends BoxPainter {
image: image,
colorFilter: backgroundImage.colorFilter,
alignment: backgroundImage.alignment,
fit: backgroundImage.fit,
fit: backgroundImage.fit,
repeat: backgroundImage.repeat
);
}
......
packages/flutter/lib/src/painting/colors.dart
View file @ 8294b96f
......@@ -4,7 +4,16 @@
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 {
/// 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);
/// Alpha, from 0.0 to 1.0.
......@@ -19,18 +28,22 @@ class HSVColor {
/// Value, from 0.0 to 1.0.
final double value;
/// Returns a copy of this color with the alpha parameter replaced with the given value.
HSVColor withAlpha(double alpha) {
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) {
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) {
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) {
return new HSVColor.fromAHSV(alpha, hue, saturation, value);
}
......
packages/flutter/lib/src/painting/edge_insets.dart
View file @ 8294b96f
......@@ -11,14 +11,14 @@ import 'basic_types.dart';
/// 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.
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);
/// Constructs insets where all the offsets are value.
/// Creates insets where all the offsets are value.
const EdgeInsets.all(double 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({
this.left: 0.0,
this.top: 0.0,
......@@ -26,11 +26,12 @@ class EdgeInsets {
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,
double horizontal: 0.0 })
: left = horizontal, top = vertical, right = horizontal, bottom = vertical;
/// Creates insets that match the given window padding.
EdgeInsets.fromWindowPadding(ui.WindowPadding padding)
: left = padding.left, top = padding.top, right = padding.right, bottom = padding.bottom;
......@@ -61,10 +62,16 @@ class EdgeInsets {
/// An EdgeInsets with top and bottom as well as left and right flipped.
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) {
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) {
return new EdgeInsets.fromLTRB(
left - other.left,
......@@ -74,6 +81,7 @@ class EdgeInsets {
);
}
/// Returns the sum of two EdgeInsets.
EdgeInsets operator +(EdgeInsets other) {
return new EdgeInsets.fromLTRB(
left + other.left,
......@@ -83,6 +91,7 @@ class EdgeInsets {
);
}
/// Scales the EdgeInsets in each dimension by the given factor.
EdgeInsets operator *(double other) {
return new EdgeInsets.fromLTRB(
left * other,
......@@ -92,6 +101,7 @@ class EdgeInsets {
);
}
/// Divides the EdgeInsets in each dimension by the given factor.
EdgeInsets operator /(double other) {
return new EdgeInsets.fromLTRB(
left / other,
......@@ -101,6 +111,7 @@ class EdgeInsets {
);
}
/// Integer divides the EdgeInsets in each dimension by the given factor.
EdgeInsets operator ~/(double other) {
return new EdgeInsets.fromLTRB(
(left ~/ other).toDouble(),
......@@ -110,6 +121,7 @@ class EdgeInsets {
);
}
/// Computes the remainder in each dimension by the given factor.
EdgeInsets operator %(double other) {
return new EdgeInsets.fromLTRB(
left % other,
......
packages/flutter/lib/src/painting/text_editing.dart
View file @ 8294b96f
......@@ -8,6 +8,13 @@ export 'dart:ui' show TextAffinity, TextPosition;
/// A range of characters in a string of text.
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 });
/// A text range that starts and ends at offset.
......@@ -19,9 +26,13 @@ class TextRange {
static const TextRange empty = const TextRange(start: -1, end: -1);
/// The index of the first character in the range.
///
/// If [start] and [end] are both -1, the text range is empty.
final int start;
/// The next index after the characters in this range.
///
/// If [start] and [end] are both -1, the text range is empty.
final int end;
/// Whether this range represents a valid position in the text.
......@@ -74,6 +85,9 @@ class TextRange {
/// A range of text that represents a selection.
class TextSelection extends TextRange {
/// Creates a text selection.
///
/// The [baseOffset] and [extentOffset] arguments must not be null.
const TextSelection({
int baseOffset,
int extentOffset,
......@@ -86,11 +100,23 @@ class TextSelection extends TextRange {
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({
int offset,
this.affinity: TextAffinity.downstream
}) : 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)
: baseOffset = position.offset,
extentOffset = position.offset,
......
packages/flutter/lib/src/painting/text_painter.dart
View file @ 8294b96f
......@@ -229,6 +229,13 @@ class TextPainter {
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) {
assert(!_needsLayout);
List<int> indices = _paragraph.getWordBoundary(position.offset);
......
packages/flutter/lib/src/painting/transforms.dart
View file @ 8294b96f
......@@ -9,6 +9,7 @@ import 'package:vector_math/vector_math_64.dart';
import 'basic_types.dart';
/// Utility functions for working with matrices.
class MatrixUtils {
MatrixUtils._();
......@@ -68,6 +69,7 @@ class MatrixUtils {
&& a.storage[15] == b.storage[15];
}
/// Whether the given matrix is the identity matrix.
static bool isIdentity(Matrix4 a) {
assert(a != null);
return a.storage[0] == 1.0 // col 1
......@@ -88,6 +90,10 @@ class MatrixUtils {
&& 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) {
Vector3 position3 = new Vector3(point.x, point.y, 0.0);
Vector3 transformed3 = transform.perspectiveTransform(position3);
......@@ -101,6 +107,12 @@ class MatrixUtils {
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) {
assert(rect != null);
assert(transform.determinant != 0.0);
......
packages/flutter/lib/src/rendering/box.dart
View file @ 8294b96f
......@@ -41,9 +41,9 @@ enum Axis {
/// * `0.0 <= minWidth <= maxWidth <= 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 {
/// Constructs box constraints with the given constraints
/// Creates box constraints with the given constraints.
const BoxConstraints({
this.minWidth: 0.0,
this.maxWidth: double.INFINITY,
......@@ -51,19 +51,30 @@ class BoxConstraints extends Constraints {
this.maxHeight: double.INFINITY
});
/// The minimum width that satisfies the constraints.
final double minWidth;
/// The maximum width that satisfies the constraints.
///
/// Might be [double.INFINITY].
final double maxWidth;
/// The minimum height that satisfies the constraints.
final double minHeight;
/// The maximum height that satisfies the constraints.
///
/// Might be [double.INFINITY].
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)
: minWidth = size.width,
maxWidth = size.width,
minHeight = 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({
double width,
double height
......@@ -72,14 +83,14 @@ class BoxConstraints extends Constraints {
minHeight = height != null ? height : 0.0,
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)
: minWidth = 0.0,
maxWidth = size.width,
minHeight = 0.0,
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
/// given value in the given dimension.
......
packages/flutter/lib/src/rendering/error.dart
View file @ 8294b96f
......@@ -25,7 +25,7 @@ const double _kMaxHeight = 100000.0;
/// 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.
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
/// will be made to render the message when the box paints.
......
packages/flutter/lib/src/rendering/object.dart
View file @ 8294b96f
......@@ -1316,7 +1316,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// Subclasses that set [sizedByParent] to true should override this function
/// 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();
/// Do the work of computing the layout for this render object.
......
packages/flutter/lib/src/widgets/framework.dart
View file @ 8294b96f
......@@ -115,7 +115,7 @@ typedef void GlobalKeyRemoveListener(GlobalKey key);
/// [UniqueKey] instead.
@optionalTypeArgs
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.
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 {
@override
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.
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

HIAST - GitLab