binding.dart 30.7 KB
Newer Older
1 2 3 4
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:async';
6
import 'dart:developer' as developer;
7
import 'dart:ui' show AppLifecycleState, Locale;
8
import 'dart:ui' as ui show window;
9

10
import 'package:flutter/foundation.dart';
Ian Hickson's avatar
Ian Hickson committed
11
import 'package:flutter/gestures.dart';
12
import 'package:flutter/rendering.dart';
13
import 'package:flutter/scheduler.dart';
Ian Hickson's avatar
Ian Hickson committed
14
import 'package:flutter/services.dart';
15

16
import 'app.dart';
17
import 'focus_manager.dart';
18
import 'framework.dart';
19

20 21
export 'dart:ui' show AppLifecycleState, Locale;

22 23
/// Interface for classes that register with the Widgets layer binding.
///
24
/// See [WidgetsBinding.addObserver] and [WidgetsBinding.removeObserver].
25 26 27 28 29
///
/// This class can be extended directly, to get default behaviors for all of the
/// handlers, or can used with the `implements` keyword, in which case all the
/// handlers must be implemented (and the analyzer will list those that have
/// been omitted).
30 31 32 33 34 35 36 37
///
/// ## Sample code
///
/// This [StatefulWidget] implements the parts of the [State] and
/// [WidgetsBindingObserver] protocols necessary to react to application
/// lifecycle messages. See [didChangeAppLifecycleState].
///
/// ```dart
38 39
/// class AppLifecycleReactor extends StatefulWidget {
///   const AppLifecycleReactor({ Key key }) : super(key: key);
40 41
///
///   @override
42
///   _AppLifecycleReactorState createState() => new _AppLifecycleReactorState();
43 44
/// }
///
45
/// class _AppLifecycleReactorState extends State<AppLifecycleReactor> with WidgetsBindingObserver {
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
///   @override
///   void initState() {
///     super.initState();
///     WidgetsBinding.instance.addObserver(this);
///   }
///
///   @override
///   void dispose() {
///     WidgetsBinding.instance.removeObserver(this);
///     super.dispose();
///   }
///
///   AppLifecycleState _notification;
///
///   @override
///   void didChangeAppLifecycleState(AppLifecycleState state) {
///     setState(() { _notification = state; });
///   }
///
///   @override
///   Widget build(BuildContext context) {
///     return new Text('Last notification: $_notification');
///   }
/// }
/// ```
///
/// To respond to other notifications, replace the [didChangeAppLifecycleState]
/// method above with other methods from this class.
74 75 76 77 78 79 80 81 82 83 84 85 86
abstract class WidgetsBindingObserver {
  /// Called when the system tells the app to pop the current route.
  /// For example, on Android, this is called when the user presses
  /// the back button.
  ///
  /// Observers are notified in registration order until one returns
  /// true. If none return true, the application quits.
  ///
  /// Observers are expected to return true if they were able to
  /// handle the notification, for example by closing an active dialog
  /// box, and false otherwise. The [WidgetsApp] widget uses this
  /// mechanism to notify the [Navigator] widget that it should pop
  /// its current route if possible.
87
  Future<bool> didPopRoute() => new Future<bool>.value(false);
88

89 90 91 92
  /// Called when the host tells the app to push a new route onto the
  /// navigator.
  ///
  /// Observers are expected to return true if they were able to
93
  /// handle the notification. Observers are notified in registration
94 95 96
  /// order until one returns true.
  Future<bool> didPushRoute(String route) => new Future<bool>.value(false);

97 98
  /// Called when the application's dimensions change. For example,
  /// when a phone is rotated.
99 100 101 102 103 104 105 106
  ///
  /// ## Sample code
  ///
  /// This [StatefulWidget] implements the parts of the [State] and
  /// [WidgetsBindingObserver] protocols necessary to react when the device is
  /// rotated (or otherwise changes dimensions).
  ///
  /// ```dart
107 108
  /// class MetricsReactor extends StatefulWidget {
  ///   const MetricsReactor({ Key key }) : super(key: key);
109 110
  ///
  ///   @override
111
  ///   _MetricsReactorState createState() => new _MetricsReactorState();
112 113
  /// }
  ///
114
  /// class _MetricsReactorState extends State<MetricsReactor> with WidgetsBindingObserver {
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
  ///   @override
  ///   void initState() {
  ///     super.initState();
  ///     WidgetsBinding.instance.addObserver(this);
  ///   }
  ///
  ///   @override
  ///   void dispose() {
  ///     WidgetsBinding.instance.removeObserver(this);
  ///     super.dispose();
  ///   }
  ///
  ///   Size _lastSize;
  ///
  ///   @override
  ///   void didChangeMetrics() {
  ///     setState(() { _lastSize = ui.window.physicalSize; });
  ///   }
  ///
  ///   @override
  ///   Widget build(BuildContext context) {
136
  ///     return new Text('Current size: $_lastSize');
137 138 139 140 141 142 143 144 145 146 147 148
  ///   }
  /// }
  /// ```
  ///
  /// In general, this is unnecessary as the layout system takes care of
  /// automatically recomputing the application geometry when the application
  /// size changes.
  ///
  /// See also:
  ///
  ///  * [MediaQuery.of], which provides a similar service with less
  ///    boilerplate.
149
  void didChangeMetrics() { }
150

151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
  /// Called when the platform's text scale factor changes.
  ///
  /// This typically happens as the result of the user changing system
  /// preferences, and it should affect all of the text sizes in the
  /// application.
  ///
  /// ## Sample code
  ///
  /// ```dart
  /// class TextScaleFactorReactor extends StatefulWidget {
  ///   const TextScaleFactorReactor({ Key key }) : super(key: key);
  ///
  ///   @override
  ///   _TextScaleFactorReactorState createState() => new _TextScaleFactorReactorState();
  /// }
  ///
  /// class _TextScaleFactorReactorState extends State<TextScaleFactorReactor> with WidgetsBindingObserver {
  ///   @override
  ///   void initState() {
  ///     super.initState();
  ///     WidgetsBinding.instance.addObserver(this);
  ///   }
  ///
  ///   @override
  ///   void dispose() {
  ///     WidgetsBinding.instance.removeObserver(this);
  ///     super.dispose();
  ///   }
  ///
  ///   double _lastTextScaleFactor;
  ///
  ///   @override
  ///   void didChangeTextScaleFactor() {
  ///     setState(() { _lastTextScaleFactor = ui.window.textScaleFactor; });
  ///   }
  ///
  ///   @override
  ///   Widget build(BuildContext context) {
  ///     return new Text('Current scale factor: $_lastTextScaleFactor');
  ///   }
  /// }
  /// ```
  ///
  /// See also:
  ///
  ///  * [MediaQuery.of], which provides a similar service with less
  ///    boilerplate.
  void didChangeTextScaleFactor() { }

200 201 202
  /// Called when the system tells the app that the user's locale has
  /// changed. For example, if the user changes the system language
  /// settings.
203
  void didChangeLocale(Locale locale) { }
204 205 206

