layout_builder.dart 12.3 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'package:flutter/foundation.dart';
6 7
import 'package:flutter/rendering.dart';

8 9 10
import 'debug.dart';
import 'framework.dart';

11
/// The signature of the [LayoutBuilder] builder function.
12
typedef LayoutWidgetBuilder = Widget Function(BuildContext context, BoxConstraints constraints);
13

14
/// An abstract superclass for widgets that defer their building until layout.
15 16
///
/// Similar to the [Builder] widget except that the framework calls the [builder]
17 18 19
/// function at layout time and provides the constraints that this widget should
/// adhere to. This is useful when the parent constrains the child's size and layout,
/// and doesn't depend on the child's intrinsic size.
20
///
21
/// {@template flutter.widgets.ConstrainedLayoutBuilder}
22 23 24 25 26
/// The [builder] function is called in the following situations:
///
/// * The first time the widget is laid out.
/// * When the parent widget passes different layout constraints.
/// * When the parent widget updates this widget.
27
/// * When the dependencies that the [builder] function subscribes to change.
28 29 30 31
///
/// The [builder] function is _not_ called during layout if the parent passes
/// the same constraints repeatedly.
/// {@endtemplate}
32 33 34
///
/// Subclasses must return a [RenderObject] that mixes in
/// [RenderConstrainedLayoutBuilder].
35
abstract class ConstrainedLayoutBuilder<ConstraintType extends Constraints> extends RenderObjectWidget {
36 37
  /// Creates a widget that defers its building until layout.
  ///
38 39 40
  /// The [builder] argument must not be null, and the returned widget should not
  /// be null.
  const ConstrainedLayoutBuilder({
41
    super.key,
42
    required this.builder,
43
  }) : assert(builder != null);
44 45

  @override
46
  RenderObjectElement createElement() => _LayoutBuilderElement<ConstraintType>(this);
47

48 49 50 51
  /// Called at layout time to construct the widget tree.
  ///
  /// The builder must not return null.
  final Widget Function(BuildContext, ConstraintType) builder;
52 53

  // updateRenderObject is redundant with the logic in the LayoutBuilderElement below.
54 55
}

56
class _LayoutBuilderElement<ConstraintType extends Constraints> extends RenderObjectElement {
57
  _LayoutBuilderElement(ConstrainedLayoutBuilder<ConstraintType> super.widget);
58 59

  @override
60
  RenderConstrainedLayoutBuilder<ConstraintType, RenderObject> get renderObject => super.renderObject as RenderConstrainedLayoutBuilder<ConstraintType, RenderObject>;
61

62
  Element? _child;
63 64 65

  @override
  void visitChildren(ElementVisitor visitor) {
66
    if (_child != null) {
67
      visitor(_child!);
68
    }
69 70
  }

71
  @override
72
  void forgetChild(Element child) {
73 74
    assert(child == _child);
    _child = null;
75
    super.forgetChild(child);
76 77
  }

78
  @override
79
  void mount(Element? parent, Object? newSlot) {
80
    super.mount(parent, newSlot); // Creates the renderObject.
81
    renderObject.updateCallback(_layout);
82 83 84
  }

  @override
85
  void update(ConstrainedLayoutBuilder<ConstraintType> newWidget) {
86 87 88
    assert(widget != newWidget);
    super.update(newWidget);
    assert(widget == newWidget);
89

90
    renderObject.updateCallback(_layout);
91 92 93
    // Force the callback to be called, even if the layout constraints are the
    // same, because the logic in the callback might have changed.
    renderObject.markNeedsBuild();
94 95
  }

96 97 98 99
  @override
  void performRebuild() {
    // This gets called if markNeedsBuild() is called on us.
    // That might happen if, e.g., our builder uses Inherited widgets.
100 101 102 103 104

    // Force the callback to be called, even if the layout constraints are the
    // same. This is because that callback may depend on the updated widget
    // configuration, or an inherited widget.
    renderObject.markNeedsBuild();
105
    super.performRebuild(); // Calls widget.updateRenderObject (a no-op in this case).
106 107
  }

108 109
  @override
  void unmount() {
110
    renderObject.updateCallback(null);
111 112 113
    super.unmount();
  }

114
  void _layout(ConstraintType constraints) {
115 116
    @pragma('vm:notify-debugger-on-exception')
    void layoutCallback() {
117 118
      Widget built;
      try {
119
        built = (widget as ConstrainedLayoutBuilder<ConstraintType>).builder(this, constraints);
120 121 122 123 124 125 126
        debugWidgetBuilderValue(widget, built);
      } catch (e, stack) {
        built = ErrorWidget.builder(
          _debugReportException(
            ErrorDescription('building $widget'),
            e,
            stack,
127 128 129 130
            informationCollector: () => <DiagnosticsNode>[
              if (kDebugMode)
                DiagnosticsDebugCreator(DebugCreator(this)),
            ],
131 132
          ),
        );
133 134 135 136 137
      }
      try {
        _child = updateChild(_child, built, null);
        assert(_child != null);
      } catch (e, stack) {
138 139 140 141 142
        built = ErrorWidget.builder(
          _debugReportException(
            ErrorDescription('building $widget'),
            e,
            stack,
143 144 145 146
            informationCollector: () => <DiagnosticsNode>[
              if (kDebugMode)
                DiagnosticsDebugCreator(DebugCreator(this)),
            ],
147
          ),
148
        );
149 150
        _child = updateChild(null, built, slot);
      }
151 152 153
    }

    owner!.buildScope(this, layoutCallback);
154 155 156
  }

