development/flutter
development/flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter synced 2024-10-16 05:02:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1644 from abarth/doc_widget2

Browse source 
Add more dartdoc to widgets.dart
This commit is contained in:
Adam Barth 2016-02-05 20:28:25 -08:00
parent d38b9a02bb 9251504a57
commit bc3202ff35
14 changed files with 210 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
examples/rendering/lib/sector_layout.dart
View file

@ -91,7 +91,7 @@ abstract class RenderSector extends RenderObject {
assert(deltaTheta <= math.max(constraints.minDeltaTheta, constraints.maxDeltaTheta));
}
void performResize() {
// default behaviour for subclasses that have sizedByParent = true
// default behavior for subclasses that have sizedByParent = true
deltaRadius = constraints.constrainDeltaRadius(0.0);
deltaTheta = constraints.constrainDeltaTheta(0.0);
}

2
packages/flutter/lib/src/rendering/block.dart
View file

@ -395,7 +395,7 @@ class RenderBlockViewport extends RenderBlockBase {
}
// We don't override computeDistanceToActualBaseline(), because we
// want the default behaviour (returning null). Otherwise, as you
// want the default behavior (returning null). Otherwise, as you
// scroll the RenderBlockViewport, it would shift in its parent if
// the parent was baseline-aligned, which makes no sense.

2
packages/flutter/lib/src/rendering/box.dart
View file

@ -670,7 +670,7 @@ abstract class RenderBox extends RenderObject {
super.markNeedsLayout();
}
void performResize() {
// default behaviour for subclasses that have sizedByParent = true
// default behavior for subclasses that have sizedByParent = true
size = constraints.constrain(Size.zero);
assert(!size.isInfinite);
}

2
packages/flutter/lib/src/rendering/object.dart
View file

@ -810,7 +810,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
void debugAssertDoesMeetConstraints();
/// When true, debugAssertDoesMeetConstraints() is currently
/// executing asserts for verifying the consistent behaviour of
/// executing asserts for verifying the consistent behavior of
/// intrinsic dimensions methods.
///
/// This should only be set by debugAssertDoesMeetConstraints()

2
packages/flutter/lib/src/rendering/semantics.dart
View file