  /// Called when the system puts the app in the background or returns
  /// the app to the foreground.
207 208 209
  ///
  /// An example of implementing this method is provided in the class-level
  /// documentation for the [WidgetsBindingObserver] class.
210
  void didChangeAppLifecycleState(AppLifecycleState state) { }
211 212 213

  /// Called when the system is running low on memory.
  void didHaveMemoryPressure() { }
Ian Hickson's avatar
Ian Hickson committed
214
}
215

216
/// The glue between the widgets layer and the Flutter engine.
217 218 219 220 221
abstract class WidgetsBinding extends BindingBase with GestureBinding, RendererBinding {
  // This class is intended to be used as a mixin, and should not be
  // extended directly.
  factory WidgetsBinding._() => null;

222
  @override
223
  void initInstances() {
Ian Hickson's avatar
Ian Hickson committed
224 225
    super.initInstances();
    _instance = this;
226
    buildOwner.onBuildScheduled = _handleBuildScheduled;
Ian Hickson's avatar
Ian Hickson committed
227
    ui.window.onLocaleChanged = handleLocaleChanged;
228 229 230
    SystemChannels.navigation.setMethodCallHandler(_handleNavigationInvocation);
    SystemChannels.lifecycle.setMessageHandler(_handleLifecycleMessage);
    SystemChannels.system.setMessageHandler(_handleSystemMessage);
231 232
  }

233
  /// The current [WidgetsBinding], if one has been created.
234 235 236
  ///
  /// If you need the binding to be constructed before calling [runApp],
  /// you can ensure a Widget binding has been constructed by calling the
237 238 239
  /// `WidgetsFlutterBinding.ensureInitialized()` function.
  static WidgetsBinding get instance => _instance;
  static WidgetsBinding _instance;
240

241 242 243 244
  @override
  void initServiceExtensions() {
    super.initServiceExtensions();

245 246
    registerSignalServiceExtension(
      name: 'debugDumpApp',
247
      callback: () { debugDumpApp(); return debugPrintDone; }
248 249
    );

250 251
    registerBoolServiceExtension(
      name: 'showPerformanceOverlay',
252
      getter: () => new Future<bool>.value(WidgetsApp.showPerformanceOverlayOverride),
253 254
      setter: (bool value) {
        if (WidgetsApp.showPerformanceOverlayOverride == value)
255
          return new Future<Null>.value();
256
        WidgetsApp.showPerformanceOverlayOverride = value;
257
        return _forceRebuild();
258 259
      }
    );
260 261 262

    registerBoolServiceExtension(
      name: 'debugAllowBanner',
263
      getter: () => new Future<bool>.value(WidgetsApp.debugAllowBannerOverride),
264 265
      setter: (bool value) {
        if (WidgetsApp.debugAllowBannerOverride == value)
266
          return new Future<Null>.value();
267
        WidgetsApp.debugAllowBannerOverride = value;
268
        return _forceRebuild();
269 270
      }
    );
271 272 273 274 275 276 277 278 279 280 281

    registerBoolServiceExtension(
        name: 'debugWidgetInspector',
        getter: () async => WidgetsApp.debugShowWidgetInspectorOverride,
        setter: (bool value) {
          if (WidgetsApp.debugShowWidgetInspectorOverride == value)
            return new Future<Null>.value();
          WidgetsApp.debugShowWidgetInspectorOverride = value;
          return _forceRebuild();
        }
    );
282 283
  }

284 285 286 287 288 289 290 291
  Future<Null> _forceRebuild() {
    if (renderViewElement != null) {
      buildOwner.reassemble(renderViewElement);
      return endOfFrame;
    }
    return new Future<Null>.value();
  }

292 293 294 295
  /// The [BuildOwner] in charge of executing the build pipeline for the
  /// widget tree rooted at this binding.
  BuildOwner get buildOwner => _buildOwner;
  final BuildOwner _buildOwner = new BuildOwner();
Ian Hickson's avatar
Ian Hickson committed
296

297
  /// The object in charge of the focus tree.
298
  ///
299 300
  /// Rarely used directly. Instead, consider using [FocusScope.of] to obtain
  /// the [FocusScopeNode] for a given [BuildContext].
301
  ///
302 303 304
  /// See [FocusManager] for more details.
  final FocusManager focusManager = new FocusManager();

305
  final List<WidgetsBindingObserver> _observers = <WidgetsBindingObserver>[];
Ian Hickson's avatar
Ian Hickson committed
306

307 308 309 310 311 312 313 314 315 316 317 318
  /// Registers the given object as a binding observer. Binding
  /// observers are notified when various application events occur,
  /// for example when the system locale changes. Generally, one
  /// widget in the widget tree registers itself as a binding
  /// observer, and converts the system state into inherited widgets.
  ///
  /// For example, the [WidgetsApp] widget registers as a binding
  /// observer and passes the screen size to a [MediaQuery] widget
  /// each time it is built, which enables other widgets to use the
  /// [MediaQuery.of] static method and (implicitly) the
  /// [InheritedWidget] mechanism to be notified whenever the screen
  /// size changes (e.g. whenever the screen rotates).
319 320 321 322 323
  ///
  /// See also:
  ///
  ///  * [removeObserver], to release the resources reserved by this method.
  ///  * [WidgetsBindingObserver], which has an example of using this method.
324 325 326 327 328
  void addObserver(WidgetsBindingObserver observer) => _observers.add(observer);

