| // Copyright 2014 The Flutter Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| import 'dart:math' as math; |
| import 'dart:ui' as ui show lerpDouble; |
| |
| import 'package:flutter/foundation.dart'; |
| import 'package:flutter/gestures.dart'; |
| |
| import 'package:vector_math/vector_math_64.dart'; |
| |
| import 'debug.dart'; |
| import 'object.dart'; |
| |
| // This class should only be used in debug builds. |
| class _DebugSize extends Size { |
| _DebugSize(Size source, this._owner, this._canBeUsedByParent) : super.copy(source); |
| final RenderBox _owner; |
| final bool _canBeUsedByParent; |
| } |
| |
| /// Immutable layout constraints for [RenderBox] layout. |
| /// |
| /// A [Size] respects a [BoxConstraints] if, and only if, all of the following |
| /// relations hold: |
| /// |
| /// * [minWidth] <= [Size.width] <= [maxWidth] |
| /// * [minHeight] <= [Size.height] <= [maxHeight] |
| /// |
| /// The constraints themselves must satisfy these relations: |
| /// |
| /// * 0.0 <= [minWidth] <= [maxWidth] <= [double.infinity] |
| /// * 0.0 <= [minHeight] <= [maxHeight] <= [double.infinity] |
| /// |
| /// [double.infinity] is a legal value for each constraint. |
| /// |
| /// ## The box layout model |
| /// |
| /// Render objects in the Flutter framework are laid out by a one-pass layout |
| /// model which walks down the render tree passing constraints, then walks back |
| /// up the render tree passing concrete geometry. |
| /// |
| /// For boxes, the constraints are [BoxConstraints], which, as described herein, |
| /// consist of four numbers: a minimum width [minWidth], a maximum width |
| /// [maxWidth], a minimum height [minHeight], and a maximum height [maxHeight]. |
| /// |
| /// The geometry for boxes consists of a [Size], which must satisfy the |
| /// constraints described above. |
| /// |
| /// Each [RenderBox] (the objects that provide the layout models for box |
| /// widgets) receives [BoxConstraints] from its parent, then lays out each of |
| /// its children, then picks a [Size] that satisfies the [BoxConstraints]. |
| /// |
| /// Render objects position their children independently of laying them out. |
| /// Frequently, the parent will use the children's sizes to determine their |
| /// position. A child does not know its position and will not necessarily be |
| /// laid out again, or repainted, if its position changes. |
| /// |
| /// ## Terminology |
| /// |
| /// When the minimum constraints and the maximum constraint in an axis are the |
| /// same, that axis is _tightly_ constrained. See: [new |
| /// BoxConstraints.tightFor], [new BoxConstraints.tightForFinite], [tighten], |
| /// [hasTightWidth], [hasTightHeight], [isTight]. |
| /// |
| /// An axis with a minimum constraint of 0.0 is _loose_ (regardless of the |
| /// maximum constraint; if it is also 0.0, then the axis is simultaneously tight |
| /// and loose!). See: [new BoxConstraints.loose], [loosen]. |
| /// |
| /// An axis whose maximum constraint is not infinite is _bounded_. See: |
| /// [hasBoundedWidth], [hasBoundedHeight]. |
| /// |
| /// An axis whose maximum constraint is infinite is _unbounded_. An axis is |
| /// _expanding_ if it is tightly infinite (its minimum and maximum constraints |
| /// are both infinite). See: [new BoxConstraints.expand]. |
| /// |
| /// An axis whose _minimum_ constraint is infinite is just said to be _infinite_ |
| /// (since by definition the maximum constraint must also be infinite in that |
| /// case). See: [hasInfiniteWidth], [hasInfiniteHeight]. |
| /// |
| /// A size is _constrained_ when it satisfies a [BoxConstraints] description. |
| /// See: [constrain], [constrainWidth], [constrainHeight], |
| /// [constrainDimensions], [constrainSizeAndAttemptToPreserveAspectRatio], |
| /// [isSatisfiedBy]. |
| class BoxConstraints extends Constraints { |
| /// Creates box constraints with the given constraints. |
| const BoxConstraints({ |
| this.minWidth = 0.0, |
| this.maxWidth = double.infinity, |
| this.minHeight = 0.0, |
| this.maxHeight = double.infinity, |
| }) : assert (minWidth != null), |
| assert (maxWidth != null), |
| assert (minHeight != null), |
| assert (maxHeight != null); |
| |
| /// Creates box constraints that is respected only by the given size. |
| BoxConstraints.tight(Size size) |
| : minWidth = size.width, |
| maxWidth = size.width, |
| minHeight = size.height, |
| maxHeight = size.height; |
| |
| /// Creates box constraints that require the given width or height. |
| /// |
| /// See also: |
| /// |
| /// * [new BoxConstraints.tightForFinite], which is similar but instead of |
| /// being tight if the value is non-null, is tight if the value is not |
| /// infinite. |
| const BoxConstraints.tightFor({ |
| double width, |
| double height, |
| }) : minWidth = width ?? 0.0, |
| maxWidth = width ?? double.infinity, |
| minHeight = height ?? 0.0, |
| maxHeight = height ?? double.infinity; |
| |
| /// Creates box constraints that require the given width or height, except if |
| /// they are infinite. |
| /// |
| /// See also: |
| /// |
| /// * [new BoxConstraints.tightFor], which is similar but instead of being |
| /// tight if the value is not infinite, is tight if the value is non-null. |
| const BoxConstraints.tightForFinite({ |
| double width = double.infinity, |
| double height = double.infinity, |
| }) : minWidth = width != double.infinity ? width : 0.0, |
| maxWidth = width != double.infinity ? width : double.infinity, |
| minHeight = height != double.infinity ? height : 0.0, |
| maxHeight = height != double.infinity ? height : double.infinity; |
| |
| /// Creates box constraints that forbid sizes larger than the given size. |
| BoxConstraints.loose(Size size) |
| : minWidth = 0.0, |
| maxWidth = size.width, |
| minHeight = 0.0, |
| maxHeight = size.height; |
| |
| /// Creates box constraints that expand to fill another box constraints. |
| /// |
| /// If width or height is given, the constraints will require exactly the |
| /// given value in the given dimension. |
| const BoxConstraints.expand({ |
| double width, |
| double height, |
| }) : minWidth = width ?? double.infinity, |
| maxWidth = width ?? double.infinity, |
| minHeight = height ?? double.infinity, |
| maxHeight = height ?? double.infinity; |
| |
| /// The minimum width that satisfies the constraints. |
| final double minWidth; |
| |
| /// The maximum width that satisfies the constraints. |
| /// |
| /// Might be [double.infinity]. |
| final double maxWidth; |
| |
| /// The minimum height that satisfies the constraints. |
| final double minHeight; |
| |
| /// The maximum height that satisfies the constraints. |
| /// |
| /// Might be [double.infinity]. |
| final double maxHeight; |
| |
| /// Creates a copy of this box constraints but with the given fields replaced with the new values. |
| BoxConstraints copyWith({ |
| double minWidth, |
| double maxWidth, |
| double minHeight, |
| double maxHeight, |
| }) { |
| return BoxConstraints( |
| minWidth: minWidth ?? this.minWidth, |
| maxWidth: maxWidth ?? this.maxWidth, |
| minHeight: minHeight ?? this.minHeight, |
| maxHeight: maxHeight ?? this.maxHeight, |
| ); |
| } |
| |
| /// Returns new box constraints that are smaller by the given edge dimensions. |
| BoxConstraints deflate(EdgeInsets edges) { |
| assert(edges != null); |
| assert(debugAssertIsValid()); |
| final double horizontal = edges.horizontal; |
| final double vertical = edges.vertical; |
| final double deflatedMinWidth = math.max(0.0, minWidth - horizontal); |
| final double deflatedMinHeight = math.max(0.0, minHeight - vertical); |
| return BoxConstraints( |
| minWidth: deflatedMinWidth, |
| maxWidth: math.max(deflatedMinWidth, maxWidth - horizontal), |
| minHeight: deflatedMinHeight, |
| maxHeight: math.max(deflatedMinHeight, maxHeight - vertical), |
| ); |
| } |
| |
| /// Returns new box constraints that remove the minimum width and height requirements. |
| BoxConstraints loosen() { |
| assert(debugAssertIsValid()); |
| return BoxConstraints( |
| minWidth: 0.0, |
| maxWidth: maxWidth, |
| minHeight: 0.0, |
| maxHeight: maxHeight, |
| ); |
| } |
| |
| /// Returns new box constraints that respect the given constraints while being |
| /// as close as possible to the original constraints. |
| BoxConstraints enforce(BoxConstraints constraints) { |
| return BoxConstraints( |
| minWidth: minWidth.clamp(constraints.minWidth, constraints.maxWidth) as double, |
| maxWidth: maxWidth.clamp(constraints.minWidth, constraints.maxWidth) as double, |
| minHeight: minHeight.clamp(constraints.minHeight, constraints.maxHeight) as double, |
| maxHeight: maxHeight.clamp(constraints.minHeight, constraints.maxHeight) as double, |
| ); |
| } |
| |
| /// Returns new box constraints with a tight width and/or height as close to |
| /// the given width and height as possible while still respecting the original |
| /// box constraints. |
| BoxConstraints tighten({ double width, double height }) { |
| return BoxConstraints( |
| minWidth: width == null ? minWidth : width.clamp(minWidth, maxWidth) as double, |
| maxWidth: width == null ? maxWidth : width.clamp(minWidth, maxWidth) as double, |
| minHeight: height == null ? minHeight : height.clamp(minHeight, maxHeight) as double, |
| maxHeight: height == null ? maxHeight : height.clamp(minHeight, maxHeight) as double, |
| ); |
| } |
| |
| /// A box constraints with the width and height constraints flipped. |
| BoxConstraints get flipped { |
| return BoxConstraints( |
| minWidth: minHeight, |
| maxWidth: maxHeight, |
| minHeight: minWidth, |
| maxHeight: maxWidth, |
| ); |
| } |
| |
| /// Returns box constraints with the same width constraints but with |
| /// unconstrained height. |
| BoxConstraints widthConstraints() => BoxConstraints(minWidth: minWidth, maxWidth: maxWidth); |
| |
| /// Returns box constraints with the same height constraints but with |
| /// unconstrained width |
| BoxConstraints heightConstraints() => BoxConstraints(minHeight: minHeight, maxHeight: maxHeight); |
| |
| /// Returns the width that both satisfies the constraints and is as close as |
| /// possible to the given width. |
| double constrainWidth([ double width = double.infinity ]) { |
| assert(debugAssertIsValid()); |
| return width.clamp(minWidth, maxWidth) as double; |
| } |
| |
| /// Returns the height that both satisfies the constraints and is as close as |
| /// possible to the given height. |
| double constrainHeight([ double height = double.infinity ]) { |
| assert(debugAssertIsValid()); |
| return height.clamp(minHeight, maxHeight) as double; |
| } |
| |
| Size _debugPropagateDebugSize(Size size, Size result) { |
| assert(() { |
| if (size is _DebugSize) |
| result = _DebugSize(result, size._owner, size._canBeUsedByParent); |
| return true; |
| }()); |
| return result; |
| } |
| |
| /// Returns the size that both satisfies the constraints and is as close as |
| /// possible to the given size. |
| /// |
| /// See also: |
| /// |
| /// * [constrainDimensions], which applies the same algorithm to |
| /// separately provided widths and heights. |
| Size constrain(Size size) { |
| Size result = Size(constrainWidth(size.width), constrainHeight(size.height)); |
| assert(() { |
| result = _debugPropagateDebugSize(size, result); |
| return true; |
| }()); |
| return result; |
| } |
| |
| /// Returns the size that both satisfies the constraints and is as close as |
| /// possible to the given width and height. |
| /// |
| /// When you already have a [Size], prefer [constrain], which applies the same |
| /// algorithm to a [Size] directly. |
| Size constrainDimensions(double width, double height) { |
| return Size(constrainWidth(width), constrainHeight(height)); |
| } |
| |
| /// Returns a size that attempts to meet the following conditions, in order: |
| /// |
| /// * The size must satisfy these constraints. |
| /// * The aspect ratio of the returned size matches the aspect ratio of the |
| /// given size. |
| /// * The returned size as big as possible while still being equal to or |
| /// smaller than the given size. |
| Size constrainSizeAndAttemptToPreserveAspectRatio(Size size) { |
| if (isTight) { |
| Size result = smallest; |
| assert(() { |
| result = _debugPropagateDebugSize(size, result); |
| return true; |
| }()); |
| return result; |
| } |
| |
| double width = size.width; |
| double height = size.height; |
| assert(width > 0.0); |
| assert(height > 0.0); |
| final double aspectRatio = width / height; |
| |
| if (width > maxWidth) { |
| width = maxWidth; |
| height = width / aspectRatio; |
| } |
| |
| if (height > maxHeight) { |
| height = maxHeight; |
| width = height * aspectRatio; |
| } |
| |
| if (width < minWidth) { |
| width = minWidth; |
| height = width / aspectRatio; |
| } |
| |
| if (height < minHeight) { |
| height = minHeight; |
| width = height * aspectRatio; |
| } |
| |
| Size result = Size(constrainWidth(width), constrainHeight(height)); |
| assert(() { |
| result = _debugPropagateDebugSize(size, result); |
| return true; |
| }()); |
| return result; |
| } |
| |
| /// The biggest size that satisfies the constraints. |
| Size get biggest => Size(constrainWidth(), constrainHeight()); |
| |
| /// The smallest size that satisfies the constraints. |
| Size get smallest => Size(constrainWidth(0.0), constrainHeight(0.0)); |
| |
| /// Whether there is exactly one width value that satisfies the constraints. |
| bool get hasTightWidth => minWidth >= maxWidth; |
| |
| /// Whether there is exactly one height value that satisfies the constraints. |
| bool get hasTightHeight => minHeight >= maxHeight; |
| |
| /// Whether there is exactly one size that satisfies the constraints. |
| @override |
| bool get isTight => hasTightWidth && hasTightHeight; |
| |
| /// Whether there is an upper bound on the maximum width. |
| /// |
| /// See also: |
| /// |
| /// * [hasBoundedHeight], the equivalent for the vertical axis. |
| /// * [hasInfiniteWidth], which describes whether the minimum width |
| /// constraint is infinite. |
| bool get hasBoundedWidth => maxWidth < double.infinity; |
| |
| /// Whether there is an upper bound on the maximum height. |
| /// |
| /// See also: |
| /// |
| /// * [hasBoundedWidth], the equivalent for the horizontal axis. |
| /// * [hasInfiniteHeight], which describes whether the minimum height |
| /// constraint is infinite. |
| bool get hasBoundedHeight => maxHeight < double.infinity; |
| |
| /// Whether the width constraint is infinite. |
| /// |
| /// Such a constraint is used to indicate that a box should grow as large as |
| /// some other constraint (in this case, horizontally). If constraints are |
| /// infinite, then they must have other (non-infinite) constraints [enforce]d |
| /// upon them, or must be [tighten]ed, before they can be used to derive a |
| /// [Size] for a [RenderBox.size]. |
| /// |
| /// See also: |
| /// |
| /// * [hasInfiniteHeight], the equivalent for the vertical axis. |
| /// * [hasBoundedWidth], which describes whether the maximum width |
| /// constraint is finite. |
| bool get hasInfiniteWidth => minWidth >= double.infinity; |
| |
| /// Whether the height constraint is infinite. |
| /// |
| /// Such a constraint is used to indicate that a box should grow as large as |
| /// some other constraint (in this case, vertically). If constraints are |
| /// infinite, then they must have other (non-infinite) constraints [enforce]d |
| /// upon them, or must be [tighten]ed, before they can be used to derive a |
| /// [Size] for a [RenderBox.size]. |
| /// |
| /// See also: |
| /// |
| /// * [hasInfiniteWidth], the equivalent for the horizontal axis. |
| /// * [hasBoundedHeight], which describes whether the maximum height |
| /// constraint is finite. |
| bool get hasInfiniteHeight => minHeight >= double.infinity; |
| |
| /// Whether the given size satisfies the constraints. |
| bool isSatisfiedBy(Size size) { |
| assert(debugAssertIsValid()); |
| return (minWidth <= size.width) && (size.width <= maxWidth) && |
| (minHeight <= size.height) && (size.height <= maxHeight); |
| } |
| |
| /// Scales each constraint parameter by the given factor. |
| BoxConstraints operator*(double factor) { |
| return BoxConstraints( |
| minWidth: minWidth * factor, |
| maxWidth: maxWidth * factor, |
| minHeight: minHeight * factor, |
| maxHeight: maxHeight * factor, |
| ); |
| } |
| |
| /// Scales each constraint parameter by the inverse of the given factor. |
| BoxConstraints operator/(double factor) { |
| return BoxConstraints( |
| minWidth: minWidth / factor, |
| maxWidth: maxWidth / factor, |
| minHeight: minHeight / factor, |
| maxHeight: maxHeight / factor, |
| ); |
| } |
| |
| /// Scales each constraint parameter by the inverse of the given factor, rounded to the nearest integer. |
| BoxConstraints operator~/(double factor) { |
| return BoxConstraints( |
| minWidth: (minWidth ~/ factor).toDouble(), |
| maxWidth: (maxWidth ~/ factor).toDouble(), |
| minHeight: (minHeight ~/ factor).toDouble(), |
| maxHeight: (maxHeight ~/ factor).toDouble(), |
| ); |
| } |
| |
| /// Computes the remainder of each constraint parameter by the given value. |
| BoxConstraints operator%(double value) { |
| return BoxConstraints( |
| minWidth: minWidth % value, |
| maxWidth: maxWidth % value, |
| minHeight: minHeight % value, |
| maxHeight: maxHeight % value, |
| ); |
| } |
| |
| /// Linearly interpolate between two BoxConstraints. |
| /// |
| /// If either is null, this function interpolates from a [BoxConstraints] |
| /// object whose fields are all set to 0.0. |
| /// |
| /// {@macro dart.ui.shadow.lerp} |
| static BoxConstraints lerp(BoxConstraints a, BoxConstraints b, double t) { |
| assert(t != null); |
| if (a == null && b == null) |
| return null; |
| if (a == null) |
| return b * t; |
| if (b == null) |
| return a * (1.0 - t); |
| assert(a.debugAssertIsValid()); |
| assert(b.debugAssertIsValid()); |
| assert((a.minWidth.isFinite && b.minWidth.isFinite) || (a.minWidth == double.infinity && b.minWidth == double.infinity), 'Cannot interpolate between finite constraints and unbounded constraints.'); |
| assert((a.maxWidth.isFinite && b.maxWidth.isFinite) || (a.maxWidth == double.infinity && b.maxWidth == double.infinity), 'Cannot interpolate between finite constraints and unbounded constraints.'); |
| assert((a.minHeight.isFinite && b.minHeight.isFinite) || (a.minHeight == double.infinity && b.minHeight == double.infinity), 'Cannot interpolate between finite constraints and unbounded constraints.'); |
| assert((a.maxHeight.isFinite && b.maxHeight.isFinite) || (a.maxHeight == double.infinity && b.maxHeight == double.infinity), 'Cannot interpolate between finite constraints and unbounded constraints.'); |
| return BoxConstraints( |
| minWidth: a.minWidth.isFinite ? ui.lerpDouble(a.minWidth, b.minWidth, t) : double.infinity, |
| maxWidth: a.maxWidth.isFinite ? ui.lerpDouble(a.maxWidth, b.maxWidth, t) : double.infinity, |
| minHeight: a.minHeight.isFinite ? ui.lerpDouble(a.minHeight, b.minHeight, t) : double.infinity, |
| maxHeight: a.maxHeight.isFinite ? ui.lerpDouble(a.maxHeight, b.maxHeight, t) : double.infinity, |
| ); |
| } |
| |
| /// Returns whether the object's constraints are normalized. |
| /// Constraints are normalized if the minimums are less than or |
| /// equal to the corresponding maximums. |
| /// |
| /// For example, a BoxConstraints object with a minWidth of 100.0 |
| /// and a maxWidth of 90.0 is not normalized. |
| /// |
| /// Most of the APIs on BoxConstraints expect the constraints to be |
| /// normalized and have undefined behavior when they are not. In |
| /// checked mode, many of these APIs will assert if the constraints |
| /// are not normalized. |
| @override |
| bool get isNormalized { |
| return minWidth >= 0.0 && |
| minWidth <= maxWidth && |
| minHeight >= 0.0 && |
| minHeight <= maxHeight; |
| } |
| |
| @override |
| bool debugAssertIsValid({ |
| bool isAppliedConstraint = false, |
| InformationCollector informationCollector, |
| }) { |
| assert(() { |
| void throwError(DiagnosticsNode message) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| message, |
| if (informationCollector != null) ...informationCollector(), |
| DiagnosticsProperty<BoxConstraints>('The offending constraints were', this, style: DiagnosticsTreeStyle.errorProperty), |
| ]); |
| } |
| if (minWidth.isNaN || maxWidth.isNaN || minHeight.isNaN || maxHeight.isNaN) { |
| final List<String> affectedFieldsList = <String>[ |
| if (minWidth.isNaN) 'minWidth', |
| if (maxWidth.isNaN) 'maxWidth', |
| if (minHeight.isNaN) 'minHeight', |
| if (maxHeight.isNaN) 'maxHeight', |
| ]; |
| assert(affectedFieldsList.isNotEmpty); |
| if (affectedFieldsList.length > 1) |
| affectedFieldsList.add('and ${affectedFieldsList.removeLast()}'); |
| String whichFields = ''; |
| if (affectedFieldsList.length > 2) { |
| whichFields = affectedFieldsList.join(', '); |
| } else if (affectedFieldsList.length == 2) { |
| whichFields = affectedFieldsList.join(' '); |
| } else { |
| whichFields = affectedFieldsList.single; |
| } |
| throwError(ErrorSummary('BoxConstraints has ${affectedFieldsList.length == 1 ? 'a NaN value' : 'NaN values' } in $whichFields.')); |
| } |
| if (minWidth < 0.0 && minHeight < 0.0) |
| throwError(ErrorSummary('BoxConstraints has both a negative minimum width and a negative minimum height.')); |
| if (minWidth < 0.0) |
| throwError(ErrorSummary('BoxConstraints has a negative minimum width.')); |
| if (minHeight < 0.0) |
| throwError(ErrorSummary('BoxConstraints has a negative minimum height.')); |
| if (maxWidth < minWidth && maxHeight < minHeight) |
| throwError(ErrorSummary('BoxConstraints has both width and height constraints non-normalized.')); |
| if (maxWidth < minWidth) |
| throwError(ErrorSummary('BoxConstraints has non-normalized width constraints.')); |
| if (maxHeight < minHeight) |
| throwError(ErrorSummary('BoxConstraints has non-normalized height constraints.')); |
| if (isAppliedConstraint) { |
| if (minWidth.isInfinite && minHeight.isInfinite) |
| throwError(ErrorSummary('BoxConstraints forces an infinite width and infinite height.')); |
| if (minWidth.isInfinite) |
| throwError(ErrorSummary('BoxConstraints forces an infinite width.')); |
| if (minHeight.isInfinite) |
| throwError(ErrorSummary('BoxConstraints forces an infinite height.')); |
| } |
| assert(isNormalized); |
| return true; |
| }()); |
| return isNormalized; |
| } |
| |
| /// Returns a box constraints that [isNormalized]. |
| /// |
| /// The returned [maxWidth] is at least as large as the [minWidth]. Similarly, |
| /// the returned [maxHeight] is at least as large as the [minHeight]. |
| BoxConstraints normalize() { |
| if (isNormalized) |
| return this; |
| final double minWidth = this.minWidth >= 0.0 ? this.minWidth : 0.0; |
| final double minHeight = this.minHeight >= 0.0 ? this.minHeight : 0.0; |
| return BoxConstraints( |
| minWidth: minWidth, |
| maxWidth: minWidth > maxWidth ? minWidth : maxWidth, |
| minHeight: minHeight, |
| maxHeight: minHeight > maxHeight ? minHeight : maxHeight, |
| ); |
| } |
| |
| @override |
| bool operator ==(Object other) { |
| assert(debugAssertIsValid()); |
| if (identical(this, other)) |
| return true; |
| if (other.runtimeType != runtimeType) |
| return false; |
| assert(other is BoxConstraints && other.debugAssertIsValid()); |
| return other is BoxConstraints |
| && other.minWidth == minWidth |
| && other.maxWidth == maxWidth |
| && other.minHeight == minHeight |
| && other.maxHeight == maxHeight; |
| } |
| |
| @override |
| int get hashCode { |
| assert(debugAssertIsValid()); |
| return hashValues(minWidth, maxWidth, minHeight, maxHeight); |
| } |
| |
| @override |
| String toString() { |
| final String annotation = isNormalized ? '' : '; NOT NORMALIZED'; |
| if (minWidth == double.infinity && minHeight == double.infinity) |
| return 'BoxConstraints(biggest$annotation)'; |
| if (minWidth == 0 && maxWidth == double.infinity && |
| minHeight == 0 && maxHeight == double.infinity) |
| return 'BoxConstraints(unconstrained$annotation)'; |
| String describe(double min, double max, String dim) { |
| if (min == max) |
| return '$dim=${min.toStringAsFixed(1)}'; |
| return '${min.toStringAsFixed(1)}<=$dim<=${max.toStringAsFixed(1)}'; |
| } |
| final String width = describe(minWidth, maxWidth, 'w'); |
| final String height = describe(minHeight, maxHeight, 'h'); |
| return 'BoxConstraints($width, $height$annotation)'; |
| } |
| } |
| |
| /// Method signature for hit testing a [RenderBox]. |
| /// |
| /// Used by [BoxHitTestResult.addWithPaintTransform] to hit test children |
| /// of a [RenderBox]. |
| /// |
| /// See also: |
| /// |
| /// * [RenderBox.hitTest], which documents more details around hit testing |
| /// [RenderBox]es. |
| typedef BoxHitTest = bool Function(BoxHitTestResult result, Offset position); |
| |
| /// The result of performing a hit test on [RenderBox]es. |
| /// |
| /// An instance of this class is provided to [RenderBox.hitTest] to record the |
| /// result of the hit test. |
| class BoxHitTestResult extends HitTestResult { |
| /// Creates an empty hit test result for hit testing on [RenderBox]. |
| BoxHitTestResult() : super(); |
| |
| /// Wraps `result` to create a [HitTestResult] that implements the |
| /// [BoxHitTestResult] protocol for hit testing on [RenderBox]es. |
| /// |
| /// This method is used by [RenderObject]s that adapt between the |
| /// [RenderBox]-world and the non-[RenderBox]-world to convert a (subtype of) |
| /// [HitTestResult] to a [BoxHitTestResult] for hit testing on [RenderBox]es. |
| /// |
| /// The [HitTestEntry] instances added to the returned [BoxHitTestResult] are |
| /// also added to the wrapped `result` (both share the same underlying data |
| /// structure to store [HitTestEntry] instances). |
| /// |
| /// See also: |
| /// |
| /// * [HitTestResult.wrap], which turns a [BoxHitTestResult] back into a |
| /// generic [HitTestResult]. |
| /// * [SliverHitTestResult.wrap], which turns a [BoxHitTestResult] into a |
| /// [SliverHitTestResult] for hit testing on [RenderSliver] children. |
| BoxHitTestResult.wrap(HitTestResult result) : super.wrap(result); |
| |
| /// Transforms `position` to the local coordinate system of a child for |
| /// hit-testing the child. |
| /// |
| /// The actual hit testing of the child needs to be implemented in the |
| /// provided `hitTest` callback, which is invoked with the transformed |
| /// `position` as argument. |
| /// |
| /// The provided paint `transform` (which describes the transform from the |
| /// child to the parent in 3D) is processed by |
| /// [PointerEvent.removePerspectiveTransform] to remove the |
| /// perspective component and inverted before it is used to transform |
| /// `position` from the coordinate system of the parent to the system of the |
| /// child. |
| /// |
| /// If `transform` is null it will be treated as the identity transform and |
| /// `position` is provided to the `hitTest` callback as-is. If `transform` |
| /// cannot be inverted, the `hitTest` callback is not invoked and false is |
| /// returned. Otherwise, the return value of the `hitTest` callback is |
| /// returned. |
| /// |
| /// The `position` argument may be null, which will be forwarded to the |
| /// `hitTest` callback as-is. Using null as the position can be useful if |
| /// the child speaks a different hit test protocol then the parent and the |
| /// position is not required to do the actual hit testing in that protocol. |
| /// |
| /// {@tool snippet} |
| /// This method is used in [RenderBox.hitTestChildren] when the child and |
| /// parent don't share the same origin. |
| /// |
| /// ```dart |
| /// abstract class Foo extends RenderBox { |
| /// |
| /// final Matrix4 _effectiveTransform = Matrix4.rotationZ(50); |
| /// |
| /// @override |
| /// void applyPaintTransform(RenderBox child, Matrix4 transform) { |
| /// transform.multiply(_effectiveTransform); |
| /// } |
| /// |
| /// @override |
| /// bool hitTestChildren(BoxHitTestResult result, { Offset position }) { |
| /// return result.addWithPaintTransform( |
| /// transform: _effectiveTransform, |
| /// position: position, |
| /// hitTest: (BoxHitTestResult result, Offset position) { |
| /// return super.hitTestChildren(result, position: position); |
| /// }, |
| /// ); |
| /// } |
| /// } |
| /// ``` |
| /// {@end-tool} |
| /// |
| /// See also: |
| /// |
| /// * [addWithPaintOffset], which can be used for `transform`s that are just |
| /// simple matrix translations by an [Offset]. |
| /// * [addWithRawTransform], which takes a transform matrix that is directly |
| /// used to transform the position without any pre-processing. |
| bool addWithPaintTransform({ |
| @required Matrix4 transform, |
| @required Offset position, |
| @required BoxHitTest hitTest, |
| }) { |
| assert(hitTest != null); |
| if (transform != null) { |
| transform = Matrix4.tryInvert(PointerEvent.removePerspectiveTransform(transform)); |
| if (transform == null) { |
| // Objects are not visible on screen and cannot be hit-tested. |
| return false; |
| } |
| } |
| return addWithRawTransform( |
| transform: transform, |
| position: position, |
| hitTest: hitTest, |
| ); |
| } |
| |
| /// Convenience method for hit testing children, that are translated by |
| /// an [Offset]. |
| /// |
| /// The actual hit testing of the child needs to be implemented in the |
| /// provided `hitTest` callback, which is invoked with the transformed |
| /// `position` as argument. |
| /// |
| /// This method can be used as a convenience over [addWithPaintTransform] if |
| /// a parent paints a child at an `offset`. |
| /// |
| /// A null value for `offset` is treated as if [Offset.zero] was provided. |
| /// |
| /// Se also: |
| /// |
| /// * [addWithPaintTransform], which takes a generic paint transform matrix and |
| /// documents the intended usage of this API in more detail. |
| bool addWithPaintOffset({ |
| @required Offset offset, |
| @required Offset position, |
| @required BoxHitTest hitTest, |
| }) { |
| assert(hitTest != null); |
| return addWithRawTransform( |
| transform: offset != null ? Matrix4.translationValues(-offset.dx, -offset.dy, 0.0) : null, |
| position: position, |
| hitTest: hitTest, |
| ); |
| } |
| |
| /// Transforms `position` to the local coordinate system of a child for |
| /// hit-testing the child. |
| /// |
| /// The actual hit testing of the child needs to be implemented in the |
| /// provided `hitTest` callback, which is invoked with the transformed |
| /// `position` as argument. |
| /// |
| /// Unlike [addWithPaintTransform], the provided `transform` matrix is used |
| /// directly to transform `position` without any pre-processing. |
| /// |
| /// If `transform` is null it will be treated as the identity transform ad |
| /// `position` is provided to the `hitTest` callback as-is. |
| /// |
| /// The function returns the return value of the `hitTest` callback. |
| /// |
| /// The `position` argument may be null, which will be forwarded to the |
| /// `hitTest` callback as-is. Using null as the position can be useful if |
| /// the child speaks a different hit test protocol then the parent and the |
| /// position is not required to do the actual hit testing in that protocol. |
| /// |
| /// Se also: |
| /// |
| /// * [addWithPaintTransform], which accomplishes the same thing, but takes a |
| /// _paint_ transform matrix. |
| bool addWithRawTransform({ |
| @required Matrix4 transform, |
| @required Offset position, |
| @required BoxHitTest hitTest, |
| }) { |
| assert(hitTest != null); |
| final Offset transformedPosition = position == null || transform == null |
| ? position |
| : MatrixUtils.transformPoint(transform, position); |
| if (transform != null) { |
| pushTransform(transform); |
| } |
| final bool isHit = hitTest(this, transformedPosition); |
| if (transform != null) { |
| popTransform(); |
| } |
| return isHit; |
| } |
| } |
| |
| /// A hit test entry used by [RenderBox]. |
| class BoxHitTestEntry extends HitTestEntry { |
| /// Creates a box hit test entry. |
| /// |
| /// The [localPosition] argument must not be null. |
| BoxHitTestEntry(RenderBox target, this.localPosition) |
| : assert(localPosition != null), |
| super(target); |
| |
| @override |
| RenderBox get target => super.target as RenderBox; |
| |
| /// The position of the hit test in the local coordinates of [target]. |
| final Offset localPosition; |
| |
| @override |
| String toString() => '${describeIdentity(target)}@$localPosition'; |
| } |
| |
| /// Parent data used by [RenderBox] and its subclasses. |
| class BoxParentData extends ParentData { |
| /// The offset at which to paint the child in the parent's coordinate system. |
| Offset offset = Offset.zero; |
| |
| @override |
| String toString() => 'offset=$offset'; |
| } |
| |
| /// Abstract [ParentData] subclass for [RenderBox] subclasses that want the |
| /// [ContainerRenderObjectMixin]. |
| /// |
| /// This is a convenience class that mixes in the relevant classes with |
| /// the relevant type arguments. |
| abstract class ContainerBoxParentData<ChildType extends RenderObject> extends BoxParentData with ContainerParentDataMixin<ChildType> { } |
| |
| enum _IntrinsicDimension { minWidth, maxWidth, minHeight, maxHeight } |
| |
| @immutable |
| class _IntrinsicDimensionsCacheEntry { |
| const _IntrinsicDimensionsCacheEntry(this.dimension, this.argument); |
| |
| final _IntrinsicDimension dimension; |
| final double argument; |
| |
| @override |
| bool operator ==(Object other) { |
| return other is _IntrinsicDimensionsCacheEntry |
| && other.dimension == dimension |
| && other.argument == argument; |
| } |
| |
| @override |
| int get hashCode => hashValues(dimension, argument); |
| } |
| |
| /// 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 own coordinate system in which its upper left corner is placed at (0, |
| /// 0). The lower right corner of the box is therefore at (width, height). The |
| /// box contains all the points including the upper left corner and extending |
| /// to, but not including, the lower right corner. |
| /// |
| /// Box layout is performed by passing a [BoxConstraints] object down the tree. |
| /// The box constraints establish a min and max value for the child's width and |
| /// height. In determining its size, the child must respect the constraints |
| /// given to it by its parent. |
| /// |
| /// This protocol is sufficient for expressing a number of common box layout |
| /// data flows. For example, to implement a width-in-height-out data flow, call |
| /// your child's [layout] function with a set of box constraints with a tight |
| /// width value (and pass true for parentUsesSize). After the child determines |
| /// its height, use the child's height to determine your size. |
| /// |
| /// ## Writing a RenderBox subclass |
| /// |
| /// One would implement a new [RenderBox] subclass to describe a new layout |
| /// model, new paint model, new hit-testing model, or new semantics model, while |
| /// remaining in the Cartesian space defined by the [RenderBox] protocol. |
| /// |
| /// To create a new protocol, consider subclassing [RenderObject] instead. |
| /// |
| /// ### Constructors and properties of a new RenderBox subclass |
| /// |
| /// The constructor will typically take a named argument for each property of |
| /// the class. The value is then passed to a private field of the class and the |
| /// constructor asserts its correctness (e.g. if it should not be null, it |
| /// asserts it's not null). |
| /// |
| /// Properties have the form of a getter/setter/field group like the following: |
| /// |
| /// ```dart |
| /// AxisDirection get axis => _axis; |
| /// AxisDirection _axis; |
| /// set axis(AxisDirection value) { |
| /// assert(value != null); // same check as in the constructor |
| /// if (value == _axis) |
| /// return; |
| /// _axis = value; |
| /// markNeedsLayout(); |
| /// } |
| /// ``` |
| /// |
| /// The setter will typically finish with either a call to [markNeedsLayout], if |
| /// the layout uses this property, or [markNeedsPaint], if only the painter |
| /// function does. (No need to call both, [markNeedsLayout] implies |
| /// [markNeedsPaint].) |
| /// |
| /// Consider layout and paint to be expensive; be conservative about calling |
| /// [markNeedsLayout] or [markNeedsPaint]. They should only be called if the |
| /// layout (or paint, respectively) has actually changed. |
| /// |
| /// ### Children |
| /// |
| /// If a render object is a leaf, that is, it cannot have any children, then |
| /// ignore this section. (Examples of leaf render objects are [RenderImage] and |
| /// [RenderParagraph].) |
| /// |
| /// For render objects with children, there are four possible scenarios: |
| /// |
| /// * A single [RenderBox] child. In this scenario, consider inheriting from |
| /// [RenderProxyBox] (if the render object sizes itself to match the child) or |
| /// [RenderShiftedBox] (if the child will be smaller than the box and the box |
| /// will align the child inside itself). |
| /// |
| /// * A single child, but it isn't a [RenderBox]. Use the |
| /// [RenderObjectWithChildMixin] mixin. |
| /// |
| /// * A single list of children. Use the [ContainerRenderObjectMixin] mixin. |
| /// |
| /// * A more complicated child model. |
| /// |
| /// #### Using RenderProxyBox |
| /// |
| /// By default, a [RenderProxyBox] render object sizes itself to fit its child, or |
| /// to be as small as possible if there is no child; it passes all hit testing |
| /// and painting on to the child, and intrinsic dimensions and baseline |
| /// measurements similarly are proxied to the child. |
| /// |
| /// A subclass of [RenderProxyBox] just needs to override the parts of the |
| /// [RenderBox] protocol that matter. For example, [RenderOpacity] just |
| /// overrides the paint method (and [alwaysNeedsCompositing] to reflect what the |
| /// paint method does, and the [visitChildrenForSemantics] method so that the |
| /// child is hidden from accessibility tools when it's invisible), and adds an |
| /// [RenderOpacity.opacity] field. |
| /// |
| /// [RenderProxyBox] assumes that the child is the size of the parent and |
| /// positioned at 0,0. If this is not true, then use [RenderShiftedBox] instead. |
| /// |
| /// See |
| /// [proxy_box.dart](https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/rendering/proxy_box.dart) |
| /// for examples of inheriting from [RenderProxyBox]. |
| /// |
| /// #### Using RenderShiftedBox |
| /// |
| /// By default, a [RenderShiftedBox] acts much like a [RenderProxyBox] but |
| /// without assuming that the child is positioned at 0,0 (the actual position |
| /// recorded in the child's [parentData] field is used), and without providing a |
| /// default layout algorithm. |
| /// |
| /// See |
| /// [shifted_box.dart](https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/rendering/shifted_box.dart) |
| /// for examples of inheriting from [RenderShiftedBox]. |
| /// |
| /// #### Kinds of children and child-specific data |
| /// |
| /// A [RenderBox] doesn't have to have [RenderBox] children. One can use another |
| /// subclass of [RenderObject] for a [RenderBox]'s children. See the discussion |
| /// at [RenderObject]. |
| /// |
| /// Children can have additional data owned by the parent but stored on the |
| /// child using the [parentData] field. The class used for that data must |
| /// inherit from [ParentData]. The [setupParentData] method is used to |
| /// initialize the [parentData] field of a child when the child is attached. |
| /// |
| /// By convention, [RenderBox] objects that have [RenderBox] children use the |
| /// [BoxParentData] class, which has a [BoxParentData.offset] field to store the |
| /// position of the child relative to the parent. ([RenderProxyBox] does not |
| /// need this offset and therefore is an exception to this rule.) |
| /// |
| /// #### Using RenderObjectWithChildMixin |
| /// |
| /// If a render object has a single child but it isn't a [RenderBox], then the |
| /// [RenderObjectWithChildMixin] class, which is a mixin that will handle the |
| /// boilerplate of managing a child, will be useful. |
| /// |
| /// It's a generic class with one type argument, the type of the child. For |
| /// example, if you are building a `RenderFoo` class which takes a single |
| /// `RenderBar` child, you would use the mixin as follows: |
| /// |
| /// ```dart |
| /// class RenderFoo extends RenderBox |
| /// with RenderObjectWithChildMixin<RenderBar> { |
| /// // ... |
| /// } |
| /// ``` |
| /// |
| /// Since the `RenderFoo` class itself is still a [RenderBox] in this case, you |
| /// still have to implement the [RenderBox] layout algorithm, as well as |
| /// features like intrinsics and baselines, painting, and hit testing. |
| /// |
| /// #### Using ContainerRenderObjectMixin |
| /// |
| /// If a render box can have multiple children, then the |
| /// [ContainerRenderObjectMixin] mixin can be used to handle the boilerplate. It |
| /// uses a linked list to model the children in a manner that is easy to mutate |
| /// dynamically and that can be walked efficiently. Random access is not |
| /// efficient in this model; if you need random access to the children consider |
| /// the next section on more complicated child models. |
| /// |
| /// The [ContainerRenderObjectMixin] class has two type arguments. The first is |
| /// the type of the child objects. The second is the type for their |
| /// [parentData]. The class used for [parentData] must itself have the |
| /// [ContainerParentDataMixin] class mixed into it; this is where |
| /// [ContainerRenderObjectMixin] stores the linked list. A [ParentData] class |
| /// can extend [ContainerBoxParentData]; this is essentially |
| /// [BoxParentData] mixed with [ContainerParentDataMixin]. For example, if a |
| /// `RenderFoo` class wanted to have a linked list of [RenderBox] children, one |
| /// might create a `FooParentData` class as follows: |
| /// |
| /// ```dart |
| /// class FooParentData extends ContainerBoxParentData<RenderBox> { |
| /// // (any fields you might need for these children) |
| /// } |
| /// ``` |
| /// |
| /// When using [ContainerRenderObjectMixin] in a [RenderBox], consider mixing in |
| /// [RenderBoxContainerDefaultsMixin], which provides a collection of utility |
| /// methods that implement common parts of the [RenderBox] protocol (such as |
| /// painting the children). |
| /// |
| /// The declaration of the `RenderFoo` class itself would thus look like this: |
| /// |
| /// ```dart |
| /// class RenderFoo extends RenderBox with |
| /// ContainerRenderObjectMixin<RenderBox, FooParentData>, |
| /// RenderBoxContainerDefaultsMixin<RenderBox, FooParentData> { |
| /// // ... |
| /// } |
| /// ``` |
| /// |
| /// When walking the children (e.g. during layout), the following pattern is |
| /// commonly used (in this case assuming that the children are all [RenderBox] |
| /// objects and that this render object uses `FooParentData` objects for its |
| /// children's [parentData] fields): |
| /// |
| /// ```dart |
| /// RenderBox child = firstChild; |
| /// while (child != null) { |
| /// final FooParentData childParentData = child.parentData; |
| /// // ...operate on child and childParentData... |
| /// assert(child.parentData == childParentData); |
| /// child = childParentData.nextSibling; |
| /// } |
| /// ``` |
| /// |
| /// #### More complicated child models |
| /// |
| /// Render objects can have more complicated models, for example a map of |
| /// children keyed on an enum, or a 2D grid of efficiently randomly-accessible |
| /// children, or multiple lists of children, etc. If a render object has a model |
| /// that can't be handled by the mixins above, it must implement the |
| /// [RenderObject] child protocol, as follows: |
| /// |
| /// * Any time a child is removed, call [dropChild] with the child. |
| /// |
| /// * Any time a child is added, call [adoptChild] with the child. |
| /// |
| /// * Implement the [attach] method such that it calls [attach] on each child. |
| /// |
| /// * Implement the [detach] method such that it calls [detach] on each child. |
| /// |
| /// * Implement the [redepthChildren] method such that it calls [redepthChild] |
| /// on each child. |
| /// |
| /// * Implement the [visitChildren] method such that it calls its argument for |
| /// each child, typically in paint order (back-most to front-most). |
| /// |
| /// * Implement [debugDescribeChildren] such that it outputs a [DiagnosticsNode] |
| /// for each child. |
| /// |
| /// Implementing these seven bullet points is essentially all that the two |
| /// aforementioned mixins do. |
| /// |
| /// ### Layout |
| /// |
| /// [RenderBox] classes implement a layout algorithm. They have a set of |
| /// constraints provided to them, and they size themselves based on those |
| /// constraints and whatever other inputs they may have (for example, their |
| /// children or properties). |
| /// |
| /// When implementing a [RenderBox] subclass, one must make a choice. Does it |
| /// size itself exclusively based on the constraints, or does it use any other |
| /// information in sizing itself? An example of sizing purely based on the |
| /// constraints would be growing to fit the parent. |
| /// |
| /// Sizing purely based on the constraints allows the system to make some |
| /// significant optimizations. Classes that use this approach should override |
| /// [sizedByParent] to return true, and then override [performResize] to set the |
| /// [size] using nothing but the constraints, e.g.: |
| /// |
| /// ```dart |
| /// @override |
| /// bool get sizedByParent => true; |
| /// |
| /// @override |
| /// void performResize() { |
| /// size = constraints.smallest; |
| /// } |
| /// ``` |
| /// |
| /// Otherwise, the size is set in the [performLayout] function. |
| /// |
| /// The [performLayout] function is where render boxes decide, if they are not |
| /// [sizedByParent], what [size] they should be, and also where they decide |
| /// where their children should be. |
| /// |
| /// #### Layout of RenderBox children |
| /// |
| /// The [performLayout] function should call the [layout] function of each (box) |
| /// child, passing it a [BoxConstraints] object describing the constraints |
| /// within which the child can render. Passing tight constraints (see |
| /// [BoxConstraints.isTight]) to the child will allow the rendering library to |
| /// apply some optimizations, as it knows that if the constraints are tight, the |
| /// child's dimensions cannot change even if the layout of the child itself |
| /// changes. |
| /// |
| /// If the [performLayout] function will use the child's size to affect other |
| /// aspects of the layout, for example if the render box sizes itself around the |
| /// child, or positions several children based on the size of those children, |
| /// then it must specify the `parentUsesSize` argument to the child's [layout] |
| /// function, setting it to true. |
| /// |
| /// This flag turns off some optimizations; algorithms that do not rely on the |
| /// children's sizes will be more efficient. (In particular, relying on the |
| /// child's [size] means that if the child is marked dirty for layout, the |
| /// parent will probably also be marked dirty for layout, unless the |
| /// [constraints] given by the parent to the child were tight constraints.) |
| /// |
| /// For [RenderBox] classes that do not inherit from [RenderProxyBox], once they |
| /// have laid out their children, they should also position them, by setting the |
| /// [BoxParentData.offset] field of each child's [parentData] object. |
| /// |
| /// #### Layout of non-RenderBox children |
| /// |
| /// The children of a [RenderBox] do not have to be [RenderBox]es themselves. If |
| /// they use another protocol (as discussed at [RenderObject]), then instead of |
| /// [BoxConstraints], the parent would pass in the appropriate [Constraints] |
| /// subclass, and instead of reading the child's size, the parent would read |
| /// whatever the output of [layout] is for that layout protocol. The |
| /// `parentUsesSize` flag is still used to indicate whether the parent is going |
| /// to read that output, and optimizations still kick in if the child has tight |
| /// constraints (as defined by [Constraints.isTight]). |
| /// |
| /// ### Painting |
| /// |
| /// To describe how a render box paints, implement the [paint] method. It is |
| /// given a [PaintingContext] object and an [Offset]. The painting context |
| /// provides methods to affect the layer tree as well as a |
| /// [PaintingContext.canvas] which can be used to add drawing commands. The |
| /// canvas object should not be cached across calls to the [PaintingContext]'s |
| /// methods; every time a method on [PaintingContext] is called, there is a |
| /// chance that the canvas will change identity. The offset specifies the |
| /// position of the top left corner of the box in the coordinate system of the |
| /// [PaintingContext.canvas]. |
| /// |
| /// To draw text on a canvas, use a [TextPainter]. |
| /// |
| /// To draw an image to a canvas, use the [paintImage] method. |
| /// |
| /// A [RenderBox] that uses methods on [PaintingContext] that introduce new |
| /// layers should override the [alwaysNeedsCompositing] getter and set it to |
| /// true. If the object sometimes does and sometimes does not, it can have that |
| /// getter return true in some cases and false in others. In that case, whenever |
| /// the return value would change, call [markNeedsCompositingBitsUpdate]. (This |
| /// is done automatically when a child is added or removed, so you don't have to |
| /// call it explicitly if the [alwaysNeedsCompositing] getter only changes value |
| /// based on the presence or absence of children.) |
| /// |
| /// Anytime anything changes on the object that would cause the [paint] method |
| /// to paint something different (but would not cause the layout to change), |
| /// the object should call [markNeedsPaint]. |
| /// |
| /// #### Painting children |
| /// |
| /// The [paint] method's `context` argument has a [PaintingContext.paintChild] |
| /// method, which should be called for each child that is to be painted. It |
| /// should be given a reference to the child, and an [Offset] giving the |
| /// position of the child relative to the parent. |
| /// |
| /// If the [paint] method applies a transform to the painting context before |
| /// painting children (or generally applies an additional offset beyond the |
| /// offset it was itself given as an argument), then the [applyPaintTransform] |
| /// method should also be overridden. That method must adjust the matrix that it |
| /// is given in the same manner as it transformed the painting context and |
| /// offset before painting the given child. This is used by the [globalToLocal] |
| /// and [localToGlobal] methods. |
| /// |
| /// #### Hit Tests |
| /// |
| /// Hit testing for render boxes is implemented by the [hitTest] method. The |
| /// default implementation of this method defers to [hitTestSelf] and |
| /// [hitTestChildren]. When implementing hit testing, you can either override |
| /// these latter two methods, or ignore them and just override [hitTest]. |
| /// |
| /// The [hitTest] method itself is given an [Offset], and must return true if the |
| /// object or one of its children has absorbed the hit (preventing objects below |
| /// this one from being hit), or false if the hit can continue to other objects |
| /// below this one. |
| /// |
| /// For each child [RenderBox], the [hitTest] method on the child should be |
| /// called with the same [HitTestResult] argument and with the point transformed |
| /// into the child's coordinate space (in the same manner that the |
| /// [applyPaintTransform] method would). The default implementation defers to |
| /// [hitTestChildren] to call the children. [RenderBoxContainerDefaultsMixin] |
| /// provides a [RenderBoxContainerDefaultsMixin.defaultHitTestChildren] method |
| /// that does this assuming that the children are axis-aligned, not transformed, |
| /// and positioned according to the [BoxParentData.offset] field of the |
| /// [parentData]; more elaborate boxes can override [hitTestChildren] |
| /// accordingly. |
| /// |
| /// If the object is hit, then it should also add itself to the [HitTestResult] |
| /// object that is given as an argument to the [hitTest] method, using |
| /// [HitTestResult.add]. The default implementation defers to [hitTestSelf] to |
| /// determine if the box is hit. If the object adds itself before the children |
| /// can add themselves, then it will be as if the object was above the children. |
| /// If it adds itself after the children, then it will be as if it was below the |
| /// children. Entries added to the [HitTestResult] object should use the |
| /// [BoxHitTestEntry] class. The entries are subsequently walked by the system |
| /// in the order they were added, and for each entry, the target's [handleEvent] |
| /// method is called, passing in the [HitTestEntry] object. |
| /// |
| /// Hit testing cannot rely on painting having happened. |
| /// |
| /// ### Semantics |
| /// |
| /// For a render box to be accessible, implement the |
| /// [describeApproximatePaintClip] and [visitChildrenForSemantics] methods, and |
| /// the [semanticsAnnotator] getter. The default implementations are sufficient |
| /// for objects that only affect layout, but nodes that represent interactive |
| /// components or information (diagrams, text, images, etc) should provide more |
| /// complete implementations. For more information, see the documentation for |
| /// these members. |
| /// |
| /// ### Intrinsics and Baselines |
| /// |
| /// The layout, painting, hit testing, and semantics protocols are common to all |
| /// render objects. [RenderBox] objects must implement two additional protocols: |
| /// intrinsic sizing and baseline measurements. |
| /// |
| /// There are four methods to implement for intrinsic sizing, to compute the |
| /// minimum and maximum intrinsic width and height of the box. The documentation |
| /// for these methods discusses the protocol in detail: |
| /// [computeMinIntrinsicWidth], [computeMaxIntrinsicWidth], |
| /// [computeMinIntrinsicHeight], [computeMaxIntrinsicHeight]. |
| /// |
| /// In addition, if the box has any children, it must implement |
| /// [computeDistanceToActualBaseline]. [RenderProxyBox] provides a simple |
| /// implementation that forwards to the child; [RenderShiftedBox] provides an |
| /// implementation that offsets the child's baseline information by the position |
| /// of the child relative to the parent. If you do not inherited from either of |
| /// these classes, however, you must implement the algorithm yourself. |
| abstract class RenderBox extends RenderObject { |
| @override |
| void setupParentData(covariant RenderObject child) { |
| if (child.parentData is! BoxParentData) |
| child.parentData = BoxParentData(); |
| } |
| |
| Map<_IntrinsicDimensionsCacheEntry, double> _cachedIntrinsicDimensions; |
| |
| double _computeIntrinsicDimension(_IntrinsicDimension dimension, double argument, double computer(double argument)) { |
| assert(RenderObject.debugCheckingIntrinsics || !debugDoingThisResize); // performResize should not depend on anything except the incoming constraints |
| bool shouldCache = true; |
| assert(() { |
| // we don't want the checked-mode intrinsic tests to affect |
| // who gets marked dirty, etc. |
| if (RenderObject.debugCheckingIntrinsics) |
| shouldCache = false; |
| return true; |
| }()); |
| if (shouldCache) { |
| _cachedIntrinsicDimensions ??= <_IntrinsicDimensionsCacheEntry, double>{}; |
| return _cachedIntrinsicDimensions.putIfAbsent( |
| _IntrinsicDimensionsCacheEntry(dimension, argument), |
| () => computer(argument), |
| ); |
| } |
| return computer(argument); |
| } |
| |
| /// Returns the minimum width that this box could be without failing to |
| /// correctly paint its contents within itself, without clipping. |
| /// |
| /// The height argument may give a specific height to assume. The given height |
| /// can be infinite, meaning that the intrinsic width in an unconstrained |
| /// environment is being requested. The given height should never be negative |
| /// or null. |
| /// |
| /// This function should only be called on one's children. Calling this |
| /// function couples the child with the parent so that when the child's layout |
| /// changes, the parent is notified (via [markNeedsLayout]). |
| /// |
| /// Calling this function is expensive as it can result in O(N^2) behavior. |
| /// |
| /// Do not override this method. Instead, implement [computeMinIntrinsicWidth]. |
| @mustCallSuper |
| double getMinIntrinsicWidth(double height) { |
| assert(() { |
| if (height == null) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The height argument to getMinIntrinsicWidth was null.'), |
| ErrorDescription('The argument to getMinIntrinsicWidth must not be negative or null.'), |
| ErrorHint('If you do not have a specific height in mind, then pass double.infinity instead.'), |
| ]); |
| } |
| if (height < 0.0) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The height argument to getMinIntrinsicWidth was negative.'), |
| ErrorDescription('The argument to getMinIntrinsicWidth must not be negative or null.'), |
| ErrorHint( |
| 'If you perform computations on another height before passing it to ' |
| 'getMinIntrinsicWidth, consider using math.max() or double.clamp() ' |
| 'to force the value into the valid range.' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| return _computeIntrinsicDimension(_IntrinsicDimension.minWidth, height, computeMinIntrinsicWidth); |
| } |
| |
| /// Computes the value returned by [getMinIntrinsicWidth]. Do not call this |
| /// function directly, instead, call [getMinIntrinsicWidth]. |
| /// |
| /// Override in subclasses that implement [performLayout]. This method should |
| /// return the minimum width that this box could be without failing to |
| /// correctly paint its contents within itself, without clipping. |
| /// |
| /// If the layout algorithm is independent of the context (e.g. it always |
| /// tries to be a particular size), or if the layout algorithm is |
| /// width-in-height-out, or if the layout algorithm uses both the incoming |
| /// width and height constraints (e.g. it always sizes itself to |
| /// [BoxConstraints.biggest]), then the `height` argument should be ignored. |
| /// |
| /// If the layout algorithm is strictly height-in-width-out, or is |
| /// height-in-width-out when the width is unconstrained, then the height |
| /// argument is the height to use. |
| /// |
| /// The `height` argument will never be negative or null. It may be infinite. |
| /// |
| /// If this algorithm depends on the intrinsic dimensions of a child, the |
| /// intrinsic dimensions of that child should be obtained using the functions |
| /// whose names start with `get`, not `compute`. |
| /// |
| /// This function should never return a negative or infinite value. |
| /// |
| /// ## Examples |
| /// |
| /// ### Text |
| /// |
| /// Text is the canonical example of a width-in-height-out algorithm. The |
| /// `height` argument is therefore ignored. |
| /// |
| /// Consider the string "Hello World" The _maximum_ intrinsic width (as |
| /// returned from [computeMaxIntrinsicWidth]) would be the width of the string |
| /// with no line breaks. |
| /// |
| /// The minimum intrinsic width would be the width of the widest word, "Hello" |
| /// or "World". If the text is rendered in an even narrower width, however, it |
| /// might still not overflow. For example, maybe the rendering would put a |
| /// line-break half-way through the words, as in "Hel⁞lo⁞Wor⁞ld". However, |
| /// this wouldn't be a _correct_ rendering, and [computeMinIntrinsicWidth] is |
| /// supposed to render the minimum width that the box could be without failing |
| /// to _correctly_ paint the contents within itself. |
| /// |
| /// The minimum intrinsic _height_ for a given width smaller than the minimum |
| /// intrinsic width could therefore be greater than the minimum intrinsic |
| /// height for the minimum intrinsic width. |
| /// |
| /// ### Viewports (e.g. scrolling lists) |
| /// |
| /// Some render boxes are intended to clip their children. For example, the |
| /// render box for a scrolling list might always size itself to its parents' |
| /// size (or rather, to the maximum incoming constraints), regardless of the |
| /// children's sizes, and then clip the children and position them based on |
| /// the current scroll offset. |
| /// |
| /// The intrinsic dimensions in these cases still depend on the children, even |
| /// though the layout algorithm sizes the box in a way independent of the |
| /// children. It is the size that is needed to paint the box's contents (in |
| /// this case, the children) _without clipping_ that matters. |
| /// |
| /// ### When the intrinsic dimensions cannot be known |
| /// |
| /// There are cases where render objects do not have an efficient way to |
| /// compute their intrinsic dimensions. For example, it may be prohibitively |
| /// expensive to reify and measure every child of a lazy viewport (viewports |
| /// generally only instantiate the actually visible children), or the |
| /// dimensions may be computed by a callback about which the render object |
| /// cannot reason. |
| /// |
| /// In such cases, it may be impossible (or at least impractical) to actually |
| /// return a valid answer. In such cases, the intrinsic functions should throw |
| /// when [RenderObject.debugCheckingIntrinsics] is false and asserts are |
| /// enabled, and return 0.0 otherwise. |
| /// |
| /// See the implementations of [LayoutBuilder] or [RenderViewportBase] for |
| /// examples (in particular, |
| /// [RenderViewportBase.debugThrowIfNotCheckingIntrinsics]). |
| /// |
| /// ### Aspect-ratio-driven boxes |
| /// |
| /// Some boxes always return a fixed size based on the constraints. For these |
| /// boxes, the intrinsic functions should return the appropriate size when the |
| /// incoming `height` or `width` argument is finite, treating that as a tight |
| /// constraint in the respective direction and treating the other direction's |
| /// constraints as unbounded. This is because the definitions of |
| /// [computeMinIntrinsicWidth] and [computeMinIntrinsicHeight] are in terms of |
| /// what the dimensions _could be_, and such boxes can only be one size in |
| /// such cases. |
| /// |
| /// When the incoming argument is not finite, then they should return the |
| /// actual intrinsic dimensions based on the contents, as any other box would. |
| @protected |
| double computeMinIntrinsicWidth(double height) { |
| return 0.0; |
| } |
| |
| /// Returns the smallest width beyond which increasing the width never |
| /// decreases the preferred height. The preferred height is the value that |
| /// would be returned by [getMinIntrinsicHeight] for that width. |
| /// |
| /// The height argument may give a specific height to assume. The given height |
| /// can be infinite, meaning that the intrinsic width in an unconstrained |
| /// environment is being requested. The given height should never be negative |
| /// or null. |
| /// |
| /// This function should only be called on one's children. Calling this |
| /// function couples the child with the parent so that when the child's layout |
| /// changes, the parent is notified (via [markNeedsLayout]). |
| /// |
| /// Calling this function is expensive as it can result in O(N^2) behavior. |
| /// |
| /// Do not override this method. Instead, implement |
| /// [computeMaxIntrinsicWidth]. |
| @mustCallSuper |
| double getMaxIntrinsicWidth(double height) { |
| assert(() { |
| if (height == null) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The height argument to getMaxIntrinsicWidth was null.'), |
| ErrorDescription('The argument to getMaxIntrinsicWidth must not be negative or null.'), |
| ErrorHint('If you do not have a specific height in mind, then pass double.infinity instead.'), |
| ]); |
| } |
| if (height < 0.0) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The height argument to getMaxIntrinsicWidth was negative.'), |
| ErrorDescription('The argument to getMaxIntrinsicWidth must not be negative or null.'), |
| ErrorHint( |
| 'If you perform computations on another height before passing it to ' |
| 'getMaxIntrinsicWidth, consider using math.max() or double.clamp() ' |
| 'to force the value into the valid range.' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| return _computeIntrinsicDimension(_IntrinsicDimension.maxWidth, height, computeMaxIntrinsicWidth); |
| } |
| |
| /// Computes the value returned by [getMaxIntrinsicWidth]. Do not call this |
| /// function directly, instead, call [getMaxIntrinsicWidth]. |
| /// |
| /// Override in subclasses that implement [performLayout]. This should return |
| /// the smallest width beyond which increasing the width never decreases the |
| /// preferred height. The preferred height is the value that would be returned |
| /// by [computeMinIntrinsicHeight] for that width. |
| /// |
| /// If the layout algorithm is strictly height-in-width-out, or is |
| /// height-in-width-out when the width is unconstrained, then this should |
| /// return the same value as [computeMinIntrinsicWidth] for the same height. |
| /// |
| /// Otherwise, the height argument should be ignored, and the returned value |
| /// should be equal to or bigger than the value returned by |
| /// [computeMinIntrinsicWidth]. |
| /// |
| /// The `height` argument will never be negative or null. It may be infinite. |
| /// |
| /// The value returned by this method might not match the size that the object |
| /// would actually take. For example, a [RenderBox] subclass that always |
| /// exactly sizes itself using [BoxConstraints.biggest] might well size itself |
| /// bigger than its max intrinsic size. |
| /// |
| /// If this algorithm depends on the intrinsic dimensions of a child, the |
| /// intrinsic dimensions of that child should be obtained using the functions |
| /// whose names start with `get`, not `compute`. |
| /// |
| /// This function should never return a negative or infinite value. |
| /// |
| /// See also: |
| /// |
| /// * [computeMinIntrinsicWidth], which has usage examples. |
| @protected |
| double computeMaxIntrinsicWidth(double height) { |
| return 0.0; |
| } |
| |
| /// Returns the minimum height that this box could be without failing to |
| /// correctly paint its contents within itself, without clipping. |
| /// |
| /// The width argument may give a specific width to assume. The given width |
| /// can be infinite, meaning that the intrinsic height in an unconstrained |
| /// environment is being requested. The given width should never be negative |
| /// or null. |
| /// |
| /// This function should only be called on one's children. Calling this |
| /// function couples the child with the parent so that when the child's layout |
| /// changes, the parent is notified (via [markNeedsLayout]). |
| /// |
| /// Calling this function is expensive as it can result in O(N^2) behavior. |
| /// |
| /// Do not override this method. Instead, implement |
| /// [computeMinIntrinsicHeight]. |
| @mustCallSuper |
| double getMinIntrinsicHeight(double width) { |
| assert(() { |
| if (width == null) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The width argument to getMinIntrinsicHeight was null.'), |
| ErrorDescription('The argument to getMinIntrinsicHeight must not be negative or null.'), |
| ErrorHint('If you do not have a specific width in mind, then pass double.infinity instead.'), |
| ]); |
| } |
| if (width < 0.0) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The width argument to getMinIntrinsicHeight was negative.'), |
| ErrorDescription('The argument to getMinIntrinsicHeight must not be negative or null.'), |
| ErrorHint( |
| 'If you perform computations on another width before passing it to ' |
| 'getMinIntrinsicHeight, consider using math.max() or double.clamp() ' |
| 'to force the value into the valid range.' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| return _computeIntrinsicDimension(_IntrinsicDimension.minHeight, width, computeMinIntrinsicHeight); |
| } |
| |
| /// Computes the value returned by [getMinIntrinsicHeight]. Do not call this |
| /// function directly, instead, call [getMinIntrinsicHeight]. |
| /// |
| /// Override in subclasses that implement [performLayout]. Should return the |
| /// minimum height that this box could be without failing to correctly paint |
| /// its contents within itself, without clipping. |
| /// |
| /// If the layout algorithm is independent of the context (e.g. it always |
| /// tries to be a particular size), or if the layout algorithm is |
| /// height-in-width-out, or if the layout algorithm uses both the incoming |
| /// height and width constraints (e.g. it always sizes itself to |
| /// [BoxConstraints.biggest]), then the `width` argument should be ignored. |
| /// |
| /// If the layout algorithm is strictly width-in-height-out, or is |
| /// width-in-height-out when the height is unconstrained, then the width |
| /// argument is the width to use. |
| /// |
| /// The `width` argument will never be negative or null. It may be infinite. |
| /// |
| /// If this algorithm depends on the intrinsic dimensions of a child, the |
| /// intrinsic dimensions of that child should be obtained using the functions |
| /// whose names start with `get`, not `compute`. |
| /// |
| /// This function should never return a negative or infinite value. |
| /// |
| /// See also: |
| /// |
| /// * [computeMinIntrinsicWidth], which has usage examples. |
| @protected |
| double computeMinIntrinsicHeight(double width) { |
| return 0.0; |
| } |
| |
| /// Returns the smallest height beyond which increasing the height never |
| /// decreases the preferred width. The preferred width is the value that |
| /// would be returned by [getMinIntrinsicWidth] for that height. |
| /// |
| /// The width argument may give a specific width to assume. The given width |
| /// can be infinite, meaning that the intrinsic height in an unconstrained |
| /// environment is being requested. The given width should never be negative |
| /// or null. |
| /// |
| /// This function should only be called on one's children. Calling this |
| /// function couples the child with the parent so that when the child's layout |
| /// changes, the parent is notified (via [markNeedsLayout]). |
| /// |
| /// Calling this function is expensive as it can result in O(N^2) behavior. |
| /// |
| /// Do not override this method. Instead, implement |
| /// [computeMaxIntrinsicHeight]. |
| @mustCallSuper |
| double getMaxIntrinsicHeight(double width) { |
| assert(() { |
| if (width == null) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The width argument to getMaxIntrinsicHeight was null.'), |
| ErrorDescription('The argument to getMaxIntrinsicHeight must not be negative or null.'), |
| ErrorHint('If you do not have a specific width in mind, then pass double.infinity instead.'), |
| ]); |
| } |
| if (width < 0.0) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The width argument to getMaxIntrinsicHeight was negative.'), |
| ErrorDescription('The argument to getMaxIntrinsicHeight must not be negative or null.'), |
| ErrorHint( |
| 'If you perform computations on another width before passing it to ' |
| 'getMaxIntrinsicHeight, consider using math.max() or double.clamp() ' |
| 'to force the value into the valid range.' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| return _computeIntrinsicDimension(_IntrinsicDimension.maxHeight, width, computeMaxIntrinsicHeight); |
| } |
| |
| /// Computes the value returned by [getMaxIntrinsicHeight]. Do not call this |
| /// function directly, instead, call [getMaxIntrinsicHeight]. |
| /// |
| /// Override in subclasses that implement [performLayout]. Should return the |
| /// smallest height beyond which increasing the height never decreases the |
| /// preferred width. The preferred width is the value that would be returned |
| /// by [computeMinIntrinsicWidth] for that height. |
| /// |
| /// If the layout algorithm is strictly width-in-height-out, or is |
| /// width-in-height-out when the height is unconstrained, then this should |
| /// return the same value as [computeMinIntrinsicHeight] for the same width. |
| /// |
| /// Otherwise, the width argument should be ignored, and the returned value |
| /// should be equal to or bigger than the value returned by |
| /// [computeMinIntrinsicHeight]. |
| /// |
| /// The `width` argument will never be negative or null. It may be infinite. |
| /// |
| /// The value returned by this method might not match the size that the object |
| /// would actually take. For example, a [RenderBox] subclass that always |
| /// exactly sizes itself using [BoxConstraints.biggest] might well size itself |
| /// bigger than its max intrinsic size. |
| /// |
| /// If this algorithm depends on the intrinsic dimensions of a child, the |
| /// intrinsic dimensions of that child should be obtained using the functions |
| /// whose names start with `get`, not `compute`. |
| /// |
| /// This function should never return a negative or infinite value. |
| /// |
| /// See also: |
| /// |
| /// * [computeMinIntrinsicWidth], which has usage examples. |
| @protected |
| double computeMaxIntrinsicHeight(double width) { |
| return 0.0; |
| } |
| |
| /// Whether this render object has undergone layout and has a [size]. |
| bool get hasSize => _size != null; |
| |
| /// The size of this render box computed during 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 |
| /// true for parentUsesSize when calling the child's [layout] function. |
| /// |
| /// The size of a box should be set only during the box's [performLayout] or |
| /// [performResize] functions. If you wish to change the size of a box outside |
| /// of those functions, call [markNeedsLayout] instead to schedule a layout of |
| /// the box. |
| Size get size { |
| assert(hasSize, 'RenderBox was not laid out: ${toString()}'); |
| assert(() { |
| final Size _size = this._size; |
| if (_size is _DebugSize) { |
| assert(_size._owner == this); |
| if (RenderObject.debugActiveLayout != null) { |
| // We are always allowed to access our own size (for print debugging |
| // and asserts if nothing else). Other than us, the only object that's |
| // allowed to read our size is our parent, if they've said they will. |
| // If you hit this assert trying to access a child's size, pass |
| // "parentUsesSize: true" to that child's layout(). |
| assert(debugDoingThisResize || debugDoingThisLayout || |
| (RenderObject.debugActiveLayout == parent && _size._canBeUsedByParent)); |
| } |
| assert(_size == this._size); |
| } |
| return true; |
| }()); |
| return _size; |
| } |
| Size _size; |
| /// Setting the size, in checked mode, triggers some analysis of the render box, |
| /// as implemented by [debugAssertDoesMeetConstraints], including calling the intrinsic |
| /// sizing methods and checking that they meet certain invariants. |
| @protected |
| set size(Size value) { |
| assert(!(debugDoingThisResize && debugDoingThisLayout)); |
| assert(sizedByParent || !debugDoingThisResize); |
| assert(() { |
| if ((sizedByParent && debugDoingThisResize) || |
| (!sizedByParent && debugDoingThisLayout)) |
| return true; |
| assert(!debugDoingThisResize); |
| final List<DiagnosticsNode> information = <DiagnosticsNode>[ |
| ErrorSummary('RenderBox size setter called incorrectly.'), |
| ]; |
| if (debugDoingThisLayout) { |
| assert(sizedByParent); |
| information.add(ErrorDescription('It appears that the size setter was called from performLayout().')); |
| } else { |
| information.add(ErrorDescription( |
| 'The size setter was called from outside layout (neither performResize() nor performLayout() were being run for this object).' |
| )); |
| if (owner != null && owner.debugDoingLayout) |
| information.add(ErrorDescription('Only the object itself can set its size. It is a contract violation for other objects to set it.')); |
| } |
| if (sizedByParent) |
| information.add(ErrorDescription('Because this RenderBox has sizedByParent set to true, it must set its size in performResize().')); |
| else |
| information.add(ErrorDescription('Because this RenderBox has sizedByParent set to false, it must set its size in performLayout().')); |
| throw FlutterError.fromParts(information); |
| }()); |
| assert(() { |
| value = debugAdoptSize(value); |
| return true; |
| }()); |
| _size = value; |
| assert(() { |
| debugAssertDoesMeetConstraints(); |
| return true; |
| }()); |
| } |
| |
| /// Claims ownership of the given [Size]. |
| /// |
| /// In debug mode, the [RenderBox] class verifies that [Size] objects obtained |
| /// from other [RenderBox] objects are only used according to the semantics of |
| /// the [RenderBox] protocol, namely that a [Size] from a [RenderBox] can only |
| /// be used by its parent, and then only if `parentUsesSize` was set. |
| /// |
| /// Sometimes, a [Size] that can validly be used ends up no longer being valid |
| /// over time. The common example is a [Size] taken from a child that is later |
| /// removed from the parent. In such cases, this method can be called to first |
| /// check whether the size can legitimately be used, and if so, to then create |
| /// a new [Size] that can be used going forward, regardless of what happens to |
| /// the original owner. |
| Size debugAdoptSize(Size value) { |
| Size result = value; |
| assert(() { |
| if (value is _DebugSize) { |
| if (value._owner != this) { |
| if (value._owner.parent != this) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The size property was assigned a size inappropriately.'), |
| describeForError('The following render object'), |
| value._owner.describeForError('...was assigned a size obtained from'), |
| ErrorDescription( |
| 'However, this second render object is not, or is no longer, a ' |
| 'child of the first, and it is therefore a violation of the ' |
| 'RenderBox layout protocol to use that size in the layout of the ' |
| 'first render object.' |
| ), |
| ErrorHint( |
| 'If the size was obtained at a time where it was valid to read ' |
| 'the size (because the second render object above was a child ' |
| 'of the first at the time), then it should be adopted using ' |
| 'debugAdoptSize at that time.' |
| ), |
| ErrorHint( |
| 'If the size comes from a grandchild or a render object from an ' |
| 'entirely different part of the render tree, then there is no ' |
| 'way to be notified when the size changes and therefore attempts ' |
| 'to read that size are almost certainly a source of bugs. A different ' |
| 'approach should be used.' |
| ), |
| ]); |
| } |
| if (!value._canBeUsedByParent) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary("A child's size was used without setting parentUsesSize."), |
| describeForError('The following render object'), |
| value._owner.describeForError('...was assigned a size obtained from its child'), |
| ErrorDescription( |
| 'However, when the child was laid out, the parentUsesSize argument ' |
| 'was not set or set to false. Subsequently this transpired to be ' |
| 'inaccurate: the size was nonetheless used by the parent.\n' |
| 'It is important to tell the framework if the size will be used or not ' |
| 'as several important performance optimizations can be made if the ' |
| 'size will not be used by the parent.' |
| ), |
| ]); |
| } |
| } |
| } |
| result = _DebugSize(value, this, debugCanParentUseSize); |
| return true; |
| }()); |
| return result; |
| } |
| |
| @override |
| Rect get semanticBounds => Offset.zero & size; |
| |
| @override |
| void debugResetSize() { |
| // updates the value of size._canBeUsedByParent if necessary |
| size = size; |
| } |
| |
| Map<TextBaseline, double> _cachedBaselines; |
| static bool _debugDoingBaseline = false; |
| static bool _debugSetDoingBaseline(bool value) { |
| _debugDoingBaseline = value; |
| return true; |
| } |
| |
| /// Returns the distance from the y-coordinate of the position of the box to |
| /// the y-coordinate of the first given baseline in the box's contents. |
| /// |
| /// Used by certain layout models to align adjacent boxes on a common |
| /// baseline, regardless of padding, font size differences, etc. If there is |
| /// no baseline, this function returns the distance from the y-coordinate of |
| /// the position of the box to the y-coordinate of the bottom of the box |
| /// (i.e., the height of the box) unless the caller passes true |
| /// for `onlyReal`, in which case the function returns null. |
| /// |
| /// Only call this function after calling [layout] on this box. You |
| /// are only allowed to call this from the parent of this box during |
| /// that parent's [performLayout] or [paint] functions. |
| /// |
| /// When implementing a [RenderBox] subclass, to override the baseline |
| /// computation, override [computeDistanceToActualBaseline]. |
| double getDistanceToBaseline(TextBaseline baseline, { bool onlyReal = false }) { |
| assert(!_debugDoingBaseline, 'Please see the documentation for computeDistanceToActualBaseline for the required calling conventions of this method.'); |
| assert(!debugNeedsLayout); |
| assert(() { |
| final RenderObject parent = this.parent as RenderObject; |
| if (owner.debugDoingLayout) |
| return (RenderObject.debugActiveLayout == parent) && parent.debugDoingThisLayout; |
| if (owner.debugDoingPaint) |
| return ((RenderObject.debugActivePaint == parent) && parent.debugDoingThisPaint) || |
| ((RenderObject.debugActivePaint == this) && debugDoingThisPaint); |
| assert(parent == this.parent); |
| return false; |
| }()); |
| assert(_debugSetDoingBaseline(true)); |
| final double result = getDistanceToActualBaseline(baseline); |
| assert(_debugSetDoingBaseline(false)); |
| if (result == null && !onlyReal) |
| return size.height; |
| return result; |
| } |
| |
| /// Calls [computeDistanceToActualBaseline] and caches the result. |
| /// |
| /// This function must only be called from [getDistanceToBaseline] and |
| /// [computeDistanceToActualBaseline]. Do not call this function directly from |
| /// outside those two methods. |
| @protected |
| @mustCallSuper |
| double getDistanceToActualBaseline(TextBaseline baseline) { |
| assert(_debugDoingBaseline, 'Please see the documentation for computeDistanceToActualBaseline for the required calling conventions of this method.'); |
| _cachedBaselines ??= <TextBaseline, double>{}; |
| _cachedBaselines.putIfAbsent(baseline, () => computeDistanceToActualBaseline(baseline)); |
| return _cachedBaselines[baseline]; |
| } |
| |
| /// Returns the distance from the y-coordinate of the position of the box to |
| /// the y-coordinate of the first given baseline in the box's contents, if |
| /// any, or null otherwise. |
| /// |
| /// Do not call this function directly. If you need to know the baseline of a |
| /// child from an invocation of [performLayout] or [paint], call |
| /// [getDistanceToBaseline]. |
| /// |
| /// Subclasses should override this method to supply the distances to their |
| /// baselines. When implementing this method, there are generally three |
| /// strategies: |
| /// |
| /// * For classes that use the [ContainerRenderObjectMixin] child model, |
| /// consider mixing in the [RenderBoxContainerDefaultsMixin] class and |
| /// using |
| /// [RenderBoxContainerDefaultsMixin.defaultComputeDistanceToFirstActualBaseline]. |
| /// |
| /// * For classes that define a particular baseline themselves, return that |
| /// value directly. |
| /// |
| /// * For classes that have a child to which they wish to defer the |
| /// computation, call [getDistanceToActualBaseline] on the child (not |
| /// [computeDistanceToActualBaseline], the internal implementation, and not |
| /// [getDistanceToBaseline], the public entry point for this API). |
| @protected |
| double computeDistanceToActualBaseline(TextBaseline baseline) { |
| assert(_debugDoingBaseline, 'Please see the documentation for computeDistanceToActualBaseline for the required calling conventions of this method.'); |
| return null; |
| } |
| |
| /// The box constraints most recently received from the parent. |
| @override |
| BoxConstraints get constraints => super.constraints as BoxConstraints; |
| |
| @override |
| void debugAssertDoesMeetConstraints() { |
| assert(constraints != null); |
| assert(() { |
| if (!hasSize) { |
| assert(!debugNeedsLayout); // this is called in the size= setter during layout, but in that case we have a size |
| DiagnosticsNode contract; |
| if (sizedByParent) |
| contract = ErrorDescription('Because this RenderBox has sizedByParent set to true, it must set its size in performResize().'); |
| else |
| contract = ErrorDescription('Because this RenderBox has sizedByParent set to false, it must set its size in performLayout().'); |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('RenderBox did not set its size during layout.'), |
| contract, |
| ErrorDescription('It appears that this did not happen; layout completed, but the size property is still null.'), |
| DiagnosticsProperty<RenderBox>('The RenderBox in question is', this, style: DiagnosticsTreeStyle.errorProperty), |
| ]); |
| } |
| // verify that the size is not infinite |
| if (!_size.isFinite) { |
| final List<DiagnosticsNode> information = <DiagnosticsNode>[ |
| ErrorSummary('$runtimeType object was given an infinite size during layout.'), |
| ErrorDescription( |
| 'This probably means that it is a render object that tries to be ' |
| 'as big as possible, but it was put inside another render object ' |
| 'that allows its children to pick their own size.' |
| ), |
| ]; |
| if (!constraints.hasBoundedWidth) { |
| RenderBox node = this; |
| while (!node.constraints.hasBoundedWidth && node.parent is RenderBox) |
| node = node.parent as RenderBox; |
| |
| information.add(node.describeForError('The nearest ancestor providing an unbounded width constraint is')); |
| } |
| if (!constraints.hasBoundedHeight) { |
| RenderBox node = this; |
| while (!node.constraints.hasBoundedHeight && node.parent is RenderBox) |
| node = node.parent as RenderBox; |
| |
| information.add(node.describeForError('The nearest ancestor providing an unbounded height constraint is')); |
| } |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ...information, |
| DiagnosticsProperty<BoxConstraints>('The constraints that applied to the $runtimeType were', constraints, style: DiagnosticsTreeStyle.errorProperty), |
| DiagnosticsProperty<Size>('The exact size it was given was', _size, style: DiagnosticsTreeStyle.errorProperty), |
| ErrorHint('See https://flutter.dev/docs/development/ui/layout/box-constraints for more information.'), |
| ]); |
| } |
| // verify that the size is within the constraints |
| if (!constraints.isSatisfiedBy(_size)) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('$runtimeType does not meet its constraints.'), |
| DiagnosticsProperty<BoxConstraints>('Constraints', constraints, style: DiagnosticsTreeStyle.errorProperty), |
| DiagnosticsProperty<Size>('Size', _size, style: DiagnosticsTreeStyle.errorProperty), |
| ErrorHint( |
| 'If you are not writing your own RenderBox subclass, then this is not ' |
| 'your fault. Contact support: https://github.com/flutter/flutter/issues/new?template=BUG.md' |
| ), |
| ]); |
| } |
| if (debugCheckIntrinsicSizes) { |
| // verify that the intrinsics are sane |
| assert(!RenderObject.debugCheckingIntrinsics); |
| RenderObject.debugCheckingIntrinsics = true; |
| final List<DiagnosticsNode> failures = <DiagnosticsNode>[]; |
| |
| double testIntrinsic(double function(double extent), String name, double constraint) { |
| final double result = function(constraint); |
| if (result < 0) { |
| failures.add(ErrorDescription(' * $name($constraint) returned a negative value: $result')); |
| } |
| if (!result.isFinite) { |
| failures.add(ErrorDescription(' * $name($constraint) returned a non-finite value: $result')); |
| } |
| return result; |
| } |
| |
| void testIntrinsicsForValues(double getMin(double extent), double getMax(double extent), String name, double constraint) { |
| final double min = testIntrinsic(getMin, 'getMinIntrinsic$name', constraint); |
| final double max = testIntrinsic(getMax, 'getMaxIntrinsic$name', constraint); |
| if (min > max) { |
| failures.add(ErrorDescription(' * getMinIntrinsic$name($constraint) returned a larger value ($min) than getMaxIntrinsic$name($constraint) ($max)')); |
| } |
| } |
| |
| testIntrinsicsForValues(getMinIntrinsicWidth, getMaxIntrinsicWidth, 'Width', double.infinity); |
| testIntrinsicsForValues(getMinIntrinsicHeight, getMaxIntrinsicHeight, 'Height', double.infinity); |
| if (constraints.hasBoundedWidth) |
| testIntrinsicsForValues(getMinIntrinsicWidth, getMaxIntrinsicWidth, 'Width', constraints.maxHeight); |
| if (constraints.hasBoundedHeight) |
| testIntrinsicsForValues(getMinIntrinsicHeight, getMaxIntrinsicHeight, 'Height', constraints.maxWidth); |
| |
| // TODO(ianh): Test that values are internally consistent in more ways than the above. |
| |
| RenderObject.debugCheckingIntrinsics = false; |
| if (failures.isNotEmpty) { |
| // TODO(jacobr): consider nesting the failures object so it is collapsible. |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('The intrinsic dimension methods of the $runtimeType class returned values that violate the intrinsic protocol contract.'), |
| ErrorDescription('The following ${failures.length > 1 ? "failures" : "failure"} was detected:'), // should this be tagged as an error or not? |
| ...failures, |
| ErrorHint( |
| 'If you are not writing your own RenderBox subclass, then this is not\n' |
| 'your fault. Contact support: https://github.com/flutter/flutter/issues/new?template=BUG.md' |
| ), |
| ]); |
| } |
| } |
| return true; |
| }()); |
| } |
| |
| @override |
| void markNeedsLayout() { |
| if ((_cachedBaselines != null && _cachedBaselines.isNotEmpty) || |
| (_cachedIntrinsicDimensions != null && _cachedIntrinsicDimensions.isNotEmpty)) { |
| // If we have cached data, then someone must have used our data. |
| // Since the parent will shortly be marked dirty, we can forget that they |
| // used the baseline and/or intrinsic dimensions. If they use them again, |
| // then we'll fill the cache again, and if we get dirty again, we'll |
| // notify them again. |
| _cachedBaselines?.clear(); |
| _cachedIntrinsicDimensions?.clear(); |
| if (parent is RenderObject) { |
| markParentNeedsLayout(); |
| return; |
| } |
| } |
| super.markNeedsLayout(); |
| } |
| |
| @override |
| void performResize() { |
| // default behavior for subclasses that have sizedByParent = true |
| size = constraints.smallest; |
| assert(size.isFinite); |
| } |
| |
| @override |
| void performLayout() { |
| assert(() { |
| if (!sizedByParent) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('$runtimeType did not implement performLayout().'), |
| ErrorHint( |
| 'RenderBox subclasses need to either override performLayout() to ' |
| 'set a size and lay out any children, or, set sizedByParent to true ' |
| 'so that performResize() sizes the render object.' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| } |
| |
| /// Determines the set of render objects located at the given position. |
| /// |
| /// Returns true, and adds any render objects that contain the point to the |
| /// given hit test result, if this render object or one of its descendants |
| /// absorbs the hit (preventing objects below this one from being hit). |
| /// Returns false if the hit can continue to other objects below this one. |
| /// |
| /// The caller is responsible for transforming [position] from global |
| /// coordinates to its location relative to the origin of this [RenderBox]. |
| /// This [RenderBox] is responsible for checking whether the given position is |
| /// within its bounds. |
| /// |
| /// If transforming is necessary, [BoxHitTestResult.addWithPaintTransform], |
| /// [BoxHitTestResult.addWithPaintOffset], or |
| /// [BoxHitTestResult.addWithRawTransform] need to be invoked by the caller |
| /// to record the required transform operations in the [HitTestResult]. These |
| /// methods will also help with applying the transform to `position`. |
| /// |
| /// Hit testing requires layout to be up-to-date but does not require painting |
| /// to be up-to-date. That means a render object can rely upon [performLayout] |
| /// having been called in [hitTest] but cannot rely upon [paint] having been |
| /// called. For example, a render object might be a child of a [RenderOpacity] |
| /// object, which calls [hitTest] on its children when its opacity is zero |
| /// even through it does not [paint] its children. |
| bool hitTest(BoxHitTestResult result, { @required Offset position }) { |
| assert(() { |
| if (!hasSize) { |
| if (debugNeedsLayout) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('Cannot hit test a render box that has never been laid out.'), |
| describeForError('The hitTest() method was called on this RenderBox'), |
| ErrorDescription( |
| "Unfortunately, this object's geometry is not known at this time, " |
| 'probably because it has never been laid out. ' |
| 'This means it cannot be accurately hit-tested.' |
| ), |
| ErrorHint( |
| 'If you are trying ' |
| 'to perform a hit test during the layout phase itself, make sure ' |
| "you only hit test nodes that have completed layout (e.g. the node's " |
| 'children, after their layout() method has been called).' |
| ), |
| ]); |
| } |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('Cannot hit test a render box with no size.'), |
| describeForError('The hitTest() method was called on this RenderBox'), |
| ErrorDescription( |
| 'Although this node is not marked as needing layout, ' |
| 'its size is not set.' |
| ), |
| ErrorHint( |
| 'A RenderBox object must have an ' |
| 'explicit size before it can be hit-tested. Make sure ' |
| 'that the RenderBox in question sets its size during layout.' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| if (_size.contains(position)) { |
| if (hitTestChildren(result, position: position) || hitTestSelf(position)) { |
| result.add(BoxHitTestEntry(this, position)); |
| return true; |
| } |
| } |
| return false; |
| } |
| |
| /// Override this method if this render object can be hit even if its |
| /// children were not hit. |
| /// |
| /// The caller is responsible for transforming [position] from global |
| /// coordinates to its location relative to the origin of this [RenderBox]. |
| /// This [RenderBox] is responsible for checking whether the given position is |
| /// within its bounds. |
| /// |
| /// Used by [hitTest]. If you override [hitTest] and do not call this |
| /// function, then you don't need to implement this function. |
| @protected |
| bool hitTestSelf(Offset position) => false; |
| |
| /// Override this method to check whether any children are located at the |
| /// given position. |
| /// |
| /// Typically children should be hit-tested in reverse paint order so that |
| /// hit tests at locations where children overlap hit the child that is |
| /// visually "on top" (i.e., paints later). |
| /// |
| /// The caller is responsible for transforming [position] from global |
| /// coordinates to its location relative to the origin of this [RenderBox]. |
| /// This [RenderBox] is responsible for checking whether the given position is |
| /// within its bounds. |
| /// |
| /// If transforming is necessary, [HitTestResult.addWithPaintTransform], |
| /// [HitTestResult.addWithPaintOffset], or [HitTestResult.addWithRawTransform] need |
| /// to be invoked by the caller to record the required transform operations |
| /// in the [HitTestResult]. These methods will also help with applying the |
| /// transform to `position`. |
| /// |
| /// Used by [hitTest]. If you override [hitTest] and do not call this |
| /// function, then you don't need to implement this function. |
| @protected |
| bool hitTestChildren(BoxHitTestResult result, { Offset position }) => false; |
| |
| /// Multiply the transform from the parent's coordinate system to this box's |
| /// coordinate system into the given transform. |
| /// |
| /// This function is used to convert coordinate systems between boxes. |
| /// Subclasses that apply transforms during painting should override this |
| /// function to factor those transforms into the calculation. |
| /// |
| /// The [RenderBox] implementation takes care of adjusting the matrix for the |
| /// position of the given child as determined during layout and stored on the |
| /// child's [parentData] in the [BoxParentData.offset] field. |
| @override |
| void applyPaintTransform(RenderObject child, Matrix4 transform) { |
| assert(child != null); |
| assert(child.parent == this); |
| assert(() { |
| if (child.parentData is! BoxParentData) { |
| throw FlutterError.fromParts(<DiagnosticsNode>[ |
| ErrorSummary('$runtimeType does not implement applyPaintTransform.'), |
| describeForError('The following $runtimeType object'), |
| child.describeForError('...did not use a BoxParentData class for the parentData field of the following child'), |
| ErrorDescription('The $runtimeType class inherits from RenderBox.'), |
| ErrorHint( |
| 'The default applyPaintTransform implementation provided by RenderBox assumes that the ' |
| 'children all use BoxParentData objects for their parentData field. ' |
| 'Since $runtimeType does not in fact use that ParentData class for its children, it must ' |
| 'provide an implementation of applyPaintTransform that supports the specific ParentData ' |
| 'subclass used by its children (which apparently is ${child.parentData.runtimeType}).' |
| ), |
| ]); |
| } |
| return true; |
| }()); |
| final BoxParentData childParentData = child.parentData as BoxParentData; |
| final Offset offset = childParentData.offset; |
| transform.translate(offset.dx, offset.dy); |
| } |
| |
| /// Convert the given point from the global coordinate system in logical pixels |
| /// to the local coordinate system for this box. |
| /// |
| /// This method will un-project the point from the screen onto the widget, |
| /// which makes it different from [MatrixUtils.transformPoint]. |
| /// |
| /// If the transform from global coordinates to local coordinates is |
| /// degenerate, this function returns [Offset.zero]. |
| /// |
| /// If `ancestor` is non-null, this function converts the given point from the |
| /// coordinate system of `ancestor` (which must be an ancestor of this render |
| /// object) instead of from the global coordinate system. |
| /// |
| /// This method is implemented in terms of [getTransformTo]. |
| Offset globalToLocal(Offset point, { RenderObject ancestor }) { |
| // We want to find point (p) that corresponds to a given point on the |
| // screen (s), but that also physically resides on the local render plane, |
| // so that it is useful for visually accurate gesture processing in the |
| // local space. For that, we can't simply transform 2D screen point to |
| // the 3D local space since the screen space lacks the depth component |z|, |
| // and so there are many 3D points that correspond to the screen point. |
| // We must first unproject the screen point onto the render plane to find |
| // the true 3D point that corresponds to the screen point. |
| // We do orthogonal unprojection after undoing perspective, in local space. |
| // The render plane is specified by renderBox offset (o) and Z axis (n). |
| // Unprojection is done by finding the intersection of the view vector (d) |
| // with the local X-Y plane: (o-s).dot(n) == (p-s).dot(n), (p-s) == |z|*d. |
| final Matrix4 transform = getTransformTo(ancestor); |
| final double det = transform.invert(); |
| if (det == 0.0) |
| return Offset.zero; |
| final Vector3 n = Vector3(0.0, 0.0, 1.0); |
| final Vector3 i = transform.perspectiveTransform(Vector3(0.0, 0.0, 0.0)); |
| final Vector3 d = transform.perspectiveTransform(Vector3(0.0, 0.0, 1.0)) - i; |
| final Vector3 s = transform.perspectiveTransform(Vector3(point.dx, point.dy, 0.0)); |
| final Vector3 p = s - d * (n.dot(s) / n.dot(d)); |
| return Offset(p.x, p.y); |
| } |
| |
| /// Convert the given point from the local coordinate system for this box to |
| /// the global coordinate system in logical pixels. |
| /// |
| /// If `ancestor` is non-null, this function converts the given point to the |
| /// coordinate system of `ancestor` (which must be an ancestor of this render |
| /// object) instead of to the global coordinate system. |
| /// |
| /// This method is implemented in terms of [getTransformTo]. |
| Offset localToGlobal(Offset point, { RenderObject ancestor }) { |
| return MatrixUtils.transformPoint(getTransformTo(ancestor), point); |
| } |
| |
| /// 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 |
| /// of space this box takes up during layout. For example, if this box casts a |
| /// shadow, that shadow might extend beyond the space allocated to this box |
| /// during layout. |
| /// |
| /// The paint bounds are used to size the buffers into which this box paints. |
| /// If the box attempts to paints outside its paint bounds, there might not be |
| /// enough memory allocated to represent the box's visual appearance, which |
| /// can lead to undefined behavior. |
| /// |
| /// The returned paint bounds are in the local coordinate system of this box. |
| @override |
| Rect get paintBounds => Offset.zero & size; |
| |
| /// Override this method to handle pointer events that hit this render object. |
| /// |
| /// For [RenderBox] objects, the `entry` argument is a [BoxHitTestEntry]. From this |
| /// object you can determine the [PointerDownEvent]'s position in local coordinates. |
| /// (This is useful because [PointerEvent.position] is in global coordinates.) |
| /// |
| /// If you override this, consider calling [debugHandleEvent] as follows, so |
| /// that you can support [debugPaintPointersEnabled]: |
| /// |
| /// ```dart |
| /// @override |
| /// void handleEvent(PointerEvent event, HitTestEntry entry) { |
| /// assert(debugHandleEvent(event, entry)); |
| /// // ... handle the event ... |
| /// } |
| /// ``` |
| @override |
| void handleEvent(PointerEvent event, BoxHitTestEntry entry) { |
| super.handleEvent(event, entry); |
| } |
| |
| int _debugActivePointers = 0; |
| |
| /// Implements the [debugPaintPointersEnabled] debugging feature. |
| /// |
| /// [RenderBox] subclasses that implement [handleEvent] should call |
| /// [debugHandleEvent] from their [handleEvent] method, as follows: |
| /// |
| /// ```dart |
| /// @override |
| /// void handleEvent(PointerEvent event, HitTestEntry entry) { |
| /// assert(debugHandleEvent(event, entry)); |
| /// // ... handle the event ... |
| /// } |
| /// ``` |
| /// |
| /// If you call this for a [PointerDownEvent], make sure you also call it for |
| /// the corresponding [PointerUpEvent] or [PointerCancelEvent]. |
| bool debugHandleEvent(PointerEvent event, HitTestEntry entry) { |
| assert(() { |
| if (debugPaintPointersEnabled) { |
| if (event is PointerDownEvent) { |
| _debugActivePointers += 1; |
| } else if (event is PointerUpEvent || event is PointerCancelEvent) { |
| _debugActivePointers -= 1; |
| } |
| markNeedsPaint(); |
| } |
| return true; |
| }()); |
| return true; |
| } |
| |
| @override |
| void debugPaint(PaintingContext context, Offset offset) { |
| assert(() { |
| if (debugPaintSizeEnabled) |
| debugPaintSize(context, offset); |
| if (debugPaintBaselinesEnabled) |
| debugPaintBaselines(context, offset); |
| if (debugPaintPointersEnabled) |
| debugPaintPointers(context, offset); |
| return true; |
| }()); |
| } |
| |
| /// In debug mode, paints a border around this render box. |
| /// |
| /// Called for every [RenderBox] when [debugPaintSizeEnabled] is true. |
| @protected |
| void debugPaintSize(PaintingContext context, Offset offset) { |
| assert(() { |
| final Paint paint = Paint() |
| ..style = PaintingStyle.stroke |
| ..strokeWidth = 1.0 |
| ..color = const Color(0xFF00FFFF); |
| context.canvas.drawRect((offset & size).deflate(0.5), paint); |
| return true; |
| }()); |
| } |
| |
| /// In debug mode, paints a line for each baseline. |
| /// |
| /// Called for every [RenderBox] when [debugPaintBaselinesEnabled] is true. |
| @protected |
| void debugPaintBaselines(PaintingContext context, Offset offset) { |
| assert(() { |
| final Paint paint = Paint() |
| ..style = PaintingStyle.stroke |
| ..strokeWidth = 0.25; |
| Path path; |
| // ideographic baseline |
| final double baselineI = getDistanceToBaseline(TextBaseline.ideographic, onlyReal: true); |
| if (baselineI != null) { |
| paint.color = const Color(0xFFFFD000); |
| path = Path(); |
| path.moveTo(offset.dx, offset.dy + baselineI); |
| path.lineTo(offset.dx + size.width, offset.dy + baselineI); |
| context.canvas.drawPath(path, paint); |
| } |
| // alphabetic baseline |
| final double baselineA = getDistanceToBaseline(TextBaseline.alphabetic, onlyReal: true); |
| if (baselineA != null) { |
| paint.color = const Color(0xFF00FF00); |
| path = Path(); |
| path.moveTo(offset.dx, offset.dy + baselineA); |
| path.lineTo(offset.dx + size.width, offset.dy + baselineA); |
| context.canvas.drawPath(path, paint); |
| } |
| return true; |
| }()); |
| } |
| |
| /// In debug mode, paints a rectangle if this render box has counted more |
| /// pointer downs than pointer up events. |
| /// |
| /// Called for every [RenderBox] when [debugPaintPointersEnabled] is true. |
| /// |
| /// By default, events are not counted. For details on how to ensure that |
| /// events are counted for your class, see [debugHandleEvent]. |
| @protected |
| void debugPaintPointers(PaintingContext context, Offset offset) { |
| assert(() { |
| if (_debugActivePointers > 0) { |
| final Paint paint = Paint() |
| ..color = Color(0x00BBBB | ((0x04000000 * depth) & 0xFF000000)); |
| context.canvas.drawRect(offset & size, paint); |
| } |
| return true; |
| }()); |
| } |
| |
| @override |
| void debugFillProperties(DiagnosticPropertiesBuilder properties) { |
| super.debugFillProperties(properties); |
| properties.add(DiagnosticsProperty<Size>('size', _size, missingIfNull: true)); |
| } |
| } |
| |
| /// A mixin that provides useful default behaviors for boxes with children |
| /// managed by the [ContainerRenderObjectMixin] mixin. |
| /// |
| /// By convention, this class doesn't override any members of the superclass. |
| /// Instead, it provides helpful functions that subclasses can call as |
| /// appropriate. |
| mixin RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, ParentDataType extends ContainerBoxParentData<ChildType>> implements ContainerRenderObjectMixin<ChildType, ParentDataType> { |
| /// Returns the baseline of the first child with a baseline. |
| /// |
| /// Useful when the children are displayed vertically in the same order they |
| /// appear in the child list. |
| double defaultComputeDistanceToFirstActualBaseline(TextBaseline baseline) { |
| assert(!debugNeedsLayout); |
| ChildType child = firstChild; |
| while (child != null) { |
| final ParentDataType childParentData = child.parentData as ParentDataType; |
| final double result = child.getDistanceToActualBaseline(baseline); |
| if (result != null) |
| return result + childParentData.offset.dy; |
| child = childParentData.nextSibling; |
| } |
| return null; |
| } |
| |
| /// Returns the minimum baseline value among every child. |
| /// |
| /// Useful when the vertical position of the children isn't determined by the |
| /// order in the child list. |
| double defaultComputeDistanceToHighestActualBaseline(TextBaseline baseline) { |
| assert(!debugNeedsLayout); |
| double result; |
| ChildType child = firstChild; |
| while (child != null) { |
| final ParentDataType childParentData = child.parentData as ParentDataType; |
| double candidate = child.getDistanceToActualBaseline(baseline); |
| if (candidate != null) { |
| candidate += childParentData.offset.dy; |
| if (result != null) |
| result = math.min(result, candidate); |
| else |
| result = candidate; |
| } |
| child = childParentData.nextSibling; |
| } |
| return result; |
| } |
| |
| /// 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 |
| /// given point. Returns whether any children contain the given point. |
| /// |
| /// See also: |
| /// |
| /// * [defaultPaint], which paints the children appropriate for this |
| /// hit-testing strategy. |
| bool defaultHitTestChildren(BoxHitTestResult result, { Offset position }) { |
| // The x, y parameters have the top left of the node's box as the origin. |
| ChildType child = lastChild; |
| while (child != null) { |
| final ParentDataType childParentData = child.parentData as ParentDataType; |
| final bool isHit = result.addWithPaintOffset( |
| offset: childParentData.offset, |
| position: position, |
| hitTest: (BoxHitTestResult result, Offset transformed) { |
| assert(transformed == position - childParentData.offset); |
| return child.hitTest(result, position: transformed); |
| }, |
| ); |
| if (isHit) |
| return true; |
| child = childParentData.previousSibling; |
| } |
| return false; |
| } |
| |
| /// Paints each child by walking the child list forwards. |
| /// |
| /// See also: |
| /// |
| /// * [defaultHitTestChildren], which implements hit-testing of the children |
| /// in a manner appropriate for this painting strategy. |
| void defaultPaint(PaintingContext context, Offset offset) { |
| ChildType child = firstChild; |
| while (child != null) { |
| final ParentDataType childParentData = child.parentData as ParentDataType; |
| context.paintChild(child, childParentData.offset + offset); |
| child = childParentData.nextSibling; |
| } |
| } |
| |
| /// Returns a list containing the children of this render object. |
| /// |
| /// This function is useful when you need random-access to the children of |
| /// this render object. If you're accessing the children in order, consider |
| /// walking the child list directly. |
| List<ChildType> getChildrenAsList() { |
| final List<ChildType> result = <ChildType>[]; |
| RenderBox child = firstChild; |
| while (child != null) { |
| final ParentDataType childParentData = child.parentData as ParentDataType; |
| result.add(child as ChildType); |
| child = childParentData.nextSibling; |
| } |
| return result; |
| } |
| } |