  @override
157
  void insertRenderObjectChild(RenderObject child, Object? slot) {
158 159
    final RenderObjectWithChildMixin<RenderObject> renderObject = this.renderObject;
    assert(slot == null);
160
    assert(renderObject.debugValidateChild(child));
161 162 163 164 165
    renderObject.child = child;
    assert(renderObject == this.renderObject);
  }

  @override
166
  void moveRenderObjectChild(RenderObject child, Object? oldSlot, Object? newSlot) {
167 168 169 170
    assert(false);
  }

  @override
171
  void removeRenderObjectChild(RenderObject child, Object? slot) {
172
    final RenderConstrainedLayoutBuilder<ConstraintType, RenderObject> renderObject = this.renderObject;
173 174 175 176 177 178
    assert(renderObject.child == child);
    renderObject.child = null;
    assert(renderObject == this.renderObject);
  }
}

179 180 181 182 183
/// Generic mixin for [RenderObject]s created by [ConstrainedLayoutBuilder].
///
/// Provides a callback that should be called at layout time, typically in
/// [RenderObject.performLayout].
mixin RenderConstrainedLayoutBuilder<ConstraintType extends Constraints, ChildType extends RenderObject> on RenderObjectWithChildMixin<ChildType> {
184
  LayoutCallback<ConstraintType>? _callback;
185
  /// Change the layout callback.
186
  void updateCallback(LayoutCallback<ConstraintType>? value) {
187
    if (value == _callback) {
188
      return;
189
    }
190 191 192 193
    _callback = value;
    markNeedsLayout();
  }

194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
  bool _needsBuild = true;

  /// Marks this layout builder as needing to rebuild.
  ///
  /// The layout build rebuilds automatically when layout constraints change.
  /// However, we must also rebuild when the widget updates, e.g. after
  /// [State.setState], or [State.didChangeDependencies], even when the layout
  /// constraints remain unchanged.
  ///
  /// See also:
  ///
  ///  * [ConstrainedLayoutBuilder.builder], which is called during the rebuild.
  void markNeedsBuild() {
    // Do not call the callback directly. It must be called during the layout
    // phase, when parent constraints are available. Calling `markNeedsLayout`
    // will cause it to be called at the right time.
    _needsBuild = true;
    markNeedsLayout();
  }

  // The constraints that were passed to this class last time it was laid out.
  // These constraints are compared to the new constraints to determine whether
  // [ConstrainedLayoutBuilder.builder] needs to be called.
217
  Constraints? _previousConstraints;
218 219 220 221 222 223

  /// Invoke the callback supplied via [updateCallback].
  ///
  /// Typically this results in [ConstrainedLayoutBuilder.builder] being called
  /// during layout.
  void rebuildIfNecessary() {
224
    assert(_callback != null);
225 226 227
    if (_needsBuild || constraints != _previousConstraints) {
      _previousConstraints = constraints;
      _needsBuild = false;
228
      invokeLayoutCallback(_callback!);
229
    }
230
  }
231 232 233 234 235 236 237 238 239 240
}