  /// Unregisters the given observer. This should be used sparingly as
  /// it is relatively expensive (O(N) in the number of registered
  /// observers).
329 330 331 332 333
  ///
  /// See also:
  ///
  ///  * [addObserver], for the method that adds observers in the first place.
  ///  * [WidgetsBindingObserver], which has an example of using this method.
334 335
  bool removeObserver(WidgetsBindingObserver observer) => _observers.remove(observer);

336
  @override
Ian Hickson's avatar
Ian Hickson committed
337 338
  void handleMetricsChanged() {
    super.handleMetricsChanged();
339
    for (WidgetsBindingObserver observer in _observers)
340
      observer.didChangeMetrics();
Ian Hickson's avatar
Ian Hickson committed
341 342
  }

343 344 345 346 347 348 349
  @override
  void handleTextScaleFactorChanged() {
    super.handleTextScaleFactorChanged();
    for (WidgetsBindingObserver observer in _observers)
      observer.didChangeTextScaleFactor();
  }

350
  /// Called when the system locale changes.
351 352 353
  ///
  /// Calls [dispatchLocaleChanged] to notify the binding observers.
  ///
354
  /// See [Window.onLocaleChanged].
Ian Hickson's avatar
Ian Hickson committed
355 356 357 358
  void handleLocaleChanged() {
    dispatchLocaleChanged(ui.window.locale);
  }

359 360 361
  /// Notify all the observers that the locale has changed (using
  /// [WidgetsBindingObserver.didChangeLocale]), giving them the
  /// `locale` argument.
362
  void dispatchLocaleChanged(Locale locale) {
363
    for (WidgetsBindingObserver observer in _observers)
Ian Hickson's avatar
Ian Hickson committed
364 365 366
      observer.didChangeLocale(locale);
  }

367
  /// Called when the system pops the current route.
368 369 370 371 372 373 374 375 376 377
  ///
  /// This first notifies the binding observers (using
  /// [WidgetsBindingObserver.didPopRoute]), in registration order,
  /// until one returns true, meaning that it was able to handle the
  /// request (e.g. by closing a dialog box). If none return true,
  /// then the application is shut down.
  ///
  /// [WidgetsApp] uses this in conjunction with a [Navigator] to
  /// cause the back button to close dialog boxes, return from modal
  /// pages, and so forth.
378
  Future<Null> handlePopRoute() async {
379
    for (WidgetsBindingObserver observer in new List<WidgetsBindingObserver>.from(_observers)) {
380
      if (await observer.didPopRoute())
381
        return;
Ian Hickson's avatar
Ian Hickson committed
382
    }
383
    SystemNavigator.pop();
Ian Hickson's avatar
Ian Hickson committed
384
  }
Hixie's avatar
Hixie committed
385

386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402
  /// Called when the host tells the app to push a new route onto the
  /// navigator.
  Future<Null> handlePushRoute(String route) async {
    for (WidgetsBindingObserver observer in new List<WidgetsBindingObserver>.from(_observers)) {
      if (await observer.didPushRoute(route))
        return;
    }
  }

