From b5aba601472a59c2cfced5702650ee9b695c3f34 Mon Sep 17 00:00:00 2001 From: Florian Loitsch Date: Tue, 8 Dec 2015 18:20:23 -0800 Subject: [PATCH] Minor modifs. --- .../lib/src/animation/animated_value.dart | 19 ++- .../flutter/lib/src/animation/curves.dart | 55 +++++---- .../flutter/lib/src/animation/forces.dart | 14 +-- .../lib/src/animation/performance.dart | 58 ++++----- .../lib/src/animation/scroll_behavior.dart | 22 ++-- .../lib/src/animation/simulation_stepper.dart | 16 +-- .../flutter/lib/src/animation/ticker.dart | 6 +- packages/flutter/lib/src/gestures/arena.dart | 11 +- .../flutter/lib/src/gestures/lsq_solver.dart | 6 +- .../flutter/lib/src/gestures/multitap.dart | 4 +- .../lib/src/gestures/pointer_router.dart | 2 +- .../flutter/lib/src/gestures/recognizer.dart | 18 +-- packages/flutter/lib/src/http/http.dart | 7 +- .../flutter/lib/src/http/mojo_client.dart | 2 +- .../flutter/lib/src/painting/box_painter.dart | 115 +++++++++--------- .../flutter/lib/src/painting/shadows.dart | 2 +- .../lib/src/painting/text_painter.dart | 36 +++--- .../flutter/lib/src/painting/text_style.dart | 2 +- .../flutter/lib/src/painting/transforms.dart | 10 +- .../lib/src/rendering/auto_layout.dart | 16 +-- .../flutter/lib/src/rendering/binding.dart | 23 ++-- packages/flutter/lib/src/rendering/block.dart | 39 +++--- 22 files changed, 247 insertions(+), 236 deletions(-) diff --git a/packages/flutter/lib/src/animation/animated_value.dart b/packages/flutter/lib/src/animation/animated_value.dart index 88a5ee036f0..ad49d46c8e5 100644 --- a/packages/flutter/lib/src/animation/animated_value.dart +++ b/packages/flutter/lib/src/animation/animated_value.dart @@ -6,12 +6,12 @@ import 'dart:ui' show Color, Size, Rect; import 'curves.dart'; -/// The direction in which an animation is running +/// The direction in which an animation is running. enum AnimationDirection { - /// The animation is running from beginning to end + /// The animation is running from beginning to end. forward, - /// The animation is running backwards, from end to beginning + /// The animation is running backwards, from end to beginning. reverse } @@ -43,12 +43,12 @@ class AnimatedValue implements Animatable { /// Returns the value this variable has at the given animation clock value. T lerp(double t) => begin + (end - begin) * t; - /// The curve to use in the forward direction + /// The curve to use in the forward direction. Curve curve; - /// The curve to use in the reverse direction + /// The curve to use in the reverse direction. /// - /// If this field is null, use [curve] in both directions. + /// If this field is null, uses [curve] in both directions. Curve reverseCurve; Curve _getActiveCurve(AnimationDirection direction) { @@ -57,7 +57,6 @@ class AnimatedValue implements Animatable { return reverseCurve; } - /// Applies this timing to the given animation clock value in the given direction double transform(double t, AnimationDirection direction) { Curve activeCurve = _getActiveCurve(direction); if (activeCurve == null) @@ -120,13 +119,11 @@ class AnimatedRectValue extends AnimatedValue { } /// An animated variable containing a int. -/// -/// The inherited lerp() function doesn't work with ints because it multiplies -/// the begin and end types by a double, and int * double returns a double. -/// This class overrides the lerp() function to round off the result to an int. class AnimatedIntValue extends AnimatedValue { AnimatedIntValue(int begin, { int end, Curve curve, Curve reverseCurve }) : super(begin, end: end, curve: curve, reverseCurve: reverseCurve); + // The inherited lerp() function doesn't work with ints because it multiplies + // the begin and end types by a double, and int * double returns a double. int lerp(double t) => (begin + (end - begin) * t).round(); } diff --git a/packages/flutter/lib/src/animation/curves.dart b/packages/flutter/lib/src/animation/curves.dart index ddbd71c3ab0..15791fb3419 100644 --- a/packages/flutter/lib/src/animation/curves.dart +++ b/packages/flutter/lib/src/animation/curves.dart @@ -5,7 +5,6 @@ import 'dart:math' as math; double _evaluateCubic(double a, double b, double m) { - // TODO(abarth): Would Math.pow be faster? return 3 * a * (1 - m) * (1 - m) * m + 3 * b * (1 - m) * m * m + m * m * m; } @@ -15,29 +14,29 @@ const double _kCubicErrorBound = 0.001; /// /// A curve must map 0.0 to 0.0 and 1.0 to 1.0. abstract class Curve { - /// Return the value of the curve at point t + /// Returns the value of the curve at point [t]. /// - /// The value of t must be between 0.0 and 1.0, inclusive. + /// The value of [t] must be between 0.0 and 1.0, inclusive. double transform(double t); } -/// The identity map over the unit interval +/// The identity map over the unit interval. class Linear implements Curve { const Linear(); double transform(double t) => t; } -/// A curve that is 0.0 until start, then curved from 0.0 to 1.0 at end, then 1.0 +/// A curve that is 0.0 until start, then curved from 0.0 to 1.0 at end, then 1.0. class Interval implements Curve { const Interval(this.start, this.end, { this.curve: Curves.linear }); - /// The smallest value for which this interval is 0.0 + /// The smallest value for which this interval is 0.0. final double start; - /// The smallest value for which this interval is 1.0 + /// The smallest value for which this interval is 1.0. final double end; - /// The curve to apply between [start] and [end] + /// The curve to apply between [start] and [end]. final Curve curve; double transform(double t) { @@ -53,7 +52,7 @@ class Interval implements Curve { } } -/// A cubic polynomial mapping of the unit interval +/// A cubic polynomial mapping of the unit interval. class Cubic implements Curve { const Cubic(this.a, this.b, this.c, this.d); @@ -92,7 +91,7 @@ double _bounce(double t) { return 7.5625 * t * t + 0.984375; } -/// An oscillating curve that grows in magnitude +/// An oscillating curve that grows in magnitude. class BounceInCurve implements Curve { const BounceInCurve(); double transform(double t) { @@ -100,7 +99,7 @@ class BounceInCurve implements Curve { } } -/// An oscillating curve that shrink in magnitude +/// An oscillating curve that shrink in magnitude. class BounceOutCurve implements Curve { const BounceOutCurve(); double transform(double t) { @@ -108,7 +107,7 @@ class BounceOutCurve implements Curve { } } -/// An oscillating curve that first grows and then shrink in magnitude +/// An oscillating curve that first grows and then shrink in magnitude. class BounceInOutCurve implements Curve { const BounceInOutCurve(); double transform(double t) { @@ -119,7 +118,7 @@ class BounceInOutCurve implements Curve { } } -/// An oscillating curve that grows in magnitude while overshootings its bounds +/// An oscillating curve that grows in magnitude while overshooting its bounds. class ElasticInCurve implements Curve { const ElasticInCurve([this.period = 0.4]); final double period; @@ -130,7 +129,7 @@ class ElasticInCurve implements Curve { } } -/// An oscillating curve that shrinks in magnitude while overshootings its bounds +/// An oscillating curve that shrinks in magnitude while overshooting its bounds. class ElasticOutCurve implements Curve { const ElasticOutCurve([this.period = 0.4]); final double period; @@ -140,7 +139,7 @@ class ElasticOutCurve implements Curve { } } -/// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds +/// An oscillating curve that grows and then shrinks in magnitude while overshooting its bounds. class ElasticInOutCurve implements Curve { const ElasticInOutCurve([this.period = 0.4]); final double period; @@ -161,36 +160,40 @@ class Curves { /// A linear animation curve static const Linear linear = const Linear(); - /// A cubic animation curve that speeds up quickly and ends slowly + /// A cubic animation curve that speeds up quickly and ends slowly. static const Cubic ease = const Cubic(0.25, 0.1, 0.25, 1.0); - /// A cubic animation curve that starts slowly and ends quickly + /// A cubic animation curve that starts slowly and ends quickly. static const Cubic easeIn = const Cubic(0.42, 0.0, 1.0, 1.0); - /// A cubic animation curve that starts quickly and ends slowly + /// A cubic animation curve that starts quickly and ends slowly. static const Cubic easeOut = const Cubic(0.0, 0.0, 0.58, 1.0); - /// A cubic animation curve that starts slowly, speeds up, and then and ends slowly + /// A cubic animation curve that starts slowly, speeds up, and then and ends slowly. static const Cubic easeInOut = const Cubic(0.42, 0.0, 0.58, 1.0); - /// An oscillating curve that grows in magnitude + /// An oscillating curve that grows in magnitude. static const BounceInCurve bounceIn = const BounceInCurve(); - /// An oscillating curve that first grows and then shrink in magnitude + /// An oscillating curve that first grows and then shrink in magnitude. static const BounceOutCurve bounceOut = const BounceOutCurve(); - /// An oscillating curve that first grows and then shrink in magnitude + /// An oscillating curve that first grows and then shrink in magnitude. static const BounceInOutCurve bounceInOut = const BounceInOutCurve(); - /// An oscillating curve that grows in magnitude while overshootings its bounds + /// An oscillating curve that grows in magnitude while overshootings its bounds. static const ElasticInCurve elasticIn = const ElasticInCurve(); - /// An oscillating curve that shrinks in magnitude while overshootings its bounds + /// An oscillating curve that shrinks in magnitude while overshootings its bounds. static const ElasticOutCurve elasticOut = const ElasticOutCurve(); - /// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds + /// An oscillating curve that grows and then shrinks in magnitude while overshootings its bounds. static const ElasticInOutCurve elasticInOut = const ElasticInOutCurve(); - /// A curve that starts quickly and eases into its final position. Over the course of the animation, the object spends more time near its final destination. As a result, the user isn’t left waiting for the animation to finish, and the negative effects of motion are minimized. + /// A curve that starts quickly and eases into its final position. + /// + /// Over the course of the animation, the object spends more time near its + /// final destination. As a result, the user isn’t left waiting for the + /// animation to finish, and the negative effects of motion are minimized. static const Curve fastOutSlowIn = const Cubic(0.4, 0.0, 0.2, 1.0); } diff --git a/packages/flutter/lib/src/animation/forces.dart b/packages/flutter/lib/src/animation/forces.dart index 47cef10d810..00833c6129d 100644 --- a/packages/flutter/lib/src/animation/forces.dart +++ b/packages/flutter/lib/src/animation/forces.dart @@ -4,27 +4,27 @@ import 'package:newton/newton.dart'; -/// A factory for simulations +/// A factory for simulations. abstract class Force { const Force(); Simulation release(double position, double velocity); } -/// A factory for spring-based physics simulations +/// A factory for spring-based physics simulations. class SpringForce extends Force { const SpringForce(this.spring, { this.left: 0.0, this.right: 1.0 }); - /// The description of the spring to be used in the created simulations + /// The description of the spring to be used in the created simulations. final SpringDescription spring; - /// Where to put the spring's resting point when releasing left + /// Where to put the spring's resting point when releasing left. final double left; - /// Where to put the spring's resting point when releasing right + /// Where to put the spring's resting point when releasing right. final double right; - /// How pricely to terminate the simulation + /// How pricely to terminate the simulation. /// /// We overshoot the target by this distance, but stop the simulation when /// the spring gets within this distance (regardless of how fast it's moving). @@ -48,5 +48,5 @@ final SpringDescription _kDefaultSpringDesc = new SpringDescription.withDampingR ratio: 1.0 ); -/// A spring force with reasonable default values +/// A spring force with reasonable default values. final SpringForce kDefaultSpringForce = new SpringForce(_kDefaultSpringDesc); diff --git a/packages/flutter/lib/src/animation/performance.dart b/packages/flutter/lib/src/animation/performance.dart index e9ca421cc75..828dc1ebaea 100644 --- a/packages/flutter/lib/src/animation/performance.dart +++ b/packages/flutter/lib/src/animation/performance.dart @@ -13,22 +13,25 @@ import 'forces.dart'; import 'listener_helpers.dart'; import 'simulation_stepper.dart'; -/// An interface that is implemented by [Performance] that exposes a -/// read-only view of the underlying performance. This is used by classes that +/// A read-only view of a [Performance]. +/// +/// This interface is implemented by [Performance]. +/// +/// Read-only access to [Performance] is used by classes that /// want to watch a performance but should not be able to change the /// performance's state. abstract class PerformanceView { const PerformanceView(); - /// Update the given variable according to the current progress of the performance + /// Update the given variable according to the current progress of the performance. void updateVariable(Animatable variable); - /// Calls the listener every time the progress of the performance changes + /// Calls the listener every time the progress of the performance changes. void addListener(VoidCallback listener); - /// Stop calling the listener every time the progress of the performance changes + /// Stop calling the listener every time the progress of the performance changes. void removeListener(VoidCallback listener); - /// Calls listener every time the status of the performance changes + /// Calls listener every time the status of the performance changes. void addStatusListener(PerformanceStatusListener listener); - /// Stops calling the listener every time the status of the performance changes + /// Stops calling the listener every time the status of the performance changes. void removeStatusListener(PerformanceStatusListener listener); /// The current status of this animation. @@ -45,13 +48,15 @@ abstract class PerformanceView { AnimationDirection get curveDirection; /// The current progress of this animation (a value from 0.0 to 1.0). - /// This is the value that is used to update any variables when using updateVariable(). + /// + /// This is the value that is used to update any variables when using + /// [updateVariable]. double get progress; - /// Whether this animation is stopped at the beginning + /// Whether this animation is stopped at the beginning. bool get isDismissed => status == PerformanceStatus.dismissed; - /// Whether this animation is stopped at the end + /// Whether this animation is stopped at the end. bool get isCompleted => status == PerformanceStatus.completed; String toString() { @@ -556,7 +561,7 @@ class Performance extends PerformanceView _timeline.value = progress.clamp(0.0, 1.0); } - /// A label that is used in the toString() output. Intended to aid with + /// A label that is used in the [toString] output. Intended to aid with /// identifying performance instances in debug output. final String debugLabel; @@ -565,7 +570,7 @@ class Performance extends PerformanceView /// allowing users of that pointer to mutate the Performance state. PerformanceView get view => this; - /// The length of time this performance should last + /// The length of time this performance should last. Duration duration; SimulationStepper _timeline; @@ -574,7 +579,7 @@ class Performance extends PerformanceView AnimationDirection get curveDirection => _curveDirection; AnimationDirection _curveDirection = AnimationDirection.forward; - /// The progress of this performance along the timeline + /// The progress of this performance along the timeline. /// /// Note: Setting this value stops the current animation. double get progress => _timeline.value.clamp(0.0, 1.0); @@ -584,7 +589,7 @@ class Performance extends PerformanceView _checkStatusChanged(); } - /// Whether this animation is currently animating in either the forward or reverse direction + /// Whether this animation is currently animating in either the forward or reverse direction. bool get isAnimating => _timeline.isAnimating; PerformanceStatus get status { @@ -597,55 +602,52 @@ class Performance extends PerformanceView PerformanceStatus.reverse; } - /// Update the given varaible according to the current progress of this performance + /// Updates the given variable according to the current progress of this performance. void updateVariable(Animatable variable) { variable.setProgress(progress, _curveDirection); } - /// Start running this animation forwards (towards the end) + /// Starts running this animation forwards (towards the end). Future forward() => play(AnimationDirection.forward); - /// Start running this animation in reverse (towards the beginning) + /// Starts running this animation in reverse (towards the beginning). Future reverse() => play(AnimationDirection.reverse); - /// Start running this animation in the given direction + /// Starts running this animation in the given direction. Future play([AnimationDirection direction = AnimationDirection.forward]) { _direction = direction; return resume(); } - /// Start running this animation in the most recent direction + /// Resumes this animation in the most recent direction. Future resume() { return _animateTo(_direction == AnimationDirection.forward ? 1.0 : 0.0); } - /// Stop running this animation. + /// Stops running this animation. void stop() { _timeline.stop(); } - /// Release any resources used by this object. + /// Releases any resources used by this object. /// /// Same as stop(). void dispose() { stop(); } - /// Start running this animation according to the given physical parameters /// /// Flings the timeline with an optional force (defaults to a critically /// damped spring) and initial velocity. If velocity is positive, the /// animation will complete, otherwise it will dismiss. Future fling({double velocity: 1.0, Force force}) { - if (force == null) - force = kDefaultSpringForce; + force ??= kDefaultSpringForce; _direction = velocity < 0.0 ? AnimationDirection.reverse : AnimationDirection.forward; return _timeline.animateWith(force.release(progress, velocity)); } Future repeat({ double min: 0.0, double max: 1.0, Duration period }) { - if (period == null) - period = duration; + period ??= duration; return _timeline.animateWith(new _RepeatingSimulation(min, max, period)); } @@ -690,7 +692,7 @@ class Performance extends PerformanceView } } -/// An animation performance with an animated variable with a concrete type +/// An animation performance with an animated variable with a concrete type. class ValuePerformance extends Performance { ValuePerformance({ this.variable, Duration duration, double progress }) : super(duration: duration, progress: progress); @@ -707,7 +709,7 @@ class ValuePerformance extends Performance { class _RepeatingSimulation extends Simulation { _RepeatingSimulation(this.min, this.max, Duration period) - : _periodInSeconds = period.inMicroseconds.toDouble() / Duration.MICROSECONDS_PER_SECOND { + : _periodInSeconds = period.inMicroseconds / Duration.MICROSECONDS_PER_SECOND { assert(_periodInSeconds > 0.0); } diff --git a/packages/flutter/lib/src/animation/scroll_behavior.dart b/packages/flutter/lib/src/animation/scroll_behavior.dart index a10a259b7f1..815a17e2446 100644 --- a/packages/flutter/lib/src/animation/scroll_behavior.dart +++ b/packages/flutter/lib/src/animation/scroll_behavior.dart @@ -11,15 +11,18 @@ const double _kScrollDrag = 0.025; /// An interface for controlling the behavior of scrollable widgets. abstract class ScrollBehavior { - /// Called when a drag gesture ends. Returns a simulation that - /// propels the scrollOffset. + /// Returns a simulation that propels the scrollOffset. + /// + /// This function is called when a drag gesture ends. Simulation createFlingScrollSimulation(double position, double velocity) => null; - /// Called when a drag gesture ends and toSnapOffset is specified. /// Returns an animation that ends at the snap offset. + /// + /// This function is called when a drag gesture ends and toSnapOffset is specified. Simulation createSnapScrollSimulation(double startOffset, double endOffset, double startVelocity, double endVelocity) => null; - /// Return the scroll offset to use when the user attempts to scroll + + /// Returns the scroll offset to use when the user attempts to scroll /// from the given offset by the given delta. double applyCurve(double scrollOffset, double scrollDelta); @@ -27,7 +30,7 @@ abstract class ScrollBehavior { bool get isScrollable => true; } -/// A scroll behavior for a scrollable widget with linear extent +/// A scroll behavior for a scrollable widget with linear extent. abstract class ExtentScrollBehavior extends ScrollBehavior { ExtentScrollBehavior({ double contentExtent: 0.0, double containerExtent: 0.0 }) : _contentExtent = contentExtent, _containerExtent = containerExtent; @@ -40,10 +43,11 @@ abstract class ExtentScrollBehavior extends ScrollBehavior { double get containerExtent => _containerExtent; double _containerExtent; - /// Update either content or container extent (or both) + /// Updates either content or container extent (or both) /// - /// The scrollOffset parameter is the scroll offset of the widget before the - /// change in extent. Returns the new scroll offset of the widget after the + /// Returns the new scroll offset of the widget after the change in extent. + /// + /// The [scrollOffset] parameter is the scroll offset of the widget before the /// change in extent. double updateExtents({ double contentExtent, @@ -64,7 +68,7 @@ abstract class ExtentScrollBehavior extends ScrollBehavior { double get maxScrollOffset; } -/// A scroll behavior that prevents the user from exeeding scroll bounds. +/// A scroll behavior that prevents the user from exceeding scroll bounds. class BoundedBehavior extends ExtentScrollBehavior { BoundedBehavior({ double contentExtent: 0.0, double containerExtent: 0.0 }) : super(contentExtent: contentExtent, containerExtent: containerExtent); diff --git a/packages/flutter/lib/src/animation/simulation_stepper.dart b/packages/flutter/lib/src/animation/simulation_stepper.dart index 44d6a6acfd5..e0a2902286e 100644 --- a/packages/flutter/lib/src/animation/simulation_stepper.dart +++ b/packages/flutter/lib/src/animation/simulation_stepper.dart @@ -9,13 +9,13 @@ import 'animated_value.dart'; import 'curves.dart'; import 'ticker.dart'; -/// A simulation that varies from [begin] to [end] over [duration] using [curve] +/// A simulation that varies from [begin] to [end] over [duration] using [curve]. /// /// This class is an adaptor between the Simulation interface and the /// AnimatedValue interface. class _TweenSimulation extends Simulation { _TweenSimulation(double begin, double end, Duration duration, Curve curve) - : _durationInSeconds = duration.inMicroseconds.toDouble() / Duration.MICROSECONDS_PER_SECOND, + : _durationInSeconds = duration.inMicroseconds / Duration.MICROSECONDS_PER_SECOND, _tween = new AnimatedValue(begin, end: end, curve: curve) { assert(_durationInSeconds > 0.0); assert(begin != null); @@ -49,7 +49,7 @@ class SimulationStepper { Ticker _ticker; Simulation _simulation; - /// The current value of the timeline + /// The current value of the timeline. double get value => _value; double _value = 0.0; void set value(double newValue) { @@ -59,10 +59,10 @@ class SimulationStepper { _onTick(_value); } - /// Whether the timeline is currently animating + /// Whether the timeline is currently animating. bool get isAnimating => _ticker.isTicking; - /// Animate value of the timeline to the given target over the given duration + /// Animates value of the timeline to the given target over the given duration. /// /// Returns a future that resolves when the timeline stops animating, /// typically when the timeline arives at the target value. @@ -72,13 +72,13 @@ class SimulationStepper { return _start(new _TweenSimulation(value, target, duration, curve)); } - /// Gives the given simulation control over the timeline + /// Gives the given simulation control over the timeline. Future animateWith(Simulation simulation) { stop(); return _start(simulation); } - /// Start ticking the given simulation once per frame + /// Starts ticking the given simulation once per frame. /// /// Returns a future that resolves when the simulation stops ticking. Future _start(Simulation simulation) { @@ -89,7 +89,7 @@ class SimulationStepper { return _ticker.start(); } - /// Stop animating the timeline + /// Stops animating the timeline. void stop() { _simulation = null; _ticker.stop(); diff --git a/packages/flutter/lib/src/animation/ticker.dart b/packages/flutter/lib/src/animation/ticker.dart index 8aad194a89c..745fb689549 100644 --- a/packages/flutter/lib/src/animation/ticker.dart +++ b/packages/flutter/lib/src/animation/ticker.dart @@ -8,7 +8,7 @@ import 'scheduler.dart'; typedef TickerCallback(Duration elapsed); -/// Calls its callback once per animation frame +/// Calls its callback once per animation frame. class Ticker { /// Constructs a ticker that will call onTick once per frame while running Ticker(TickerCallback onTick) : _onTick = onTick; @@ -19,7 +19,7 @@ class Ticker { int _animationId; Duration _startTime; - /// Start calling onTick once per animation frame + /// Starts calling onTick once per animation frame. /// /// The returned future resolves once the ticker stops ticking. Future start() { @@ -30,7 +30,7 @@ class Ticker { return _completer.future; } - /// Stop calling onTick + /// Stops calling onTick. /// /// Causes the future returned by [start] to resolve. void stop() { diff --git a/packages/flutter/lib/src/gestures/arena.dart b/packages/flutter/lib/src/gestures/arena.dart index df7b585734d..663ea51a2b0 100644 --- a/packages/flutter/lib/src/gestures/arena.dart +++ b/packages/flutter/lib/src/gestures/arena.dart @@ -23,7 +23,7 @@ abstract class GestureArenaMember { void rejectGesture(Object key); } -/// An interface to information to an arena +/// An interface to information to an arena. /// /// A given [GestureArenaMember] can have multiple entries in multiple arenas /// with different keys. @@ -80,7 +80,7 @@ class GestureArena { _tryToResolveArena(key, state); } - /// Force resolution on this arena, giving the win to the first member + /// Forces resolution on this arena, giving the win to the first member. void sweep(Object key) { _GestureArenaState state = _arenas[key]; if (state == null) @@ -100,7 +100,7 @@ class GestureArena { } } - /// Prevent the arena from being swept + /// Prevents the arena from being swept. void hold(Object key) { _GestureArenaState state = _arenas[key]; if (state == null) @@ -108,9 +108,10 @@ class GestureArena { state.isHeld = true; } - /// Release a hold, allowing the arena to be swept + /// Releases a hold, allowing the arena to be swept. + /// /// If a sweep was attempted on a held arena, the sweep will be done - /// on release + /// on release. void release(Object key) { _GestureArenaState state = _arenas[key]; if (state == null) diff --git a/packages/flutter/lib/src/gestures/lsq_solver.dart b/packages/flutter/lib/src/gestures/lsq_solver.dart index f60ec5d5f6d..25c8e9b3f5b 100644 --- a/packages/flutter/lib/src/gestures/lsq_solver.dart +++ b/packages/flutter/lib/src/gestures/lsq_solver.dart @@ -101,12 +101,12 @@ class LeastSquaresSolver { final List w; PolynomialFit solve(int degree) { - if (degree > x.length) // not enough data to fit a curve + if (degree > x.length) // Not enough data to fit a curve. return null; PolynomialFit result = new PolynomialFit(degree); - // Shorthands for the purpose of notation equivalence to original C++ code + // Shorthands for the purpose of notation equivalence to original C++ code. final int m = x.length; final int n = degree + 1; @@ -135,7 +135,7 @@ class LeastSquaresSolver { double norm = q.getRow(j).norm(); if (norm < 0.000001) { - // vectors are linearly dependent or zero so no solution + // Vectors are linearly dependent or zero so no solution. return null; } diff --git a/packages/flutter/lib/src/gestures/multitap.dart b/packages/flutter/lib/src/gestures/multitap.dart index 282ffbd63b0..dc5e94bbd78 100644 --- a/packages/flutter/lib/src/gestures/multitap.dart +++ b/packages/flutter/lib/src/gestures/multitap.dart @@ -91,7 +91,7 @@ class DoubleTapGestureRecognizer extends GestureRecognizer { final Map _trackers = new Map(); void addPointer(PointerEvent event) { - // Ignore out-of-bounds second taps + // Ignore out-of-bounds second taps. if (_firstTap != null && !_firstTap.isWithinTolerance(event, kDoubleTapSlop)) return; @@ -155,7 +155,7 @@ class DoubleTapGestureRecognizer extends GestureRecognizer { _stopDoubleTapTimer(); if (_firstTap != null) { // Note, order is important below in order for the resolve -> reject logic - // to work properly + // to work properly. _TapTracker tracker = _firstTap; _firstTap = null; _reject(tracker); diff --git a/packages/flutter/lib/src/gestures/pointer_router.dart b/packages/flutter/lib/src/gestures/pointer_router.dart index 23da474cf2b..6ef9f9e56b0 100644 --- a/packages/flutter/lib/src/gestures/pointer_router.dart +++ b/packages/flutter/lib/src/gestures/pointer_router.dart @@ -34,7 +34,7 @@ class PointerRouter { _routeMap.remove(pointer); } - /// Call the routes registed for this pointer event. + /// Calls the routes registed for this pointer event. /// /// Calls the routes in the order in which they were added to the route. void route(PointerEvent event) { diff --git a/packages/flutter/lib/src/gestures/recognizer.dart b/packages/flutter/lib/src/gestures/recognizer.dart index 28893fa414e..da9ac2f7c01 100644 --- a/packages/flutter/lib/src/gestures/recognizer.dart +++ b/packages/flutter/lib/src/gestures/recognizer.dart @@ -14,15 +14,17 @@ export 'pointer_router.dart' show PointerRouter; abstract class GestureRecognizer extends GestureArenaMember { - /// Call this with the pointerdown event of each pointer that should be - /// considered for this gesture. (It's the GestureRecognizer's responsibility - /// to then add itself to the global pointer router to receive subsequent - /// events for this pointer.) + /// Calls this with the pointerdown event of each pointer that should be + /// considered for this gesture. + /// + /// It's the GestureRecognizer's responsibility to then add itself to the + /// global pointer router to receive subsequent events for this pointer. void addPointer(PointerDownEvent event); - /// Release any resources used by the object. Called when the object is no - /// longer needed (e.g. a gesture recogniser is being unregistered from a - /// [GestureDetector]). + /// Releases any resources used by the object. + /// + /// This method is called when the object is no longer needed (e.g. a gesture + /// recogniser is being unregistered from a [GestureDetector]). void dispose() { } } @@ -123,7 +125,7 @@ abstract class PrimaryPointerGestureRecognizer extends OneSequenceGestureRecogni /// Override to provide behavior for the primary pointer when the gesture is still possible. void handlePrimaryPointer(PointerEvent event); - /// Override to be notified with [deadline] is exceeded. + /// Override to be notified when [deadline] is exceeded. /// /// You must override this function if you supply a [deadline]. void didExceedDeadline() { diff --git a/packages/flutter/lib/src/http/http.dart b/packages/flutter/lib/src/http/http.dart index dbf811a9b71..9696b91612b 100644 --- a/packages/flutter/lib/src/http/http.dart +++ b/packages/flutter/lib/src/http/http.dart @@ -2,9 +2,10 @@ // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. -/// A [Future]-based library for making HTTP requests. It's based on -/// Dart's `http` package, but we've removed the dependency on mirrors -/// and added a `mojo`-based HTTP client. +/// A [Future]-based library for making HTTP requests. +/// +/// Let library is based on Dart's `http` package, but we have removed the +/// dependency on mirrors and added a `mojo`-based HTTP client. library http; import 'dart:async'; diff --git a/packages/flutter/lib/src/http/mojo_client.dart b/packages/flutter/lib/src/http/mojo_client.dart index 77e7a4e6a46..14cea26a20f 100644 --- a/packages/flutter/lib/src/http/mojo_client.dart +++ b/packages/flutter/lib/src/http/mojo_client.dart @@ -16,7 +16,7 @@ import 'package:mojo/mojo/http_header.mojom.dart' as mojo; import 'response.dart'; -/// A `mojo`-based HTTP client +/// A `mojo`-based HTTP client. class MojoClient { Future head(url, {Map headers}) => diff --git a/packages/flutter/lib/src/painting/box_painter.dart b/packages/flutter/lib/src/painting/box_painter.dart index 40446b31e96..8faac876d89 100644 --- a/packages/flutter/lib/src/painting/box_painter.dart +++ b/packages/flutter/lib/src/painting/box_painter.dart @@ -13,20 +13,20 @@ import 'edge_dims.dart'; export 'edge_dims.dart' show EdgeDims; -/// A side of a border of a box +/// A side of a border of a box. class BorderSide { const BorderSide({ this.color: const Color(0xFF000000), this.width: 1.0 }); - /// The color of this side of the border + /// The color of this side of the border. final Color color; - /// The width of this side of the border + /// The width of this side of the border. final double width; - /// A black border side of zero width + /// A black border side of zero width. static const none = const BorderSide(width: 0.0); bool operator ==(dynamic other) { @@ -49,7 +49,7 @@ class BorderSide { String toString() => 'BorderSide($color, $width)'; } -/// A border of a box, comprised of four sides +/// A border of a box, comprised of four sides. class Border { const Border({ this.top: BorderSide.none, @@ -58,7 +58,7 @@ class Border { this.left: BorderSide.none }); - /// A uniform border with all sides the same color and width + /// A uniform border with all sides the same color and width. factory Border.all({ Color color: const Color(0xFF000000), double width: 1.0 @@ -67,19 +67,19 @@ class Border { return new Border(top: side, right: side, bottom: side, left: side); } - /// The top side of this border + /// The top side of this border. final BorderSide top; - /// The right side of this border + /// The right side of this border. final BorderSide right; - /// The bottom side of this border + /// The bottom side of this border. final BorderSide bottom; - /// The left side of this border + /// The left side of this border. final BorderSide left; - /// The widths of the sides of this border represented as an EdgeDims + /// The widths of the sides of this border represented as an EdgeDims. EdgeDims get dimensions { return new EdgeDims.TRBL(top.width, right.width, bottom.width, left.width); } @@ -108,7 +108,7 @@ class Border { String toString() => 'Border($top, $right, $bottom, $left)'; } -/// A shadow cast by a box +/// 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). @@ -121,21 +121,22 @@ class BoxShadow { this.spreadRadius: 0.0 }); - /// The color of the shadow + /// The color of the shadow. final Color color; - /// The displacement of the shadow from the box + /// The displacement of the shadow from the box. final Offset offset; - /// 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 spreadRadius; - // See SkBlurMask::ConvertRadiusToSigma() + // See SkBlurMask::ConvertRadiusToSigma(). + // https://github.com/google/skia/blob/bb5b77db51d2e149ee66db284903572a5aac09be/src/effects/SkBlurMask.cpp#L23 double get _blurSigma => blurRadius * 0.57735 + 0.5; - /// Returns a new box shadow with its offset, blurRadius, and spreadRadius scaled by the given factor + /// Returns a new box shadow with its offset, blurRadius, and spreadRadius scaled by the given factor. BoxShadow scale(double factor) { return new BoxShadow( color: color, @@ -145,7 +146,7 @@ class BoxShadow { ); } - /// Linearly interpolate between two box shadows + /// Linearly interpolate between two box shadows. /// /// If either box shadow is null, this function linearly interpolates from a /// a box shadow that matches the other box shadow in color but has a zero @@ -165,7 +166,7 @@ class BoxShadow { ); } - /// Linearly interpolate between two lists of box shadows + /// Linearly interpolate between two lists of box shadows. /// /// If the lists differ in length, excess items are lerped with null. static List lerpList(List a, List b, double t) { @@ -210,13 +211,13 @@ class BoxShadow { String toString() => 'BoxShadow($color, $offset, $blurRadius, $spreadRadius)'; } -/// A 2D gradient +/// A 2D gradient. abstract class Gradient { const Gradient(); ui.Shader createShader(); } -/// A 2D linear gradient +/// A 2D linear gradient. class LinearGradient extends Gradient { const LinearGradient({ this.begin, @@ -226,24 +227,24 @@ class LinearGradient extends Gradient { this.tileMode: ui.TileMode.clamp }); - /// The point at which stop 0.0 of the gradient is placed + /// The point at which stop 0.0 of the gradient is placed. final Point begin; - /// The point at which stop 1.0 of the gradient is placed + /// The point at which stop 1.0 of the gradient is placed. final Point end; - /// 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]. final List 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]. final List stops; - /// How this gradient should tile the plane + /// How this gradient should tile the plane. final ui.TileMode tileMode; ui.Shader createShader() { @@ -306,7 +307,7 @@ class LinearGradient extends Gradient { } } -/// A 2D radial gradient +/// A 2D radial gradient. class RadialGradient extends Gradient { const RadialGradient({ this.center, @@ -316,18 +317,18 @@ class RadialGradient extends Gradient { this.tileMode: ui.TileMode.clamp }); - /// The center of the gradient + /// The center of the gradient. final Point center; - /// The radius at which stop 1.0 is placed + /// The radius at which stop 1.0 is placed. final double radius; - /// 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]. final List 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. /// /// The rings are centered at [center] and have a radius equal to the value of /// the stop times [radius]. @@ -335,7 +336,7 @@ class RadialGradient extends Gradient { /// Note: This list must have the same length as [colors]. final List stops; - /// How this gradient should tile the plane + /// How this gradient should tile the plane. final ui.TileMode tileMode; ui.Shader createShader() { @@ -398,38 +399,38 @@ class RadialGradient extends Gradient { } } -/// How an image should be inscribed into a box +/// How an image should be inscribed into a box. enum ImageFit { - /// Fill the box by distorting the image's aspect ratio + /// Fill the box by distorting the image's aspect ratio. fill, - /// As large as possible while still containing the image entirely within the box + /// As large as possible while still containing the image entirely within the box. contain, - /// As small as possible while still covering the entire box + /// As small as possible while still covering the entire box. cover, /// Center the image within the box and discard any portions of the image that - /// lie outside the box + /// lie outside the box. none, /// Center the image within the box and, if necessary, scale the image down to - /// ensure that the image fits within the box + /// ensure that the image fits within the box. scaleDown } -/// How to paint any portions of a box not covered by an image +/// How to paint any portions of a box not covered by an image. enum ImageRepeat { - /// Repeat the image in both the x and y directions until the box is filled + /// Repeat the image in both the x and y directions until the box is filled. repeat, - /// Repeat the image in the x direction until the box is filled horizontally + /// Repeat the image in the x direction until the box is filled horizontally. repeatX, - /// Repeat the image in the y direction until the box is filled vertically + /// Repeat the image in the y direction until the box is filled vertically. repeatY, - /// Leave uncovered poritions of the box transparent + /// Leave uncovered poritions of the box transparent. noRepeat } @@ -462,7 +463,7 @@ Iterable _generateImageTileRects(Rect outputRect, Rect fundamentalRect, Im } } -/// Paint an image into the given rectangle in the canvas. +/// Paints an image into the given rectangle in the canvas. void paintImage({ Canvas canvas, Rect rect, @@ -639,7 +640,7 @@ class BackgroundImage { final List _listeners = []; - /// Call listener when the background images changes (e.g., arrives from the network). + /// Adds a listener for background-image changes (e.g., arrives from the network). void _addChangeListener(VoidCallback listener) { // We add the listener to the _imageResource first so that the first change // listener doesn't get callback synchronously if the image resource is @@ -649,7 +650,7 @@ class BackgroundImage { _listeners.add(listener); } - /// No longer call listener when the background image changes. + /// Removes the listener for background-image changes. void _removeChangeListener(VoidCallback listener) { _listeners.remove(listener); // We need to remove ourselves as listeners from the _imageResource so that @@ -710,7 +711,7 @@ enum BoxShape { circle } -/// An immutable description of how to paint a box +/// An immutable description of how to paint a box. class BoxDecoration extends Decoration { const BoxDecoration({ this.backgroundColor, // null = don't draw background color @@ -724,37 +725,37 @@ class BoxDecoration extends Decoration { bool debugAssertValid() { assert(shape != BoxShape.circle || - borderRadius == null); // can't have a border radius if you're a circle + borderRadius == null); // Can't have a border radius if you're a circle. return super.debugAssertValid(); } - /// The color to fill in the background of the box + /// The color to fill in the background of the box. /// /// The color is filled into the shape of the box (e.g., either a rectangle, /// potentially with a border radius, or a circle). final Color backgroundColor; - /// An image to paint above the background color + /// An image to paint above the background color. final BackgroundImage backgroundImage; - /// A border to draw above the background + /// A border to draw above the background. final Border border; - /// If non-null, the corners of this box are rounded by this radius + /// If non-null, the corners of this box are rounded by this radius. /// /// Applies only to boxes with rectangular shapes. final double borderRadius; - /// A list of shadows cast by this box behind the background + /// A list of shadows cast by this box behind the background. final List boxShadow; - /// A graident to use when filling the background + /// A gradient to use when filling the background. final Gradient gradient; - /// The shape to fill the background color into and to cast as a shadow + /// The shape to fill the background color into and to cast as a shadow. final BoxShape shape; - /// Returns a new box decoration that is scaled by the given factor + /// Returns a new box decoration that is scaled by the given factor. BoxDecoration scale(double factor) { // TODO(abarth): Scale ALL the things. return new BoxDecoration( @@ -888,7 +889,7 @@ class BoxDecoration extends Decoration { _BoxDecorationPainter createBoxPainter() => new _BoxDecorationPainter(this); } -/// An object that paints a [BoxDecoration] into a canvas +/// An object that paints a [BoxDecoration] into a canvas. class _BoxDecorationPainter extends BoxPainter { _BoxDecorationPainter(this._decoration) { assert(_decoration != null); diff --git a/packages/flutter/lib/src/painting/shadows.dart b/packages/flutter/lib/src/painting/shadows.dart index 28cc7be7acc..1a7d199e577 100644 --- a/packages/flutter/lib/src/painting/shadows.dart +++ b/packages/flutter/lib/src/painting/shadows.dart @@ -8,7 +8,7 @@ import 'dart:ui' as ui; class ShadowDrawLooperBuilder { ui.LayerDrawLooperBuilder _builder = new ui.LayerDrawLooperBuilder(); - /// Add a shadow with the given parameters + /// Adds a shadow with the given parameters. void addShadow(ui.Offset offset, ui.Color color, double blur) { _builder.addLayerOnTop( new ui.DrawLooperLayerInfo() diff --git a/packages/flutter/lib/src/painting/text_painter.dart b/packages/flutter/lib/src/painting/text_painter.dart index 7f50a578c54..599a05fb0c4 100644 --- a/packages/flutter/lib/src/painting/text_painter.dart +++ b/packages/flutter/lib/src/painting/text_painter.dart @@ -7,21 +7,21 @@ import 'dart:ui' as ui; import 'basic_types.dart'; import 'text_style.dart'; -/// An immutable span of text +/// An immutable span of text. abstract class TextSpan { - // This class must be immutable, because we won't notice when it changes + // This class must be immutable, because we won't notice when it changes. String toString([String prefix = '']); void build(ui.ParagraphBuilder builder); ui.ParagraphStyle get paragraphStyle => null; } -/// An immutable span of unstyled text +/// An immutable span of unstyled text. class PlainTextSpan extends TextSpan { PlainTextSpan(this.text) { assert(text != null); } - /// The text contained in the span + /// The text contained in the span. final String text; void build(ui.ParagraphBuilder builder) { @@ -40,17 +40,17 @@ class PlainTextSpan extends TextSpan { String toString([String prefix = '']) => '$prefix$runtimeType: "$text"'; } -/// An immutable text span that applies a style to a list of children +/// An immutable text span that applies a style to a list of children. class StyledTextSpan extends TextSpan { StyledTextSpan(this.style, this.children) { assert(style != null); assert(children != null); } - /// The style to apply to the children + /// The style to apply to the children. final TextStyle style; - /// The children to which the style is applied + /// The children to which the style is applied. final List children; void build(ui.ParagraphBuilder builder) { @@ -97,7 +97,7 @@ class StyledTextSpan extends TextSpan { } } -/// An object that paints a [TextSpan] into a canvas +/// An object that paints a [TextSpan] into a canvas. class TextPainter { TextPainter(TextSpan text) { this.text = text; @@ -107,7 +107,7 @@ class TextPainter { bool _needsLayout = true; TextSpan _text; - /// The (potentially styled) text to paint + /// The (potentially styled) text to paint. TextSpan get text => _text; void set text(TextSpan value) { if (_text == value) @@ -119,7 +119,7 @@ class TextPainter { _needsLayout = true; } - /// The minimum width at which to layout the text + /// The minimum width at which to layout the text. double get minWidth => _paragraph.minWidth; void set minWidth(value) { if (_paragraph.minWidth == value) @@ -128,7 +128,7 @@ class TextPainter { _needsLayout = true; } - /// The maximum width at which to layout the text + /// The maximum width at which to layout the text. double get maxWidth => _paragraph.maxWidth; void set maxWidth(value) { if (_paragraph.maxWidth == value) @@ -137,7 +137,7 @@ class TextPainter { _needsLayout = true; } - /// The minimum height at which to layout the text + /// The minimum height at which to layout the text. double get minHeight => _paragraph.minHeight; void set minHeight(value) { if (_paragraph.minHeight == value) @@ -146,7 +146,7 @@ class TextPainter { _needsLayout = true; } - /// The maximum height at which to layout the text + /// The maximum height at which to layout the text. double get maxHeight => _paragraph.maxHeight; void set maxHeight(value) { if (_paragraph.maxHeight == value) @@ -165,13 +165,13 @@ class TextPainter { return layoutValue.ceilToDouble(); } - /// The width at which decreasing the width of the text would prevent it from painting itself completely within its bounds + /// The width at which decreasing the width of the text would prevent it from painting itself completely within its bounds. double get minIntrinsicWidth { assert(!_needsLayout); return _applyFloatingPointHack(_paragraph.minIntrinsicWidth); } - /// The width at which increasing the width of the text no longer decreases the height + /// The width at which increasing the width of the text no longer decreases the height. double get maxIntrinsicWidth { assert(!_needsLayout); return _applyFloatingPointHack(_paragraph.maxIntrinsicWidth); @@ -192,7 +192,7 @@ class TextPainter { return new Size(width, height); } - /// The distance from the top of the text to the first baseline of the given type + /// Returns the distance from the top of the text to the first baseline of the given type. double computeDistanceToActualBaseline(TextBaseline baseline) { assert(!_needsLayout); switch (baseline) { @@ -203,7 +203,7 @@ class TextPainter { } } - /// Compute the visual position of the glyphs for painting the text + /// Computes the visual position of the glyphs for painting the text. void layout() { if (!_needsLayout) return; @@ -211,7 +211,7 @@ class TextPainter { _needsLayout = false; } - /// Paint the text onto the given canvas at the given offset + /// Paints the text onto the given canvas at the given offset. void paint(ui.Canvas canvas, ui.Offset offset) { assert(!_needsLayout && "Please call layout() before paint() to position the text before painting it." is String); _paragraph.paint(canvas, offset); diff --git a/packages/flutter/lib/src/painting/text_style.dart b/packages/flutter/lib/src/painting/text_style.dart index 512d9aa3ded..99c914b88dd 100644 --- a/packages/flutter/lib/src/painting/text_style.dart +++ b/packages/flutter/lib/src/painting/text_style.dart @@ -6,7 +6,7 @@ import 'dart:ui' as ui; import 'basic_types.dart'; -/// An immutable style in which paint text +/// An immutable style in which paint text. class TextStyle { const TextStyle({ this.inherit: true, diff --git a/packages/flutter/lib/src/painting/transforms.dart b/packages/flutter/lib/src/painting/transforms.dart index bc80bc204bb..0f0d462a305 100644 --- a/packages/flutter/lib/src/painting/transforms.dart +++ b/packages/flutter/lib/src/painting/transforms.dart @@ -11,13 +11,13 @@ import 'basic_types.dart'; class MatrixUtils { MatrixUtils._(); - /// If the given transform is nothing but a 2D translation, then returns that - /// translation as an Offset. + /// Returns the given [transform] matrix as Offset, if the matrix is nothing + /// but a 2D translation. /// - /// Otherwise, returns null. + /// Returns null, otherwise. static Offset getAsTranslation(Matrix4 transform) { Float64List values = transform.storage; - // values are stored in column-major order + // Values are stored in column-major order. if (values[0] == 1.0 && values[1] == 0.0 && values[2] == 0.0 && @@ -37,4 +37,4 @@ class MatrixUtils { return null; } -} \ No newline at end of file +} diff --git a/packages/flutter/lib/src/rendering/auto_layout.dart b/packages/flutter/lib/src/rendering/auto_layout.dart index 54f31ef9d05..8dd283fce01 100644 --- a/packages/flutter/lib/src/rendering/auto_layout.dart +++ b/packages/flutter/lib/src/rendering/auto_layout.dart @@ -10,10 +10,10 @@ import 'object.dart'; /// Hosts the edge parameters and vends useful methods to construct expressions /// for constraints. Also sets up and manages implicit constraints and edit /// variables. Used as a mixin by layout containers and parent data instances -/// of render boxes taking part in auto layout +/// of render boxes taking part in auto layout. abstract class _AutoLayoutParamMixin { // Ideally, the edges would all be final, but then they would have to be - // initialized before the constructor. Not sure how to do that using a Mixin + // initialized before the constructor. Not sure how to do that using a Mixin. al.Param _leftEdge; al.Param _rightEdge; al.Param _topEdge; @@ -55,9 +55,11 @@ abstract class _AutoLayoutParamMixin { solver.suggestValueForVariable(_rightEdge.variable, size.width); } - /// Called when the solver has updated at least one of the layout parameters - /// of this object. The object is now responsible for applying this update to - /// it other properties (if necessary) + /// Applies the parameter updates. + /// + /// This method is called when the solver has updated at least one of the + /// layout parameters of this object. The object is now responsible for + /// applying this update to its other properties (if necessary). void _applyAutolayoutParameterUpdates(); /// Returns the set of implicit constraints that need to be applied to all @@ -139,7 +141,7 @@ class RenderAutoLayout extends RenderBox List _explicitConstraints = new List(); /// Adds all the given constraints to the solver. Either all constraints are - /// added or none + /// added or none. al.Result addConstraints(List constraints) { al.Result result = _solver.addConstraints(constraints); if (result == al.Result.success) { @@ -149,7 +151,7 @@ class RenderAutoLayout extends RenderBox return result; } - /// Add the given constraint to the solver. + /// Adds the given constraint to the solver. al.Result addConstraint(al.Constraint constraint) { al.Result result = _solver.addConstraint(constraint); diff --git a/packages/flutter/lib/src/rendering/binding.dart b/packages/flutter/lib/src/rendering/binding.dart index 7698d0eea9b..88641fe50f8 100644 --- a/packages/flutter/lib/src/rendering/binding.dart +++ b/packages/flutter/lib/src/rendering/binding.dart @@ -22,7 +22,7 @@ typedef void MetricListener(Size size); class _PointerState { _PointerState(this.lastPosition); - int get pointer => _pointer; // the identifier used in PointerEvent objects + int get pointer => _pointer; // The identifier used in PointerEvent objects. int _pointer; static int _pointerCount = 0; void startNewPointer() { @@ -45,7 +45,7 @@ class _PointerState { } class _PointerEventConverter { - // map from platform pointer identifiers to PointerEvent pointer identifiers + // Map from platform pointer identifiers to PointerEvent pointer identifiers. static Map _pointers = {}; static Iterable expand(Iterable packet) sync* { @@ -201,7 +201,7 @@ class BindingObserver { void didChangeLocale(ui.Locale locale) { } } -/// The glue between the render tree and the Flutter engine +/// The glue between the render tree and the Flutter engine. class FlutterBinding extends HitTestTarget { FlutterBinding({ RenderBox root: null, RenderView renderViewOverride }) { @@ -227,11 +227,11 @@ class FlutterBinding extends HitTestTarget { assert(_instance == this); } - /// The singleton instance of the binding + /// The singleton instance of the binding. static FlutterBinding get instance => _instance; static FlutterBinding _instance; - /// The render tree that's attached to the output surface + /// The render tree that's attached to the output surface. RenderView get renderView => _renderView; RenderView _renderView; @@ -260,7 +260,7 @@ class FlutterBinding extends HitTestTarget { beginFrame(); } - /// Pump the rendering pipeline to generate a frame for the given time stamp + /// Pump the rendering pipeline to generate a frame for the given time stamp. void beginFrame() { RenderObject.flushLayout(); _renderView.updateCompositingBits(); @@ -287,12 +287,13 @@ class FlutterBinding extends HitTestTarget { _handlePointerEvent(event); } - /// A router that routes all pointer events received from the engine + /// A router that routes all pointer events received from the engine. final PointerRouter pointerRouter = new PointerRouter(); /// State for all pointers which are currently down. + /// /// The state of hovering pointers is not tracked because that would require - /// hit-testing on every fram.e + /// hit-testing on every frame. Map _hitTests = {}; void _handlePointerEvent(PointerEvent event) { @@ -312,7 +313,7 @@ class FlutterBinding extends HitTestTarget { } } - /// Determine which [HitTestTarget] objects are located at a given position + /// Determine which [HitTestTarget] objects are located at a given position. HitTestResult hitTest(Point position) { HitTestResult result = new HitTestResult(); _renderView.hitTest(result, position: position); @@ -337,12 +338,12 @@ class FlutterBinding extends HitTestTarget { } } -/// Prints a textual representation of the entire render tree +/// Prints a textual representation of the entire render tree. void debugDumpRenderTree() { debugPrint(FlutterBinding.instance.renderView.toStringDeep()); } -/// Prints a textual representation of the entire layer tree +/// Prints a textual representation of the entire layer tree. void debugDumpLayerTree() { debugPrint(FlutterBinding.instance.renderView.layer.toStringDeep()); } diff --git a/packages/flutter/lib/src/rendering/block.dart b/packages/flutter/lib/src/rendering/block.dart index d8975aa395d..a1c4e337722 100644 --- a/packages/flutter/lib/src/rendering/block.dart +++ b/packages/flutter/lib/src/rendering/block.dart @@ -9,21 +9,21 @@ import 'package:vector_math/vector_math_64.dart'; import 'box.dart'; import 'object.dart'; -/// Parent data for use with [RenderBlockBase] +/// Parent data for use with [RenderBlockBase]. class BlockParentData extends ContainerBoxParentDataMixin { } -/// The direction in which the block should lay out +/// The direction in which the block should lay out. enum BlockDirection { - /// Children are arranged horizontally, from left to right + /// Children are arranged horizontally, from left to right. horizontal, - /// Children are arranged vertically, from top to bottom + /// Children are arranged vertically, from top to bottom. vertical } typedef double _ChildSizingFunction(RenderBox child, BoxConstraints constraints); typedef double _Constrainer(double value); -/// Implements the block layout algorithm +/// Implements the block layout algorithm. /// /// In block layout, children are arranged linearly along the main axis (either /// horizontally or vertically). In the cross axis, children are stretched to @@ -49,7 +49,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin child.parentData = new BlockParentData(); } - /// The direction to use as the main axis + /// The direction to use as the main axis. BlockDirection get direction => _direction; BlockDirection _direction; void set direction (BlockDirection value) { @@ -59,7 +59,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin } } - /// If non-null, forces children to be exactly this large in the main axis + /// If non-null, forces children to be exactly this large in the main axis. double get itemExtent => _itemExtent; double _itemExtent; void set itemExtent(double value) { @@ -69,7 +69,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin } } - /// Forces the block to be at least this large in the main-axis + /// Forces the block to be at least this large in the main-axis. double get minExtent => _minExtent; double _minExtent; void set minExtent(double value) { @@ -79,7 +79,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin } } - /// Whether the main axis is vertical + /// Whether the main axis is vertical. bool get isVertical => _direction == BlockDirection.vertical; BoxConstraints _getInnerConstraints(BoxConstraints constraints) { @@ -124,7 +124,7 @@ abstract class RenderBlockBase extends RenderBox with ContainerRenderObjectMixin } } -/// A block layout with a concrete set of children +/// A block layout with a concrete set of children. class RenderBlock extends RenderBlockBase { RenderBlock({ @@ -214,7 +214,7 @@ class RenderBlock extends RenderBlockBase { void performLayout() { assert((isVertical ? constraints.maxHeight >= double.INFINITY : constraints.maxWidth >= double.INFINITY) && - 'RenderBlock does not clip or resize its children, so it must be placed in a parent that does not constrain ' + + 'RenderBlock does not clip or resize its children, so it must be placed in a parent that does not constrain ' 'the block\'s main direction. You probably want to put the RenderBlock inside a RenderViewport.' is String); super.performLayout(); } @@ -229,7 +229,7 @@ class RenderBlock extends RenderBlockBase { } -/// A block layout whose children depend on its layout +/// A block layout whose children depend on its layout. /// /// This class invokes a callbacks for layout and intrinsic dimensions. The main /// [callback] (constructor argument and property) is expected to modify the @@ -261,7 +261,7 @@ class RenderBlockViewport extends RenderBlockBase { bool _inCallback = false; bool get hasLayer => true; - /// Called during [layout] to determine the blocks children + /// Called during [layout] to determine the blocks children. /// /// Typically the callback will mutate the child list appropriately, for /// example so the child list contains only visible children. @@ -275,7 +275,7 @@ class RenderBlockViewport extends RenderBlockBase { markNeedsLayout(); } - /// Returns the total main-axis extent of all the children that could be included by [callback] in one go + /// Returns the total main-axis extent of all the children that could be included by [callback] in one go. ExtentCallback get totalExtentCallback => _totalExtentCallback; ExtentCallback _totalExtentCallback; void set totalExtentCallback(ExtentCallback value) { @@ -286,7 +286,7 @@ class RenderBlockViewport extends RenderBlockBase { markNeedsLayout(); } - /// Returns the minimum cross-axis extent across all the children that could be included by [callback] in one go + /// Returns the minimum cross-axis extent across all the children that could be included by [callback] in one go. ExtentCallback get minCrossAxisExtentCallback => _minCrossAxisExtentCallback; ExtentCallback _minCrossAxisExtentCallback; void set minCrossAxisExtentCallback(ExtentCallback value) { @@ -297,7 +297,7 @@ class RenderBlockViewport extends RenderBlockBase { markNeedsLayout(); } - /// Returns the maximum cross-axis extent across all the children that could be included by [callback] in one go + /// Returns the maximum cross-axis extent across all the children that could be included by [callback] in one go. ExtentCallback get maxCrossAxisExtentCallback => _maxCrossAxisExtentCallback; ExtentCallback _maxCrossAxisExtentCallback; void set maxCrossAxisExtentCallback(ExtentCallback value) { @@ -329,7 +329,7 @@ class RenderBlockViewport extends RenderBlockBase { _overlayPainter?.detach(); } - /// The offset at which to paint the first child + /// The offset at which to paint the first child. /// /// Note: you can modify this property from within [callback], if necessary. double get startOffset => _startOffset; @@ -354,10 +354,7 @@ class RenderBlockViewport extends RenderBlockBase { try { _inCallback = true; result = intrinsicCallback(constraints); - if (result == null) - result = constrainer(0.0); - else - result = constrainer(result); + result = constrainer(result ?? 0.0); } finally { _inCallback = false; }