firka/flutter
firka/flutter
4
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #962 from Hixie/object-docs

Browse Source 
Close some sentences. (rendering dartdocs)
This commit is contained in:
Ian Hickson 2015-12-16 14:52:37 -08:00
commit ef57c4ee4d
3 changed files with 107 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
packages/flutter/lib/src/rendering/box.dart
View File

@ -23,7 +23,7 @@ class _DebugSize extends Size {
final bool _canBeUsedByParent; final bool _canBeUsedByParent;
} }
/// Immutable layout constraints for box layout /// Immutable layout constraints for box layout.
/// ///
/// A size respects a BoxConstraints if, and only if, all of the following /// A size respects a BoxConstraints if, and only if, all of the following
/// relations hold: /// relations hold:
@ -51,14 +51,14 @@ class BoxConstraints extends Constraints {
final double minHeight; final double minHeight;
final double maxHeight; final double maxHeight;
/// Constructs box constraints that is respected only by the given size /// Constructs box constraints that is respected only by the given size.
BoxConstraints.tight(Size size) BoxConstraints.tight(Size size)
: minWidth = size.width, : minWidth = size.width,
maxWidth = size.width, maxWidth = size.width,
minHeight = size.height, minHeight = size.height,
maxHeight = size.height; maxHeight = size.height;
/// Constructs box constraints that require the given width or height /// Constructs box constraints that require the given width or height.
const BoxConstraints.tightFor({ const BoxConstraints.tightFor({
double width, double width,
double height double height
@ -67,14 +67,14 @@ class BoxConstraints extends Constraints {
minHeight = height != null ? height : 0.0, minHeight = height != null ? height : 0.0,
maxHeight = height != null ? height : double.INFINITY; maxHeight = height != null ? height : double.INFINITY;
/// Constructs box constraints that forbid sizes larger than the given size /// Constructs box constraints that forbid sizes larger than the given size.
BoxConstraints.loose(Size size) BoxConstraints.loose(Size size)
: minWidth = 0.0, : minWidth = 0.0,
maxWidth = size.width, maxWidth = size.width,
minHeight = 0.0, minHeight = 0.0,
maxHeight = size.height; maxHeight = size.height;
/// Constructs box constraints that expand to fill another box contraints /// Constructs box constraints that expand to fill another box contraints.
/// ///
/// If width or height is given, the constraints will require exactly the /// If width or height is given, the constraints will require exactly the
/// given value in the given dimension. /// given value in the given dimension.
@ -86,7 +86,7 @@ class BoxConstraints extends Constraints {
minHeight = height != null ? height : double.INFINITY, minHeight = height != null ? height : double.INFINITY,
maxHeight = height != null ? height : double.INFINITY; maxHeight = height != null ? height : double.INFINITY;
/// Returns new box constraints that are smaller by the given edge dimensions /// Returns new box constraints that are smaller by the given edge dimensions.
BoxConstraints deflate(EdgeDims edges) { BoxConstraints deflate(EdgeDims edges) {
assert(edges != null); assert(edges != null);
assert(isNormalized); assert(isNormalized);
@ -102,7 +102,7 @@ class BoxConstraints extends Constraints {
); );
} }
/// Returns new box constraints that remove the minimum width and height requirements /// Returns new box constraints that remove the minimum width and height requirements.
BoxConstraints loosen() { BoxConstraints loosen() {
assert(isNormalized); assert(isNormalized);
return new BoxConstraints( return new BoxConstraints(
@ -113,7 +113,8 @@ class BoxConstraints extends Constraints {
); );
} }
/// Returns new box constraints that respect the given constraints while being as close as possible to the original constraints /// Returns new box constraints that respect the given constraints while being
/// as close as possible to the original constraints.
BoxConstraints enforce(BoxConstraints constraints) { BoxConstraints enforce(BoxConstraints constraints) {
return new BoxConstraints( return new BoxConstraints(
minWidth: clamp(min: constraints.minWidth, max: constraints.maxWidth, value: minWidth), minWidth: clamp(min: constraints.minWidth, max: constraints.maxWidth, value: minWidth),
@ -123,7 +124,8 @@ class BoxConstraints extends Constraints {
); );
} }
/// Returns new box constraints with a tight width as close to the given width as possible while still respecting the original box constraints /// Returns new box constraints with a tight width as close to the given width
/// as possible while still respecting the original box constraints.
BoxConstraints tightenWidth(double width) { BoxConstraints tightenWidth(double width) {
return new BoxConstraints(minWidth: math.max(math.min(maxWidth, width), minWidth), return new BoxConstraints(minWidth: math.max(math.min(maxWidth, width), minWidth),
maxWidth: math.max(math.min(maxWidth, width), minWidth), maxWidth: math.max(math.min(maxWidth, width), minWidth),
@ -131,7 +133,8 @@ class BoxConstraints extends Constraints {
maxHeight: maxHeight); maxHeight: maxHeight);
} }
/// Returns new box constraints with a tight height as close to the given height as possible while still respecting the original box constraints /// Returns new box constraints with a tight height as close to the given
/// height as possible while still respecting the original box constraints.
BoxConstraints tightenHeight(double height) { BoxConstraints tightenHeight(double height) {
return new BoxConstraints(minWidth: minWidth, return new BoxConstraints(minWidth: minWidth,
maxWidth: maxWidth, maxWidth: maxWidth,
@ -139,25 +142,30 @@ class BoxConstraints extends Constraints {
maxHeight: math.max(math.min(maxHeight, height), minHeight)); maxHeight: math.max(math.min(maxHeight, height), minHeight));
} }
/// Returns box constraints with the same width constraints but with unconstrainted height /// Returns box constraints with the same width constraints but with
/// unconstrainted height.
BoxConstraints widthConstraints() => new BoxConstraints(minWidth: minWidth, maxWidth: maxWidth); BoxConstraints widthConstraints() => new BoxConstraints(minWidth: minWidth, maxWidth: maxWidth);
/// Returns box constraints with the same height constraints but with unconstrainted width /// Returns box constraints with the same height constraints but with
/// unconstrainted width
BoxConstraints heightConstraints() => new BoxConstraints(minHeight: minHeight, maxHeight: maxHeight); BoxConstraints heightConstraints() => new BoxConstraints(minHeight: minHeight, maxHeight: maxHeight);
/// Returns the width that both satisfies the constraints and is as close as possible to the given width /// Returns the width that both satisfies the constraints and is as close as
/// possible to the given width.
double constrainWidth([double width = double.INFINITY]) { double constrainWidth([double width = double.INFINITY]) {
assert(isNormalized); assert(isNormalized);
return clamp(min: minWidth, max: maxWidth, value: width); return clamp(min: minWidth, max: maxWidth, value: width);
} }
/// Returns the height that both satisfies the constraints and is as close as possible to the given height /// Returns the height that both satisfies the constraints and is as close as
/// possible to the given height.
double constrainHeight([double height = double.INFINITY]) { double constrainHeight([double height = double.INFINITY]) {
assert(isNormalized); assert(isNormalized);
return clamp(min: minHeight, max: maxHeight, value: height); return clamp(min: minHeight, max: maxHeight, value: height);
} }
/// Returns the size that both satisfies the constraints and is as close as possible to the given size /// Returns the size that both satisfies the constraints and is as close as
/// possible to the given size.
Size constrain(Size size) { Size constrain(Size size) {
Size result = new Size(constrainWidth(size.width), constrainHeight(size.height)); Size result = new Size(constrainWidth(size.width), constrainHeight(size.height));
assert(() { assert(() {
@ -168,22 +176,22 @@ class BoxConstraints extends Constraints {
return result; return result;
} }
/// The biggest size that satisifes the constraints /// The biggest size that satisifes the constraints.
Size get biggest => new Size(constrainWidth(), constrainHeight()); Size get biggest => new Size(constrainWidth(), constrainHeight());
/// The smallest size that satisfies the constraints /// The smallest size that satisfies the constraints.
Size get smallest => new Size(constrainWidth(0.0), constrainHeight(0.0)); Size get smallest => new Size(constrainWidth(0.0), constrainHeight(0.0));
/// Whether there is exactly one width value that satisfies the constraints /// Whether there is exactly one width value that satisfies the constraints.
bool get hasTightWidth => minWidth >= maxWidth; bool get hasTightWidth => minWidth >= maxWidth;
/// Whether there is exactly one height value that satisfies the constraints /// Whether there is exactly one height value that satisfies the constraints.
bool get hasTightHeight => minHeight >= maxHeight; bool get hasTightHeight => minHeight >= maxHeight;
/// Whether there is exactly one size that satifies the constraints /// Whether there is exactly one size that satifies the constraints.
bool get isTight => hasTightWidth && hasTightHeight; bool get isTight => hasTightWidth && hasTightHeight;
/// Whether the given size satisfies the constraints /// Whether the given size satisfies the constraints.
bool isSatisfiedBy(Size size) { bool isSatisfiedBy(Size size) {
assert(isNormalized); assert(isNormalized);
return (minWidth <= size.width) && (size.width <= maxWidth) && return (minWidth <= size.width) && (size.width <= maxWidth) &&
@ -226,7 +234,7 @@ class BoxConstraints extends Constraints {
); );
} }
/// Linearly interpolate between two BoxConstraints /// Linearly interpolate between two BoxConstraints.
/// ///
/// If either is null, this function interpolates from [BoxConstraints.zero]. /// If either is null, this function interpolates from [BoxConstraints.zero].
static BoxConstraints lerp(BoxConstraints a, BoxConstraints b, double t) { static BoxConstraints lerp(BoxConstraints a, BoxConstraints b, double t) {
@ -294,19 +302,19 @@ class BoxConstraints extends Constraints {
} }
} }
/// A hit test entry used by [RenderBox] /// A hit test entry used by [RenderBox].
class BoxHitTestEntry extends HitTestEntry { class BoxHitTestEntry extends HitTestEntry {
const BoxHitTestEntry(RenderBox target, this.localPosition) : super(target); const BoxHitTestEntry(RenderBox target, this.localPosition) : super(target);
RenderBox get target => super.target; RenderBox get target => super.target;
/// The position of the hit test in the local coordinates of [target] /// The position of the hit test in the local coordinates of [target].
final Point localPosition; final Point localPosition;
String toString() => '${target.runtimeType}@$localPosition'; String toString() => '${target.runtimeType}@$localPosition';
} }
/// Parent data used by [RenderBox] and its subclasses /// Parent data used by [RenderBox] and its subclasses.
class BoxParentData extends ParentData { class BoxParentData extends ParentData {
// TODO(abarth): Switch to using an Offset rather than a Point here. This // TODO(abarth): Switch to using an Offset rather than a Point here. This
// value is really the offset from the parent. // value is really the offset from the parent.
@ -325,7 +333,7 @@ class BoxParentData extends ParentData {
/// ContainerRenderObjectMixin. /// ContainerRenderObjectMixin.
abstract class ContainerBoxParentDataMixin<ChildType extends RenderObject> extends BoxParentData with ContainerParentDataMixin<ChildType> { } abstract class ContainerBoxParentDataMixin<ChildType extends RenderObject> extends BoxParentData with ContainerParentDataMixin<ChildType> { }
/// A render object in a 2D cartesian coordinate system /// A render object in a 2D cartesian coordinate system.
/// ///
/// The size of each box is expressed as a width and a height. Each box has its /// The size of each box is expressed as a width and a height. Each box has its
/// own coordinate system in which its upper left corner is placed at (0, 0). /// own coordinate system in which its upper left corner is placed at (0, 0).
@ -351,7 +359,7 @@ abstract class RenderBox extends RenderObject {
} }
/// Returns the minimum width that this box could be without failing to paint /// Returns the minimum width that this box could be without failing to paint
/// its contents within itself /// its contents within itself.
/// ///
/// Override in subclasses that implement [performLayout]. /// Override in subclasses that implement [performLayout].
double getMinIntrinsicWidth(BoxConstraints constraints) { double getMinIntrinsicWidth(BoxConstraints constraints) {
@ -360,7 +368,7 @@ abstract class RenderBox extends RenderObject {
} }
/// Returns the smallest width beyond which increasing the width never /// Returns the smallest width beyond which increasing the width never
/// decreases the height /// decreases the height.
/// ///
/// Override in subclasses that implement [performLayout]. /// Override in subclasses that implement [performLayout].
double getMaxIntrinsicWidth(BoxConstraints constraints) { double getMaxIntrinsicWidth(BoxConstraints constraints) {
@ -390,7 +398,7 @@ abstract class RenderBox extends RenderObject {
return constraints.constrainHeight(0.0); return constraints.constrainHeight(0.0);
} }
/// The size of this render box computed during layout /// The size of this render box computed during layout.
/// ///
/// This value is stale whenever this object is marked as needing layout. /// This value is stale whenever this object is marked as needing layout.
/// During [performLayout], do not read the size of a child unless you pass /// During [performLayout], do not read the size of a child unless you pass
@ -521,7 +529,7 @@ abstract class RenderBox extends RenderObject {
return null; return null;
} }
/// The box constraints most recently received from the parent /// The box constraints most recently received from the parent.
BoxConstraints get constraints => super.constraints; BoxConstraints get constraints => super.constraints;
bool debugDoesMeetConstraints() { bool debugDoesMeetConstraints() {
assert(constraints != null); assert(constraints != null);
@ -571,7 +579,7 @@ abstract class RenderBox extends RenderObject {
}); });
} }
/// Determines the set of render objects located at the given position /// Determines the set of render objects located at the given position.
/// ///
/// Returns true if the given point is contained in this render object or one /// Returns true if the given point is contained in this render object or one
/// of its descendants. Adds any render objects that contain the point to the /// of its descendants. Adds any render objects that contain the point to the
@ -594,11 +602,11 @@ abstract class RenderBox extends RenderObject {
} }
/// Override this function if this render object can be hit even if its /// Override this function if this render object can be hit even if its
/// children were not hit /// children were not hit.
bool hitTestSelf(Point position) => false; bool hitTestSelf(Point position) => false;
/// Override this function to check whether any children are located at the /// Override this function to check whether any children are located at the
/// given position /// given position.
/// ///
/// Typically children should be hit tested in reverse paint order so that /// Typically children should be hit tested in reverse paint order so that
/// hit tests at locations where children overlap hit the child that is /// hit tests at locations where children overlap hit the child that is
@ -628,7 +636,7 @@ abstract class RenderBox extends RenderObject {
} }
/// Convert the given point from the global coodinate system to the local /// Convert the given point from the global coodinate system to the local
/// coordinate system for this box /// coordinate system for this box.
Point globalToLocal(Point point) { Point globalToLocal(Point point) {
assert(attached); assert(attached);
Matrix4 transform = new Matrix4.identity(); Matrix4 transform = new Matrix4.identity();
@ -655,7 +663,7 @@ abstract class RenderBox extends RenderObject {
return _transformPoint(transform, point); return _transformPoint(transform, point);
} }
/// Returns a rectangle that contains all the pixels painted by this box /// Returns a rectangle that contains all the pixels painted by this box.
/// ///
/// The paint bounds can be larger or smaller than [size], which is the amount /// The paint bounds can be larger or smaller than [size], which is the amount
/// of space this box takes up during layout. For example, if this box casts a /// of space this box takes up during layout. For example, if this box casts a
@ -747,7 +755,7 @@ abstract class RenderBox extends RenderObject {
/// appropriate. /// appropriate.
abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, ParentDataType extends ContainerBoxParentDataMixin<ChildType>> implements ContainerRenderObjectMixin<ChildType, ParentDataType> { abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, ParentDataType extends ContainerBoxParentDataMixin<ChildType>> implements ContainerRenderObjectMixin<ChildType, ParentDataType> {
/// Returns the baseline of the first child with a baseline /// Returns the baseline of the first child with a baseline.
/// ///
/// Useful when the children are displayed vertically in the same order they /// Useful when the children are displayed vertically in the same order they
/// appear in the child list. /// appear in the child list.
@ -764,7 +772,7 @@ abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, Pare
return null; return null;
} }
/// Returns the minimum baseline value among every child /// Returns the minimum baseline value among every child.
/// ///
/// Useful when the vertical position of the children isn't determined by the /// Useful when the vertical position of the children isn't determined by the
/// order in the child list. /// order in the child list.
@ -787,7 +795,7 @@ abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, Pare
return result; return result;
} }
/// Performs a hit test on each child by walking the child list backwards /// Performs a hit test on each child by walking the child list backwards.
/// ///
/// Stops walking once after the first child reports that it contains the /// Stops walking once after the first child reports that it contains the
/// given point. Returns whether any children contain the given point. /// given point. Returns whether any children contain the given point.
@ -805,7 +813,7 @@ abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, Pare
return false; return false;
} }
/// Paints each child by walking the child list forwards /// Paints each child by walking the child list forwards.
void defaultPaint(PaintingContext context, Offset offset) { void defaultPaint(PaintingContext context, Offset offset) {
RenderBox child = firstChild; RenderBox child = firstChild;
while (child != null) { while (child != null) {

99
packages/flutter/lib/src/rendering/object.dart
View File

@ -19,7 +19,7 @@ export 'package:flutter/gestures.dart' show HitTestEntry, HitTestResult;
typedef ui.Shader ShaderCallback(Rect bounds); typedef ui.Shader ShaderCallback(Rect bounds);
/// Base class for data associated with a [RenderObject] by its parent /// Base class for data associated with a [RenderObject] by its parent.
/// ///
/// Some render objects wish to store data on their children, such as their /// Some render objects wish to store data on their children, such as their
/// input parameters to the parent's layout algorithm or their position relative /// input parameters to the parent's layout algorithm or their position relative
@ -356,7 +356,7 @@ abstract class Painter {
void paint(PaintingContext context, Offset offset); void paint(PaintingContext context, Offset offset);
} }
/// An abstract set of layout constraints /// An abstract set of layout constraints.
/// ///
/// Concrete layout models (such as box) will create concrete subclasses to /// Concrete layout models (such as box) will create concrete subclasses to
/// communicate layout constraints between parents and children. /// communicate layout constraints between parents and children.
@ -385,7 +385,7 @@ typedef void RenderingExceptionHandler(RenderObject source, String method, dynam
/// information, such as from [debugDumpRenderTree()]. /// information, such as from [debugDumpRenderTree()].
RenderingExceptionHandler debugRenderingExceptionHandler; RenderingExceptionHandler debugRenderingExceptionHandler;
/// An object in the render tree /// An object in the render tree.
/// ///
/// Render objects have a reference to their parent but do not commit to a model /// Render objects have a reference to their parent but do not commit to a model
/// for their children. /// for their children.
@ -393,7 +393,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
// LAYOUT // LAYOUT
/// Data for use by the parent render object /// Data for use by the parent render object.
/// ///
/// The parent data is used by the render object that lays out this object /// The parent data is used by the render object that lays out this object
/// (typically this object's parent in the render tree) to store information /// (typically this object's parent in the render tree) to store information
@ -410,7 +410,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// permitted to read some fields of the parent data. /// permitted to read some fields of the parent data.
ParentData parentData; ParentData parentData;
/// Override to setup parent data correctly for your children /// Override to setup parent data correctly for your children.
/// ///
/// You can call this function to set up the parent data for child before the /// You can call this function to set up the parent data for child before the
/// child is added to the parent's child list. /// child is added to the parent's child list.
@ -420,7 +420,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
child.parentData = new ParentData(); child.parentData = new ParentData();
} }
/// Called by subclasses when they decide a render object is a child /// Called by subclasses when they decide a render object is a child.
/// ///
/// Only for use by subclasses when changing their child lists. Calling this /// Only for use by subclasses when changing their child lists. Calling this
/// in other cases will lead to an inconsistent tree and probably cause crashes. /// in other cases will lead to an inconsistent tree and probably cause crashes.
@ -433,7 +433,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
_markNeedsCompositingBitsUpdate(); _markNeedsCompositingBitsUpdate();
} }
/// Called by subclasses when they decide a render object is no longer a child /// Called by subclasses when they decide a render object is no longer a child.
/// ///
/// Only for use by subclasses when changing their child lists. Calling this /// Only for use by subclasses when changing their child lists. Calling this
/// in other cases will lead to an inconsistent tree and probably cause crashes. /// in other cases will lead to an inconsistent tree and probably cause crashes.
@ -449,7 +449,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
_markNeedsCompositingBitsUpdate(); _markNeedsCompositingBitsUpdate();
} }
/// Calls visitor for each immediate child of this render object /// Calls visitor for each immediate child of this render object.
/// ///
/// Override in subclasses with children and call the visitor for each child /// Override in subclasses with children and call the visitor for each child
void visitChildren(RenderObjectVisitor visitor) { } void visitChildren(RenderObjectVisitor visitor) { }
@ -494,14 +494,14 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
static List<RenderObject> _nodesNeedingLayout = new List<RenderObject>(); static List<RenderObject> _nodesNeedingLayout = new List<RenderObject>();
bool _needsLayout = true; bool _needsLayout = true;
/// Whether this render object's layout information is dirty /// Whether this render object's layout information is dirty.
bool get needsLayout => _needsLayout; bool get needsLayout => _needsLayout;
RenderObject _relayoutSubtreeRoot; RenderObject _relayoutSubtreeRoot;
bool _doingThisLayoutWithCallback = false; bool _doingThisLayoutWithCallback = false;
Constraints _constraints; Constraints _constraints;
/// The layout constraints most recently supplied by the parent /// The layout constraints most recently supplied by the parent.
Constraints get constraints => _constraints; Constraints get constraints => _constraints;
/// Override this function in a subclass to verify that your state matches the constraints object /// Override this function in a subclass to verify that your state matches the constraints object.
bool debugDoesMeetConstraints(); bool debugDoesMeetConstraints();
bool debugAncestorsAlreadyMarkedNeedsLayout() { bool debugAncestorsAlreadyMarkedNeedsLayout() {
if (_relayoutSubtreeRoot == null) if (_relayoutSubtreeRoot == null)
@ -518,7 +518,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
return true; return true;
} }
/// Mark this render object's layout information as dirty /// Mark this render object's layout information as dirty.
/// ///
/// Rather than eagerly updating layout information in response to writes into /// Rather than eagerly updating layout information in response to writes into
/// this render object, we instead mark the layout information as dirty, which /// this render object, we instead mark the layout information as dirty, which
@ -564,7 +564,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
} }
/// Bootstrap the rendering pipeline by scheduling the very first layout /// Bootstrap the rendering pipeline by scheduling the very first layout.
/// ///
/// Requires this render object to be attached and that this render object /// Requires this render object to be attached and that this render object
/// is the root of the render tree. /// is the root of the render tree.
@ -583,7 +583,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
_nodesNeedingLayout.add(this); _nodesNeedingLayout.add(this);
} }
/// Update the layout information for all dirty render objects /// Update the layout information for all dirty render objects.
/// ///
/// This function is one of the core stages of the rendering pipeline. Layout /// This function is one of the core stages of the rendering pipeline. Layout
/// information is cleaned prior to painting so that render objects will /// information is cleaned prior to painting so that render objects will
@ -636,7 +636,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
markNeedsPaint(); markNeedsPaint();
} }
/// Compute the layout for this render object /// Compute the layout for this render object.
/// ///
/// This function is the main entry point for parents to ask their children to /// This function is the main entry point for parents to ask their children to
/// update their layout information. The parent passes a constraints object, /// update their layout information. The parent passes a constraints object,
@ -740,14 +740,14 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
void debugResetSize() { } void debugResetSize() { }
/// Whether the constraints are the only input to the sizing algorithm (in /// Whether the constraints are the only input to the sizing algorithm (in
/// particular, child nodes have no impact) /// particular, child nodes have no impact).
/// ///
/// Returning false is always correct, but returning true can be more /// Returning false is always correct, but returning true can be more
/// efficient when computing the size of this render object because we don't /// efficient when computing the size of this render object because we don't
/// need to recompute the size if the constraints don't change. /// need to recompute the size if the constraints don't change.
bool get sizedByParent => false; bool get sizedByParent => false;
/// Updates the render objects size using only the constraints /// Updates the render objects size using only the constraints.
/// ///
/// Do not call this function directly: call [layout] instead. This function /// Do not call this function directly: call [layout] instead. This function
/// is called by [layout] when there is actually work to be done by this /// is called by [layout] when there is actually work to be done by this
@ -760,7 +760,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// Note: This function is called only if [sizedByParent] is true. /// Note: This function is called only if [sizedByParent] is true.
void performResize(); void performResize();
/// Do the work of computing the layout for this render object /// Do the work of computing the layout for this render object.
/// ///
/// Do not call this function directly: call [layout] instead. This function /// Do not call this function directly: call [layout] instead. This function
/// is called by [layout] when there is actually work to be done by this /// is called by [layout] when there is actually work to be done by this
@ -782,7 +782,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
void performLayout(); void performLayout();
/// Allows this render object to mutation its child list during layout and /// Allows this render object to mutation its child list during layout and
/// invokes callback /// invokes callback.
void invokeLayoutCallback(LayoutCallback callback) { void invokeLayoutCallback(LayoutCallback callback) {
assert(_debugMutationsLocked); assert(_debugMutationsLocked);
assert(_debugDoingThisLayout); assert(_debugDoingThisLayout);
@ -795,7 +795,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
} }
/// Rotate this render object (not yet implemented) /// Rotate this render object (not yet implemented).
void rotate({ void rotate({
int oldAngle, // 0..3 int oldAngle, // 0..3
int newAngle, // 0..3 int newAngle, // 0..3
@ -824,7 +824,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
static List<RenderObject> _nodesNeedingPaint = new List<RenderObject>(); static List<RenderObject> _nodesNeedingPaint = new List<RenderObject>();
/// Whether this render object paints using a composited layer /// Whether this render object paints using a composited layer.
/// ///
/// Override this in subclasses to indicate that instances of your class need /// Override this in subclasses to indicate that instances of your class need
/// to have their own compositing layer. For example, videos should return /// to have their own compositing layer. For example, videos should return
@ -834,7 +834,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
bool get hasLayer => false; bool get hasLayer => false;
ContainerLayer _layer; ContainerLayer _layer;
/// The compositing layer that this render object uses to paint /// The compositing layer that this render object uses to paint.
/// ///
/// Call only when [hasLayer] is true. /// Call only when [hasLayer] is true.
ContainerLayer get layer { ContainerLayer get layer {
@ -844,7 +844,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
bool _needsCompositingBitsUpdate = true; bool _needsCompositingBitsUpdate = true;
/// Mark the compositing state for this render object as dirty /// Mark the compositing state for this render object as dirty.
/// ///
/// When the subtree is mutated, we need to recompute our [needsCompositing] /// When the subtree is mutated, we need to recompute our [needsCompositing]
/// bit, and our ancestors need to do the same (in case ours changed). /// bit, and our ancestors need to do the same (in case ours changed).
@ -859,8 +859,9 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
parent._markNeedsCompositingBitsUpdate(); parent._markNeedsCompositingBitsUpdate();
assert(parent == this.parent); assert(parent == this.parent);
} }
bool _needsCompositing = false; bool _needsCompositing = false;
/// Whether we or one of our descendants has a compositing layer /// Whether we or one of our descendants has a compositing layer.
/// ///
/// Only legal to call after [flushLayout] and [updateCompositingBits] have /// Only legal to call after [flushLayout] and [updateCompositingBits] have
/// been called. /// been called.
@ -869,7 +870,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
return _needsCompositing; return _needsCompositing;
} }
/// Updates the [needsCompositing] bits /// Updates the [needsCompositing] bits.
/// ///
/// Called as part of the rendering pipeline after [flushLayout] and before /// Called as part of the rendering pipeline after [flushLayout] and before
/// [flushPaint]. /// [flushPaint].
@ -890,10 +891,10 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
bool _needsPaint = true; bool _needsPaint = true;
/// The visual appearance of this render object has changed since it last painted /// The visual appearance of this render object has changed since it last painted.
bool get needsPaint => _needsPaint; bool get needsPaint => _needsPaint;
/// Mark this render object as having changed its visual appearance /// Mark this render object as having changed its visual appearance.
/// ///
/// Rather than eagerly updating this render object's display list /// Rather than eagerly updating this render object's display list
/// in response to writes, we instead mark the the render object as needing to /// in response to writes, we instead mark the the render object as needing to
@ -933,7 +934,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
} }
/// Update the display lists for all render objects /// Update the display lists for all render objects.
/// ///
/// This function is one of the core stages of the rendering pipeline. /// This function is one of the core stages of the rendering pipeline.
/// Painting occurs after layout and before the scene is recomposited so that /// Painting occurs after layout and before the scene is recomposited so that
@ -959,7 +960,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
} }
/// Bootstrap the rendering pipeline by scheduling the very first paint /// Bootstrap the rendering pipeline by scheduling the very first paint.
/// ///
/// Requires that this render object is attached, is the root of the render /// Requires that this render object is attached, is the root of the render
/// tree, and has a composited layer. /// tree, and has a composited layer.
@ -1003,7 +1004,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
}); });
} }
/// The bounds within which this render object will paint /// The bounds within which this render object will paint.
/// ///
/// A render object is permitted to paint outside the region it occupies /// A render object is permitted to paint outside the region it occupies
/// during layout but is not permitted to paint outside these paints bounds. /// during layout but is not permitted to paint outside these paints bounds.
@ -1013,10 +1014,10 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
/// layer. /// layer.
Rect get paintBounds; Rect get paintBounds;
/// Override this function to paint debugging information /// Override this function to paint debugging information.
void debugPaint(PaintingContext context, Offset offset) { } void debugPaint(PaintingContext context, Offset offset) { }
/// Paint this render object into the given context at the given offset /// Paint this render object into the given context at the given offset.
/// ///
/// Subclasses should override this function to provide a visual appearance /// Subclasses should override this function to provide a visual appearance
/// for themselves. The render object's local coordinate system is /// for themselves. The render object's local coordinate system is
@ -1071,7 +1072,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
// You must not add yourself to /result/ if you return false. // You must not add yourself to /result/ if you return false.
/// Returns a human understandable name /// Returns a human understandable name.
String toString() { String toString() {
String header = '$runtimeType'; String header = '$runtimeType';
if (_relayoutSubtreeRoot != null && _relayoutSubtreeRoot != this) { if (_relayoutSubtreeRoot != null && _relayoutSubtreeRoot != this) {
@ -1125,7 +1126,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
} }
/// Obsolete function that will be removed eventually /// Obsolete function that will be removed eventually.
double clamp({ double min: 0.0, double value: 0.0, double max: double.INFINITY }) { double clamp({ double min: 0.0, double value: 0.0, double max: double.INFINITY }) {
assert(min != null); assert(min != null);
assert(value != null); assert(value != null);
@ -1134,9 +1135,9 @@ double clamp({ double min: 0.0, double value: 0.0, double max: double.INFINITY }
} }
/// Generic mixin for render objects with one child /// Generic mixin for render objects with one child.
/// ///
/// Provides a child model for a render object subclass that has a unique child /// Provides a child model for a render object subclass that has a unique child.
abstract class RenderObjectWithChildMixin<ChildType extends RenderObject> implements RenderObject { abstract class RenderObjectWithChildMixin<ChildType extends RenderObject> implements RenderObject {
ChildType _child; ChildType _child;
/// The render object's unique child /// The render object's unique child
@ -1169,11 +1170,11 @@ abstract class RenderObjectWithChildMixin<ChildType extends RenderObject> implem
} }
} }
/// Parent data to support a doubly-linked list of children /// Parent data to support a doubly-linked list of children.
abstract class ContainerParentDataMixin<ChildType extends RenderObject> implements ParentData { abstract class ContainerParentDataMixin<ChildType extends RenderObject> implements ParentData {
/// The previous sibling in the parent's child list /// The previous sibling in the parent's child list.
ChildType previousSibling; ChildType previousSibling;
/// The next sibling in the parent's child list /// The next sibling in the parent's child list.
ChildType nextSibling; ChildType nextSibling;
/// Clear the sibling pointers. /// Clear the sibling pointers.
@ -1196,7 +1197,7 @@ abstract class ContainerParentDataMixin<ChildType extends RenderObject> implemen
} }
} }
/// Generic mixin for render objects with a list of children /// Generic mixin for render objects with a list of children.
/// ///
/// Provides a child model for a render object subclass that has a doubly-linked /// Provides a child model for a render object subclass that has a doubly-linked
/// list of children. /// list of children.
@ -1222,7 +1223,7 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
} }
int _childCount = 0; int _childCount = 0;
/// The number of children /// The number of children.
int get childCount => _childCount; int get childCount => _childCount;
ChildType _firstChild; ChildType _firstChild;
@ -1269,7 +1270,7 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
} }
} }
} }
/// Insert child into this render object's child list before the given child /// Insert child into this render object's child list before the given child.
/// ///
/// To insert a child at the end of the child list, omit the before parameter. /// To insert a child at the end of the child list, omit the before parameter.
void add(ChildType child, { ChildType before }) { void add(ChildType child, { ChildType before }) {
@ -1282,7 +1283,7 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
_addToChildList(child, before: before); _addToChildList(child, before: before);
} }
/// Add all the children to the end of this render object's child list /// Add all the children to the end of this render object's child list.
void addAll(List<ChildType> children) { void addAll(List<ChildType> children) {
if (children != null) if (children != null)
for (ChildType child in children) for (ChildType child in children)
@ -1313,7 +1314,7 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
_childCount -= 1; _childCount -= 1;
} }
/// Remove this child from the child list /// Remove this child from the child list.
/// ///
/// Requires the child to be present in the child list. /// Requires the child to be present in the child list.
void remove(ChildType child) { void remove(ChildType child) {
@ -1321,7 +1322,7 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
dropChild(child); dropChild(child);
} }
/// Remove all their children from this render object's child list /// Remove all their children from this render object's child list.
/// ///
/// More efficient than removing them individually. /// More efficient than removing them individually.
void removeAll() { void removeAll() {
@ -1339,7 +1340,7 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
_childCount = 0; _childCount = 0;
} }
/// Move this child in the child list to be before the given child /// Move this child in the child list to be before the given child.
/// ///
/// More efficient than removing and re-adding the child. Requires the child /// More efficient than removing and re-adding the child. Requires the child
/// to already be in the child list at some position. Pass null for before to /// to already be in the child list at some position. Pass null for before to
@ -1394,13 +1395,13 @@ abstract class ContainerRenderObjectMixin<ChildType extends RenderObject, Parent
} }
} }
/// The first child in the child list /// The first child in the child list.
ChildType get firstChild => _firstChild; ChildType get firstChild => _firstChild;
/// The last child in the child list /// The last child in the child list.
ChildType get lastChild => _lastChild; ChildType get lastChild => _lastChild;
/// The next child after the given child in the child list /// The next child after the given child in the child list.
ChildType childAfter(ChildType child) { ChildType childAfter(ChildType child) {
final ParentDataType childParentData = child.parentData; final ParentDataType childParentData = child.parentData;
return childParentData.nextSibling; return childParentData.nextSibling;

20
packages/flutter/lib/src/rendering/view.dart
View File

@ -14,23 +14,23 @@ import 'debug.dart';
import 'layer.dart'; import 'layer.dart';
import 'object.dart'; import 'object.dart';
/// The layout constraints for the root render object /// The layout constraints for the root render object.
class ViewConstraints { class ViewConstraints {
const ViewConstraints({ const ViewConstraints({
this.size: Size.zero, this.size: Size.zero,
this.orientation this.orientation
}); });
/// The size of the output surface /// The size of the output surface.
final Size size; final Size size;
/// The orientation of the output surface (aspirational) /// The orientation of the output surface (aspirational).
final int orientation; final int orientation;
String toString() => '$size'; String toString() => '$size';
} }
/// The root of the render tree /// The root of the render tree.
/// ///
/// The view represents the total output surface of the render tree and handles /// The view represents the total output surface of the render tree and handles
/// bootstraping the rendering pipeline. The view has a unique child /// bootstraping the rendering pipeline. The view has a unique child
@ -43,18 +43,18 @@ class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox>
this.child = child; this.child = child;
} }
/// The amount of time the screen rotation animation should last (aspirational) /// The amount of time the screen rotation animation should last (aspirational).
Duration timeForRotation; Duration timeForRotation;
/// The current layout size of the view /// The current layout size of the view.
Size get size => _size; Size get size => _size;
Size _size = Size.zero; Size _size = Size.zero;
/// The current orientation of the view (aspirational) /// The current orientation of the view (aspirational).
int get orientation => _orientation; int get orientation => _orientation;
int _orientation; // 0..3 int _orientation; // 0..3
/// The constraints used for the root layout /// The constraints used for the root layout.
ViewConstraints get rootConstraints => _rootConstraints; ViewConstraints get rootConstraints => _rootConstraints;
ViewConstraints _rootConstraints; ViewConstraints _rootConstraints;
void set rootConstraints(ViewConstraints value) { void set rootConstraints(ViewConstraints value) {
@ -69,7 +69,7 @@ class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox>
return new Matrix4.diagonal3Values(devicePixelRatio, devicePixelRatio, 1.0); return new Matrix4.diagonal3Values(devicePixelRatio, devicePixelRatio, 1.0);
} }
/// Bootstrap the rendering pipeline by scheduling the first frame /// Bootstrap the rendering pipeline by scheduling the first frame.
void scheduleInitialFrame() { void scheduleInitialFrame() {
scheduleInitialLayout(); scheduleInitialLayout();
scheduleInitialPaint(new TransformLayer(transform: _logicalToDeviceTransform)); scheduleInitialPaint(new TransformLayer(transform: _logicalToDeviceTransform));
@ -115,7 +115,7 @@ class RenderView extends RenderObject with RenderObjectWithChildMixin<RenderBox>
context.paintChild(child, offset); context.paintChild(child, offset);
} }
/// Uploads the composited layer tree to the engine /// Uploads the composited layer tree to the engine.
/// ///
/// Actually causes the output of the rendering pipeline to appear on screen. /// Actually causes the output of the rendering pipeline to appear on screen.
void compositeFrame() { void compositeFrame() {