  Future<dynamic> _handleNavigationInvocation(MethodCall methodCall) {
    switch (methodCall.method) {
      case 'popRoute':
        return handlePopRoute();
      case 'pushRoute':
        return handlePushRoute(methodCall.arguments);
    }
    return new Future<Null>.value();
403 404
  }

405
  /// Called when the application lifecycle state changes.
406 407 408
  ///
  /// Notifies all the observers using
  /// [WidgetsBindingObserver.didChangeAppLifecycleState].
409
  void handleAppLifecycleStateChanged(AppLifecycleState state) {
410
    for (WidgetsBindingObserver observer in _observers)
411 412 413
      observer.didChangeAppLifecycleState(state);
  }

414 415 416 417 418 419 420 421
  Future<String> _handleLifecycleMessage(String message) async {
    switch (message) {
      case 'AppLifecycleState.paused':
        handleAppLifecycleStateChanged(AppLifecycleState.paused);
        break;
      case 'AppLifecycleState.resumed':
        handleAppLifecycleStateChanged(AppLifecycleState.resumed);
        break;
422 423 424 425 426 427
      case 'AppLifecycleState.inactive':
        handleAppLifecycleStateChanged(AppLifecycleState.inactive);
        break;
      case 'AppLifecycleState.suspending':
        handleAppLifecycleStateChanged(AppLifecycleState.suspending);
        break;
428 429 430 431
    }
    return null;
  }

432 433 434 435 436 437 438 439 440
  Future<dynamic> _handleSystemMessage(Map<String, dynamic> message) async {
    final String type = message['type'];
    if (type == 'memoryPressure') {
      for (WidgetsBindingObserver observer in _observers)
        observer.didHaveMemoryPressure();
    }
    return null;
  }

441
  bool _needToReportFirstFrame = true;
442 443
  int _deferFirstFrameReportCount = 0;
  bool get _reportFirstFrame => _deferFirstFrameReportCount == 0;
444

445 446
  /// Tell the framework not to report the frame it is building as a "useful"
  /// first frame until there is a corresponding call to [allowFirstFrameReport].
447 448
  ///
  /// This is used by [WidgetsApp] to report the first frame.
449 450
  //
  // TODO(ianh): This method should only be available in debug and profile modes.
451 452 453
  void deferFirstFrameReport() {
    assert(_deferFirstFrameReportCount >= 0);
    _deferFirstFrameReportCount += 1;
454 455
  }

456 457 458 459 460 461 462 463 464 465 466 467 468 469 470
  /// When called after [deferFirstFrameReport]: tell the framework to report
  /// the frame it is building as a "useful" first frame.
  ///
  /// This method may only be called once for each corresponding call
  /// to [deferFirstFrameReport].
  ///
  /// This is used by [WidgetsApp] to report the first frame.
  //
  // TODO(ianh): This method should only be available in debug and profile modes.
  void allowFirstFrameReport() {
    assert(_deferFirstFrameReportCount >= 1);
    _deferFirstFrameReportCount -= 1;
  }