/// Builds a widget tree that can depend on the parent widget's size.
///
/// Similar to the [Builder] widget except that the framework calls the [builder]
/// function at layout time and provides the parent widget's constraints. This
/// is useful when the parent constrains the child's size and doesn't depend on
/// the child's intrinsic size. The [LayoutBuilder]'s final size will match its
/// child's size.
///
241
/// {@macro flutter.widgets.ConstrainedLayoutBuilder}
242
///
243 244 245 246
/// {@youtube 560 315 https://www.youtube.com/watch?v=IYDVcriKjsw}
///
/// If the child should be smaller than the parent, consider wrapping the child
/// in an [Align] widget. If the child might want to be bigger, consider
247
/// wrapping it in a [SingleChildScrollView] or [OverflowBox].
248
///
249
/// {@tool dartpad}
250 251 252
/// This example uses a [LayoutBuilder] to build a different widget depending on the available width. Resize the
/// DartPad window to see [LayoutBuilder] in action!
///
253
/// ** See code in examples/api/lib/widgets/layout_builder/layout_builder.0.dart **
254 255
/// {@end-tool}
///
256 257 258 259 260 261
/// See also:
///
///  * [SliverLayoutBuilder], the sliver counterpart of this widget.
///  * [Builder], which calls a `builder` function at build time.
///  * [StatefulBuilder], which passes its `builder` function a `setState` callback.
///  * [CustomSingleChildLayout], which positions its child during layout.
262
///  * The [catalog of layout widgets](https://flutter.dev/widgets/layout/).
263 264 265 266 267
class LayoutBuilder extends ConstrainedLayoutBuilder<BoxConstraints> {
  /// Creates a widget that defers its building until layout.
  ///
  /// The [builder] argument must not be null.
  const LayoutBuilder({
268 269 270
    super.key,
    required super.builder,
  }) : assert(builder != null);
271

272 273 274 275
  @override
  LayoutWidgetBuilder get builder => super.builder;

  @override
276
  RenderObject createRenderObject(BuildContext context) => _RenderLayoutBuilder();
277 278 279
}

class _RenderLayoutBuilder extends RenderBox with RenderObjectWithChildMixin<RenderBox>, RenderConstrainedLayoutBuilder<BoxConstraints, RenderBox> {
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
  @override
  double computeMinIntrinsicWidth(double height) {
    assert(_debugThrowIfNotCheckingIntrinsics());
    return 0.0;
  }

  @override
  double computeMaxIntrinsicWidth(double height) {
    assert(_debugThrowIfNotCheckingIntrinsics());
    return 0.0;
  }

  @override
  double computeMinIntrinsicHeight(double width) {
    assert(_debugThrowIfNotCheckingIntrinsics());
    return 0.0;
  }

  @override
  double computeMaxIntrinsicHeight(double width) {
    assert(_debugThrowIfNotCheckingIntrinsics());
    return 0.0;
  }

304 305 306 307 308 309
  @override
  Size computeDryLayout(BoxConstraints constraints) {
    assert(debugCannotComputeDryLayout(reason:
      'Calculating the dry layout would require running the layout callback '
      'speculatively, which might mutate the live render object tree.',
    ));
310
    return Size.zero;
311 312
  }

313 314
  @override
  void performLayout() {
315
    final BoxConstraints constraints = this.constraints;
316
    rebuildIfNecessary();
317
    if (child != null) {
318 319
      child!.layout(constraints, parentUsesSize: true);
      size = constraints.constrain(child!.size);
320 321 322 323 324
    } else {
      size = constraints.biggest;
    }
  }

325
  @override
326
  double? computeDistanceToActualBaseline(TextBaseline baseline) {
327
    if (child != null) {
328
      return child!.getDistanceToActualBaseline(baseline);
329
    }
330 331 332
    return super.computeDistanceToActualBaseline(baseline);
  }

333
  @override
334
  bool hitTestChildren(BoxHitTestResult result, { required Offset position }) {
335 336 337 338 339
    return child?.hitTest(result, position: position) ?? false;
  }

  @override
  void paint(PaintingContext context, Offset offset) {
340
    if (child != null) {
341
      context.paintChild(child!, offset);
342
    }
343
  }
344 345 346 347 348 349 350

  bool _debugThrowIfNotCheckingIntrinsics() {
    assert(() {
      if (!RenderObject.debugCheckingIntrinsics) {
        throw FlutterError(
          'LayoutBuilder does not support returning intrinsic dimensions.\n'
          'Calculating the intrinsic dimensions would require running the layout '
351
          'callback speculatively, which might mutate the live render object tree.',
352 353 354 355 356 357 358
        );
      }
      return true;
    }());

    return true;
  }
359 360
}

361
FlutterErrorDetails _debugReportException(
362
  DiagnosticsNode context,
363
  Object exception,
364
  StackTrace stack, {
365
  InformationCollector? informationCollector,
366
}) {
367
  final FlutterErrorDetails details = FlutterErrorDetails(
368 369 370
    exception: exception,
    stack: stack,
    library: 'widgets library',
371
    context: context,
372
    informationCollector: informationCollector,
373 374 375
  );
  FlutterError.reportError(details);
  return details;
376
}