@ -158,7 +158,7 @@ class SemanticsNode extends AbstractNode {
_newChildren ??= <SemanticsNode>[];
_newChildren.addAll(children);
// we do the asserts afterwards because children is an Iterable
// and doing the asserts before would mean the behaviour is
// and doing the asserts before would mean the behavior is
// different in checked mode vs release mode (if you walk an
// iterator after having reached the end, it'll just start over;
// the values are not cached).

4
packages/flutter/lib/src/rendering/shifted_box.dart
View file

@ -216,7 +216,7 @@ class RenderPadding extends RenderShiftedBox {
/// By default, sizes to be as big as possible in both axes. If either axis is
/// unconstrained, then in that direction it will be sized to fit the child's
/// dimensions. Using widthFactor and heightFactor you can force this latter
/// behaviour in all cases.
/// behavior in all cases.
class RenderPositionedBox extends RenderShiftedBox {
RenderPositionedBox({
RenderBox child,
@ -371,7 +371,7 @@ class RenderPositionedBox extends RenderShiftedBox {
/// For example, if you wanted a box to always render 50 pixels high, regardless
/// of where it was rendered, you would wrap it in a RenderOverflow with
/// minHeight and maxHeight set to 50.0. Generally speaking, to avoid confusing
/// behaviour around hit testing, a RenderOverflowBox should usually be wrapped
/// behavior around hit testing, a RenderOverflowBox should usually be wrapped
/// in a RenderClipRect.
///
/// The child is positioned at the top left of the box. To position a smaller

2
packages/flutter/lib/src/rendering/viewport.dart
View file

@ -115,7 +115,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox
}
// We don't override computeDistanceToActualBaseline(), because we
// want the default behaviour (returning null). Otherwise, as you
// want the default behavior (returning null). Otherwise, as you
// scroll the RenderViewport, it would shift in its parent if the
// parent was baseline-aligned, which makes no sense.

2
packages/flutter/lib/src/widgets/basic.dart
View file

@ -364,7 +364,7 @@ class Padding extends OneChildRenderObjectWidget {
/// By default, sizes to be as big as possible in both axes. If either axis is
/// unconstrained, then in that direction it will be sized to fit the child's
/// dimensions. Using widthFactor and heightFactor you can force this latter
/// behaviour in all cases.
/// behavior in all cases.
class Align extends OneChildRenderObjectWidget {
Align({
Key key,

2
packages/flutter/lib/src/widgets/framework.dart
View file

@ -1834,7 +1834,7 @@ typedef void WidgetsExceptionHandler(String context, dynamic exception, StackTra
/// the exception occurred, and may include additional details such as
/// descriptions of the objects involved. The 'exception' argument contains the
/// object that was thrown, and the 'stack' argument contains the stack trace.
/// If no callback is set, then a default behaviour consisting of dumping the
/// If no callback is set, then a default behavior consisting of dumping the
/// context, exception, and stack trace to the console is used instead.
WidgetsExceptionHandler debugWidgetsExceptionHandler;
void _debugReportException(String context, dynamic exception, StackTrace stack) {

108
packages/flutter/lib/src/widgets/scrollable.dart
View file

@ -25,6 +25,7 @@ const double _kMillisecondsPerSecond = 1000.0;
const double _kMinFlingVelocity = -kMaxFlingVelocity * _kMillisecondsPerSecond;
const double _kMaxFlingVelocity = kMaxFlingVelocity * _kMillisecondsPerSecond;
/// The accuracy to which scrolling is computed.
final Tolerance kPixelScrollTolerance = new Tolerance(
velocity: 1.0 / (0.050 * ui.window.devicePixelRatio), // logical pixels per second
distance: 1.0 / ui.window.devicePixelRatio // logical pixels
@ -33,8 +34,13 @@ final Tolerance kPixelScrollTolerance = new Tolerance(
typedef void ScrollListener(double scrollOffset);
typedef double SnapOffsetCallback(double scrollOffset);
/// A base class for scrollable widgets that reacts to user input and generates
/// a scrollOffset.
/// A base class for scrollable widgets.
///
/// Commonly used subclasses include [ScrollableList], [ScrollableGrid], and
/// [ScrollableViewport].
///
/// Widgets that subclass [Scrollable] typically use state objects that subclass
/// [ScrollableState].
abstract class Scrollable extends StatefulComponent {
Scrollable({
Key key,
@ -50,13 +56,25 @@ abstract class Scrollable extends StatefulComponent {
scrollDirection == Axis.horizontal);
}
/// The scroll offset this widget should use when first created.
final double initialScrollOffset;
/// The axis along which this widget should scroll.
final Axis scrollDirection;
/// Called whenever this widget starts to scroll.
final ScrollListener onScrollStart;
/// Called whenever this widget's scroll offset changes.
final ScrollListener onScroll;
/// Called whenever this widget stops scrolling.
final ScrollListener onScrollEnd;
/// Called to determine the offset to which scrolling should snap.
final SnapOffsetCallback snapOffsetCallback;
final double snapAlignmentOffset;
final double snapAlignmentOffset; // What does this do?
/// The state from the closest instance of this class that encloses the given context.
static ScrollableState of(BuildContext context) {
@ -130,6 +148,10 @@ abstract class Scrollable extends StatefulComponent {
ScrollableState createState();
}
/// Contains the state for common scrolling behaviors.
///
/// Widgets that subclass [Scrollable] typically use state objects that subclass
/// [ScrollableState].
abstract class ScrollableState<T extends Scrollable> extends State<T> {
void initState() {
super.initState();
@ -139,21 +161,21 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
AnimationController _controller;
/// The current scroll offset.
///
/// The scroll offset is applied to the child widget along the scroll
/// direction before painting. A positive scroll offset indicates that
/// more content in the preferred reading direction is visible.
double get scrollOffset => _scrollOffset;
double _scrollOffset;
Offset get scrollOffsetVector {
if (config.scrollDirection == Axis.horizontal)
return new Offset(scrollOffset, 0.0);
return new Offset(0.0, scrollOffset);
}
/// Convert a position or velocity measured in terms of pixels to a scrollOffset.
/// Scrollable gesture handlers convert their incoming values with this method.
/// Subclasses that define scrollOffset in units other than pixels must
/// override this method.
double pixelToScrollOffset(double pixelValue) => pixelValue;
/// Returns the component of the given velocity in the scroll direction.
double scrollDirectionVelocity(Offset scrollVelocity) {
return config.scrollDirection == Axis.horizontal
? -scrollVelocity.dx
@ -161,7 +183,16 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
}
ScrollBehavior _scrollBehavior;
/// Subclasses should override this function to create the [ScrollBehavior]
/// they desire.
ScrollBehavior createScrollBehavior();
/// The current scroll behavior of this widget.
///
/// Scroll behaviors control where the boundaries of the scrollable are placed
/// and how the scrolling physics should behave near those boundaries and
/// after the user stops directly manipulating the scrollable.
ScrollBehavior get scrollBehavior {
if (_scrollBehavior == null)
_scrollBehavior = createScrollBehavior();
@ -202,6 +233,10 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
);
}
/// Subclasses should override this function to build the interior of their
/// scrollable widget. Scrollable wraps the returned widget in a
/// [GestureDetector] to observe the user's interaction with this widget and
/// to adjust the scroll offset accordingly.
Widget buildContent(BuildContext context);
Future _animateTo(double newScrollOffset, Duration duration, Curve curve) {
@ -227,10 +262,12 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
return simulation;
}
double snapScrollOffset(double value) {
return config.snapOffsetCallback == null ? value : config.snapOffsetCallback(value);
/// Returns the snapped offset closest to the given scroll offset.
double snapScrollOffset(double scrollOffset) {
return config.snapOffsetCallback == null ? scrollOffset : config.snapOffsetCallback(scrollOffset);
}
/// Whether this scrollable should attempt to snap scroll offsets.
bool get snapScrollOffsetChanges => config.snapOffsetCallback != null;
Simulation _createSnapSimulation(double velocity) {
@ -291,6 +328,10 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
dispatchOnScroll();
}
/// Scroll this widget to the given scroll offset.
///
/// If a non-null [duration] is provided, the widget will animate to the new
/// scroll offset over the given duration with the given curve.
Future scrollTo(double newScrollOffset, { Duration duration, Curve curve: Curves.ease }) {
if (newScrollOffset == _scrollOffset)
return new Future.value();
@ -304,11 +345,20 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
return _animateTo(newScrollOffset, duration, curve);
}
/// Scroll this widget by the given scroll delta.
///
/// If a non-null [duration] is provided, the widget will animate to the new
/// scroll offset over the given duration with the given curve.
Future scrollBy(double scrollDelta, { Duration duration, Curve curve: Curves.ease }) {
double newScrollOffset = scrollBehavior.applyCurve(_scrollOffset, scrollDelta);
return scrollTo(newScrollOffset, duration: duration, curve: curve);
}
/// Fling the scroll offset with the given velocity.
///
/// Calling this function starts a physics-based animation of the scroll
/// offset with the given value as the initial velocity. The physics
/// simulation used is determined by the scroll behavior.
Future fling(Offset scrollVelocity) {
if (scrollVelocity != Offset.zero)
return _startToEndAnimation(scrollVelocity);
@ -317,21 +367,34 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
return new Future.value();
}
/// Animate the scroll offset to a value with a local minima of energy.
///
/// Calling this function starts a physics-based animation of the scroll
/// offset either to a snap point or to within the scrolling bounds. The
/// physics simulation used is determined by the scroll behavior.
Future settleScrollOffset() {
return _startToEndAnimation(Offset.zero);
}
/// Calls the onScrollStart callback.
///
/// Subclasses can override this function to hook the scroll start callback.
void dispatchOnScrollStart() {
if (config.onScrollStart != null)
config.onScrollStart(_scrollOffset);
}
// Derived classes can override this method and call super.dispatchOnScroll()
/// Calls the onScroll callback.
///
/// Subclasses can override this function to hook the scroll callback.
void dispatchOnScroll() {
if (config.onScroll != null)
config.onScroll(_scrollOffset);
}
/// Calls the dispatchOnScrollEnd callback.
///
/// Subclasses can override this function to hook the scroll end callback.
void dispatchOnScrollEnd() {
if (config.onScrollEnd != null)
config.onScrollEnd(_scrollOffset);
@ -363,10 +426,15 @@ abstract class ScrollableState<T extends Scrollable> extends State<T> {
}
}
/// Indicates that a descendant scrollable has scrolled.
class ScrollNotification extends Notification {
ScrollNotification(this.scrollable, this.position);
ScrollNotification(this.scrollable, this.scrollOffset);
/// The scrollable that scrolled.
final ScrollableState scrollable;
final double position;
/// The new scroll offset that the scrollable obtained.
final double scrollOffset;
}
/// A simple scrollable widget that has a single child. Use this component if
@ -391,10 +459,10 @@ class ScrollableViewport extends Scrollable {
final Widget child;
ScrollableViewportState createState() => new ScrollableViewportState();
ScrollableState createState() => new _ScrollableViewportState();
}
class ScrollableViewportState extends ScrollableState<ScrollableViewport> {
class _ScrollableViewportState extends ScrollableState<ScrollableViewport> {
ScrollBehavior createScrollBehavior() => new OverscrollWhenScrollableBehavior();
OverscrollWhenScrollableBehavior get scrollBehavior => super.scrollBehavior;
@ -421,11 +489,17 @@ class ScrollableViewportState extends ScrollableState<ScrollableViewport> {
));
}
Offset get _scrollOffsetVector {
if (config.scrollDirection == Axis.horizontal)
return new Offset(scrollOffset, 0.0);
return new Offset(0.0, scrollOffset);
}
Widget buildContent(BuildContext context) {
return new SizeObserver(
onSizeChanged: _handleViewportSizeChanged,
child: new Viewport(
scrollOffset: scrollOffsetVector,
scrollOffset: _scrollOffsetVector,
scrollDirection: config.scrollDirection,
child: new SizeObserver(
onSizeChanged: _handleChildSizeChanged,

6
packages/flutter/lib/src/widgets/semantics_debugger.dart
View file

@ -13,9 +13,15 @@ import 'basic.dart';
import 'framework.dart';
import 'gesture_detector.dart';
/// Visualizes the semantics for the child.
///
/// This widget is useful for understand how an app presents itself to
/// accessibility technology.
class SemanticsDebugger extends StatefulComponent {
const SemanticsDebugger({ Key key, this.child }) : super(key: key);
final Widget child;
_SemanticsDebuggerState createState() => new _SemanticsDebuggerState();
}

2
packages/flutter/lib/src/widgets/status_transitions.dart
View file

@ -6,6 +6,7 @@ import 'package:flutter/animation.dart';
import 'framework.dart';
/// A component that rebuilds when the given animation changes status.
abstract class StatusTransitionComponent extends StatefulComponent {
StatusTransitionComponent({
Key key,
@ -14,6 +15,7 @@ abstract class StatusTransitionComponent extends StatefulComponent {
assert(animation != null);
}
/// The animation to which this component is listening.
final Animation<double> animation;
Widget build(BuildContext context);

11
packages/flutter/lib/src/widgets/title.dart
View file

@ -7,18 +7,23 @@ import 'package:flutter/widgets.dart';
/// Controls the description of this app in the operating system.
class Title extends StatelessComponent {
Title({ this.title, this.child, this.color }) {
Title({
Key key,
this.title,
this.child,
this.color
}) : super(key: key) {
assert(color == null || color.alpha == 0xFF);
}
final Widget child;
/// A one-line description of this app for use in the window manager.
final String title;
/// A color that the window manager should use to identify this app.
final Color color;
final Widget child;
Widget build(BuildContext context) {
updateTaskDescription(label: title, color: color);
return child;

96
packages/flutter/lib/src/widgets/transitions.dart
View file

@ -14,6 +14,13 @@ import 'framework.dart';
export 'package:flutter/animation.dart' show AnimationDirection;
export 'package:flutter/rendering.dart' show RelativeRect;
/// A component that rebuilds when the given animation changes value.
///
/// AnimatedComponent is most useful for stateless animated widgets. To use
/// AnimatedComponent, simply subclass it and implement the build function.
///
/// For more complex case involving additional state, consider using
/// [AnimatedBuilder].
abstract class AnimatedComponent extends StatefulComponent {
AnimatedComponent({
Key key,
@ -22,8 +29,11 @@ abstract class AnimatedComponent extends StatefulComponent {
assert(animation != null);
}
/// The animation to which this component is listening.
final Animation<Object> animation;
/// Override this function to build widgets that depend on the current value
/// of the animation.
Widget build(BuildContext context);
/// Subclasses typically do not override this method.
@ -64,6 +74,7 @@ class _AnimatedComponentState extends State<AnimatedComponent> {
}
}
/// Animates the position of a widget relative to its normal position.
class SlideTransition extends AnimatedComponent {
SlideTransition({
Key key,
@ -72,8 +83,21 @@ class SlideTransition extends AnimatedComponent {
this.child
}) : position = position, super(key: key, animation: position);
/// The animation that controls the position of the child.
///
/// If the current value of the position animation is (dx, dy), the child will
/// be translated horizontally by width * dx and vertically by height * dy.
final Animation<FractionalOffset> position;
/// Whether hit testing should be affected by the slide animation.
///
/// If false, hit testing will proceed as if the child was not translated at
/// all. Setting this value to false is useful for fast animations where you
/// expect the user to commonly interact with the child widget in its final
/// location and you want the user to benefit from "muscle memory".
final bool transformHitTests;
final Widget child;
Widget build(BuildContext context) {
@ -85,6 +109,7 @@ class SlideTransition extends AnimatedComponent {
}
}
/// Animates the size of a widget.
class ScaleTransition extends AnimatedComponent {
ScaleTransition({
Key key,
@ -93,8 +118,19 @@ class ScaleTransition extends AnimatedComponent {
this.child
}) : scale = scale, super(key: key, animation: scale);
/// The animation that controls the scale of the child.
///
/// If the current value of the scale animation is v, the child will be
/// painted v times its normal size.
final Animation<double> scale;
/// The alignment of the origin of the coordainte system in which the scale
/// takes place, relative to the size of the box.
///
/// For example, to set the origin of the scale to bottom middle, you can use
/// an alignment of (0.5, 1.0).
final FractionalOffset alignment;
final Widget child;
Widget build(BuildContext context) {
@ -109,6 +145,7 @@ class ScaleTransition extends AnimatedComponent {
}
}
/// Animates the rotation of a widget.
class RotationTransition extends AnimatedComponent {
RotationTransition({
Key key,
@ -116,7 +153,12 @@ class RotationTransition extends AnimatedComponent {
this.child
}) : turns = turns, super(key: key, animation: turns);
/// The animation that controls the rotation of the child.
///
/// If the current value of the turns animation is v, the child will be
/// rotated v * 2 * pi radians before being painted.
final Animation<double> turns;
final Widget child;
Widget build(BuildContext context) {
@ -130,6 +172,7 @@ class RotationTransition extends AnimatedComponent {
}
}
/// Animates the opacity of a widget.
class FadeTransition extends AnimatedComponent {
FadeTransition({
Key key,
@ -137,7 +180,14 @@ class FadeTransition extends AnimatedComponent {
this.child
}) : opacity = opacity, super(key: key, animation: opacity);
/// The animation that controls the opacity of the child.
///
/// If the current value of the opacity animation is v, the child will be
/// painted with an opacity of v. For example, if v is 0.5, the child will be
/// blended 50% with its background. Similarly, if v is 0.0, the child will be
/// completely transparent.
final Animation<double> opacity;
final Widget child;
Widget build(BuildContext context) {
@ -145,6 +195,7 @@ class FadeTransition extends AnimatedComponent {
}
}
/// Animates the background color of a widget.
class ColorTransition extends AnimatedComponent {
ColorTransition({
Key key,
@ -152,7 +203,12 @@ class ColorTransition extends AnimatedComponent {
this.child
}) : color = color, super(key: key, animation: color);
/// The animation that controls the color of the background.
///
/// If the current value of the color animation is c, this widget will paint
/// a rectangular background behind the child widget of color c.
final Animation<Color> color;
final Widget child;
Widget build(BuildContext context) {
@ -163,10 +219,10 @@ class ColorTransition extends AnimatedComponent {
}
}
/// An animated variable containing a RelativeRectangle
/// An interpolation between two relative rects.
///
/// This class specializes the interpolation of AnimatedValue<RelativeRect> to
/// be appropriate for rectangles that are described in terms of offsets from
/// This class specializes the interpolation of Tween<RelativeRect> to be
/// appropriate for rectangles that are described in terms of offsets from
/// other rectangles.
class RelativeRectTween extends Tween<RelativeRect> {
RelativeRectTween({ RelativeRect begin, RelativeRect end })
@ -189,7 +245,9 @@ class PositionedTransition extends AnimatedComponent {
assert(rect != null);
}
/// The animation that controls the child's size and position.
final Animation<RelativeRect> rect;
final Widget child;
Widget build(BuildContext context) {
@ -203,8 +261,28 @@ class PositionedTransition extends AnimatedComponent {
}
}
/// A builder that builds a widget given a child.
typedef Widget TransitionBuilder(BuildContext context, Widget child);
/// A general-purpose widget for building animations.
///
/// AnimatedBuilder is useful for more complex components that wish to include
/// an animation as part of a larger build function. To use AnimatedBuilder,
/// simply construct the widget and pass it a builder function.
///
/// If your [builder] function contains a subtree that does not depend on the
/// animation, it's more efficient to build that subtree once instead of
/// rebuilding it on every animation tick.
///
/// If you pass the pre-built subtree as the [child] parameter, the
/// AnimatedBuilder will pass it back to your builder function so that you
/// can incorporate it into your build.
///
/// Using this pre-built child is entirely optional, but can improve
/// performance significantly in some cases and is therefore a good practice.
///
/// For simple cases without additional state, consider using
/// [AnimatedComponent].
class AnimatedBuilder extends AnimatedComponent {
AnimatedBuilder({
Key key,
@ -213,7 +291,19 @@ class AnimatedBuilder extends AnimatedComponent {
this.child
}) : super(key: key, animation: animation);
/// Called every time the animation changes value.
final TransitionBuilder builder;
/// If your builder function contains a subtree that does not depend on the
/// animation, it's more efficient to build that subtree once instead of
/// rebuilding it on every animation tick.
///
/// If you pass the pre-built subtree as the [child] parameter, the
/// AnimatedBuilder will pass it back to your builder function so that you
/// can incorporate it into your build.
///
/// Using this pre-built child is entirely optional, but can improve
/// performance significantly in some cases and is therefore a good practice.
final Widget child;
Widget build(BuildContext context) {