    void _handleBuildScheduled() {
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493
    // If we're in the process of building dirty elements, then changes
    // should not trigger a new frame.
    assert(() {
      if (debugBuildingDirtyElements) {
        throw new FlutterError(
          'Build scheduled during frame.\n'
          'While the widget tree was being built, laid out, and painted, '
          'a new frame was scheduled to rebuild the widget tree. '
          'This might be because setState() was called from a layout or '
          'paint callback. '
          'If a change is needed to the widget tree, it should be applied '
          'as the tree is being built. Scheduling a change for the subsequent '
          'frame instead results in an interface that lags behind by one frame. '
          'If this was done to make your build dependent on a size measured at '
          'layout time, consider using a LayoutBuilder, CustomSingleChildLayout, '
          'or CustomMultiChildLayout. If, on the other hand, the one frame delay '
          'is the desired effect, for example because this is an '
          'animation, consider scheduling the frame in a post-frame callback '
          'using SchedulerBinding.addPostFrameCallback or '
          'using an AnimationController to trigger the animation.'
        );
      }
      return true;
494
    }());
495
    ensureVisualUpdate();
496 497
  }

498 499 500 501 502 503 504 505
  /// Whether we are currently in a frame. This is used to verify
  /// that frames are not scheduled redundantly.
  ///
  /// This is public so that test frameworks can change it.
  ///
  /// This flag is not used in release builds.
  @protected
  bool debugBuildingDirtyElements = false;
506

507 508
  /// Pump the build and rendering pipeline to generate a frame.
  ///
509
  /// This method is called by [handleDrawFrame], which itself is called
510 511 512 513 514 515
  /// automatically by the engine when when it is time to lay out and paint a
  /// frame.
  ///
  /// Each frame consists of the following phases:
  ///
  /// 1. The animation phase: The [handleBeginFrame] method, which is registered
Ian Hickson's avatar
Ian Hickson committed
516
  /// with [Window.onBeginFrame], invokes all the transient frame callbacks
517
  /// registered with [scheduleFrameCallback], in
518 519 520 521
  /// registration order. This includes all the [Ticker] instances that are
  /// driving [AnimationController] objects, which means all of the active
  /// [Animation] objects tick at this point.
  ///
522 523 524 525
  /// 2. Microtasks: After [handleBeginFrame] returns, any microtasks that got
  /// scheduled by transient frame callbacks get to run. This typically includes
  /// callbacks for futures from [Ticker]s and [AnimationController]s that
  /// completed this frame.
526
  ///
527
  /// After [handleBeginFrame], [handleDrawFrame], which is registered with
Ian Hickson's avatar
Ian Hickson committed
528
  /// [Window.onDrawFrame], is called, which invokes all the persistent frame
529 530 531 532
  /// callbacks, of which the most notable is this method, [drawFrame], which
  /// proceeds as follows:
  ///
  /// 3. The build phase: All the dirty [Element]s in the widget tree are
533 534 535 536
  /// rebuilt (see [State.build]). See [State.setState] for further details on
  /// marking a widget dirty for building. See [BuildOwner] for more information
  /// on this step.
  ///
537
  /// 4. The layout phase: All the dirty [RenderObject]s in the system are laid
538 539 540
  /// out (see [RenderObject.performLayout]). See [RenderObject.markNeedsLayout]
  /// for further details on marking an object dirty for layout.
  ///
541
  /// 5. The compositing bits phase: The compositing bits on any dirty
542 543 544
  /// [RenderObject] objects are updated. See
  /// [RenderObject.markNeedsCompositingBitsUpdate].
  ///
545
  /// 6. The paint phase: All the dirty [RenderObject]s in the system are
546 547 548 549
  /// repainted (see [RenderObject.paint]). This generates the [Layer] tree. See
  /// [RenderObject.markNeedsPaint] for further details on marking an object
  /// dirty for paint.
  ///
550
  /// 7. The compositing phase: The layer tree is turned into a [Scene] and
551 552
  /// sent to the GPU.
  ///
553
  /// 8. The semantics phase: All the dirty [RenderObject]s in the system have
Ian Hickson's avatar
Ian Hickson committed
554
  /// their semantics updated (see [RenderObject.semanticsAnnotator]). This
555 556 557 558
  /// generates the [SemanticsNode] tree. See
  /// [RenderObject.markNeedsSemanticsUpdate] for further details on marking an
  /// object dirty for semantics.
  ///
559
  /// For more details on steps 4-8, see [PipelineOwner].
560
  ///
561
  /// 9. The finalization phase in the widgets layer: The widgets tree is
562 563 564 565
  /// finalized. This causes [State.dispose] to be invoked on any objects that
  /// were removed from the widgets tree this frame. See
  /// [BuildOwner.finalizeTree] for more details.
  ///
566 567 568
  /// 10. The finalization phase in the scheduler layer: After [drawFrame]
  /// returns, [handleDrawFrame] then invokes post-frame callbacks (registered
  /// with [addPostFrameCallback]).
569 570
  //
  // When editing the above, also update rendering/binding.dart's copy.
571
  @override
572
  void drawFrame() {
573 574 575 576
    assert(!debugBuildingDirtyElements);
    assert(() {
      debugBuildingDirtyElements = true;
      return true;
577
    }());
578
    try {
579 580
      if (renderViewElement != null)
        buildOwner.buildScope(renderViewElement);
581
      super.drawFrame();
582 583 584 585 586
      buildOwner.finalizeTree();
    } finally {
      assert(() {
        debugBuildingDirtyElements = false;
        return true;
587
      }());
588
    }
589
    // TODO(ianh): Following code should not be included in release mode, only profile and debug modes.
590
    // See https://github.com/dart-lang/sdk/issues/27192
591 592 593 594
    if (_needToReportFirstFrame && _reportFirstFrame) {
      developer.Timeline.instantSync('Widgets completed first useful frame');
      developer.postEvent('Flutter.FirstFrame', <String, dynamic>{});
      _needToReportFirstFrame = false;
595
    }
596
  }
597 598 599

  /// The [Element] that is at the root of the hierarchy (and which wraps the
  /// [RenderView] object at the root of the rendering hierarchy).
600 601
  ///
  /// This is initialized the first time [runApp] is called.
602 603
  Element get renderViewElement => _renderViewElement;
  Element _renderViewElement;
604 605 606 607 608 609 610 611

  /// Takes a widget and attaches it to the [renderViewElement], creating it if
  /// necessary.
  ///
  /// This is called by [runApp] to configure the widget tree.
  ///
  /// See also [RenderObjectToWidgetAdapter.attachToRenderTree].
  void attachRootWidget(Widget rootWidget) {
612 613
    _renderViewElement = new RenderObjectToWidgetAdapter<RenderBox>(
      container: renderView,
614
      debugShortDescription: '[root]',
615
      child: rootWidget
616
    ).attachToRenderTree(buildOwner, renderViewElement);
617
  }
618 619

  @override
620
  Future<Null> performReassemble() {
621
    deferFirstFrameReport();
622 623
    if (renderViewElement != null)
      buildOwner.reassemble(renderViewElement);
624 625 626 627 628 629
    // TODO(hansmuller): eliminate the value variable after analyzer bug
    // https://github.com/flutter/flutter/issues/11646 is fixed.
    final Future<Null> value = super.performReassemble();
    return value.then((Null _) {
      allowFirstFrameReport();
    });
630
  }
631
}
Hixie's avatar
Hixie committed
632

633
/// Inflate the given widget and attach it to the screen.
634
///
635 636 637 638 639
/// The widget is given constraints during layout that force it to fill the
/// entire screen. If you wish to align your widget to one side of the screen
/// (e.g., the top), consider using the [Align] widget. If you wish to center
/// your widget, you can also use the [Center] widget
///
640 641 642 643 644 645
/// Calling [runApp] again will detach the previous root widget from the screen
/// and attach the given widget in its place. The new widget tree is compared
/// against the previous widget tree and any differences are applied to the
/// underlying render tree, similar to what happens when a [StatefulWidget]
/// rebuilds after calling [State.setState].
///
646
/// Initializes the binding using [WidgetsFlutterBinding] if necessary.
647 648 649 650 651 652 653 654 655
///
/// See also:
///
/// * [WidgetsBinding.attachRootWidget], which creates the root widget for the
///   widget hierarchy.
/// * [RenderObjectToWidgetAdapter.attachToRenderTree], which creates the root
///   element for the element hierarchy.
/// * [WidgetsBinding.handleBeginFrame], which pumps the widget pipeline to
///   ensure the widget, element, and render trees are all built.
Hixie's avatar
Hixie committed
656
void runApp(Widget app) {
657 658
  WidgetsFlutterBinding.ensureInitialized()
    ..attachRootWidget(app)
659
    ..scheduleWarmUpFrame();
Hixie's avatar
Hixie committed
660 661
}

662
/// Print a string representation of the currently running app.
663
void debugDumpApp() {
664
  assert(WidgetsBinding.instance != null);
Hixie's avatar
Hixie committed
665
  String mode = 'RELEASE MODE';
666
  assert(() { mode = 'CHECKED MODE'; return true; }());
667
  debugPrint('${WidgetsBinding.instance.runtimeType} - $mode');
668 669 670 671 672
  if (WidgetsBinding.instance.renderViewElement != null) {
    debugPrint(WidgetsBinding.instance.renderViewElement.toStringDeep());
  } else {
    debugPrint('<no tree currently mounted>');
  }
673 674
}

675 676 677 678 679 680 681 682
/// A bridge from a [RenderObject] to an [Element] tree.
///
/// The given container is the [RenderObject] that the [Element] tree should be
/// inserted into. It must be a [RenderObject] that implements the
/// [RenderObjectWithChildMixin] protocol. The type argument `T` is the kind of
/// [RenderObject] that the container expects as its child.
///
/// Used by [runApp] to bootstrap applications.
Hixie's avatar
Hixie committed
683
class RenderObjectToWidgetAdapter<T extends RenderObject> extends RenderObjectWidget {
684 685 686
  /// Creates a bridge from a [RenderObject] to an [Element] tree.
  ///
  /// Used by [WidgetsBinding] to attach the root widget to the [RenderView].
687 688
  RenderObjectToWidgetAdapter({
    this.child,
689
    this.container,
690
    this.debugShortDescription
691
  }) : super(key: new GlobalObjectKey(container));
Hixie's avatar
Hixie committed
692

693
  /// The widget below this widget in the tree.
Hixie's avatar
Hixie committed
694
  final Widget child;
695

696
  /// The [RenderObject] that is the parent of the [Element] created by this widget.
Hixie's avatar
Hixie committed
697
  final RenderObjectWithChildMixin<T> container;
698

699
  /// A short description of this widget used by debugging aids.
700
  final String debugShortDescription;
Hixie's avatar
Hixie committed
701

702
  @override
Hixie's avatar
Hixie committed
703 704
  RenderObjectToWidgetElement<T> createElement() => new RenderObjectToWidgetElement<T>(this);

705
  @override
706
  RenderObjectWithChildMixin<T> createRenderObject(BuildContext context) => container;
Hixie's avatar
Hixie committed
707

708
  @override
709
  void updateRenderObject(BuildContext context, RenderObject renderObject) { }
710

711 712
  /// Inflate this widget and actually set the resulting [RenderObject] as the
  /// child of [container].
713 714
  ///
  /// If `element` is null, this function will create a new element. Otherwise,
715
  /// the given element will have an update scheduled to switch to this widget.
716 717
  ///
  /// Used by [runApp] to bootstrap applications.
718
  RenderObjectToWidgetElement<T> attachToRenderTree(BuildOwner owner, [RenderObjectToWidgetElement<T> element]) {
719 720
    if (element == null) {
      owner.lockState(() {
721
        element = createElement();
722
        assert(element != null);
723
        element.assignOwner(owner);
724 725
      });
      owner.buildScope(element, () {
726
        element.mount(null, null);
727 728
      });
    } else {
729 730
      element._newWidget = this;
      element.markNeedsBuild();
731
    }
732 733
    return element;
  }
734

735
  @override
736
  String toStringShort() => debugShortDescription ?? super.toStringShort();
Hixie's avatar
Hixie committed
737 738
}

739 740 741 742 743
/// A [RootRenderObjectElement] that is hosted by a [RenderObject].
///
/// This element class is the instantiation of a [RenderObjectToWidgetAdapter]
/// widget. It can be used only as the root of an [Element] tree (it cannot be
/// mounted into another [Element]; it's parent must be null).
Hixie's avatar
Hixie committed
744
///
745 746
/// In typical usage, it will be instantiated for a [RenderObjectToWidgetAdapter]
/// whose container is the [RenderView] that connects to the Flutter engine. In
Hixie's avatar
Hixie committed
747
/// this usage, it is normally instantiated by the bootstrapping logic in the
748
/// [WidgetsFlutterBinding] singleton created by [runApp].
749
class RenderObjectToWidgetElement<T extends RenderObject> extends RootRenderObjectElement {
750 751 752 753 754
  /// Creates an element that is hosted by a [RenderObject].
  ///
  /// The [RenderObject] created by this element is not automatically set as a
  /// child of the hosting [RenderObject]. To actually attach this element to
  /// the render tree, call [RenderObjectToWidgetAdapter.attachToRenderTree].
Hixie's avatar
Hixie committed
755 756
  RenderObjectToWidgetElement(RenderObjectToWidgetAdapter<T> widget) : super(widget);

757
  @override
758 759
  RenderObjectToWidgetAdapter<T> get widget => super.widget;

Hixie's avatar
Hixie committed
760 761
  Element _child;

762
  static const Object _rootChildSlot = const Object();
Hixie's avatar
Hixie committed
763

764
  @override
Hixie's avatar
Hixie committed
765 766 767 768 769
  void visitChildren(ElementVisitor visitor) {
    if (_child != null)
      visitor(_child);
  }

770
  @override
771
  void forgetChild(Element child) {
772 773 774 775
    assert(child == _child);
    _child = null;
  }

776
  @override
Hixie's avatar
Hixie committed
777
  void mount(Element parent, dynamic newSlot) {
Hixie's avatar
Hixie committed
778
    assert(parent == null);
Hixie's avatar
Hixie committed
779
    super.mount(parent, newSlot);
780
    _rebuild();
Hixie's avatar
Hixie committed
781 782
  }

783
  @override
Hixie's avatar
Hixie committed
784 785 786
  void update(RenderObjectToWidgetAdapter<T> newWidget) {
    super.update(newWidget);
    assert(widget == newWidget);
787 788 789
    _rebuild();
  }

790 791 792 793 794 795
  // When we are assigned a new widget, we store it here
  // until we are ready to update to it.
  Widget _newWidget;

  @override
  void performRebuild() {
Ian Hickson's avatar
Ian Hickson committed
796 797 798 799 800 801 802
    if (_newWidget != null) {
      // _newWidget can be null if, for instance, we were rebuilt
      // due to a reassemble.
      final Widget newWidget = _newWidget;
      _newWidget = null;
      update(newWidget);
    }
803 804 805 806
    super.performRebuild();
    assert(_newWidget == null);
  }

807 808 809 810 811 812 813 814 815 816 817
  void _rebuild() {
    try {
      _child = updateChild(_child, widget.child, _rootChildSlot);
      assert(_child != null);
    } catch (exception, stack) {
      FlutterError.reportError(new FlutterErrorDetails(
        exception: exception,
        stack: stack,
        library: 'widgets library',
        context: 'attaching to the render tree'
      ));
818
      final Widget error = new ErrorWidget(exception);
819 820
      _child = updateChild(null, error, _rootChildSlot);
    }
Hixie's avatar
Hixie committed
821 822
  }

823
  @override
Hixie's avatar
Hixie committed
824 825
  RenderObjectWithChildMixin<T> get renderObject => super.renderObject;

826
  @override
Hixie's avatar
Hixie committed
827
  void insertChildRenderObject(RenderObject child, dynamic slot) {
Ian Hickson's avatar
Ian Hickson committed
828
    assert(slot == _rootChildSlot);
829
    assert(renderObject.debugValidateChild(child));
Hixie's avatar
Hixie committed
830 831 832
    renderObject.child = child;
  }

833
  @override
Adam Barth's avatar
Adam Barth committed
834 835 836 837
  void moveChildRenderObject(RenderObject child, dynamic slot) {
    assert(false);
  }

838
  @override
Hixie's avatar
Hixie committed
839 840 841 842
  void removeChildRenderObject(RenderObject child) {
    assert(renderObject.child == child);
    renderObject.child = null;
  }
Adam Barth's avatar
Adam Barth committed
843
}
844 845 846

/// A concrete binding for applications based on the Widgets framework.
/// This is the glue that binds the framework to the Flutter engine.
847
class WidgetsFlutterBinding extends BindingBase with SchedulerBinding, GestureBinding, ServicesBinding, RendererBinding, WidgetsBinding {
848 849 850 851 852

  /// Returns an instance of the [WidgetsBinding], creating and
  /// initializing it if necessary. If one is created, it will be a
  /// [WidgetsFlutterBinding]. If one was previously initialized, then
  /// it will at least implement [WidgetsBinding].
853 854 855
  ///
  /// You only need to call this method if you need the binding to be
  /// initialized before calling [runApp].
856 857 858 859 860
  ///
  /// In the `flutter_test` framework, [testWidgets] initializes the
  /// binding instance to a [TestWidgetsFlutterBinding], not a
  /// [WidgetsFlutterBinding].
  static WidgetsBinding ensureInitialized() {
861 862 863
    if (WidgetsBinding.instance == null)
      new WidgetsFlutterBinding();
    return WidgetsBinding.instance;
864 865
  }
}