As per our style guide, if you can't explain something, refactor it. I
studied this function for a while and still can't explain it, so...

Having this base class lets classes like CustomPainter and DataTableSource be
more agnostic as to what's generating the repaints.

Previously, pumpWidget() would do a partial pump (it didn't trigger
Ticker callbacks or post-frame callbacks), and pump() would do a full
pump. This patch brings them closer together. It also makes runApp run a
full actual frame, rather than skipping the transient callback part of
the frame logic. Having "half-frames" in the system was confusing and
could lead to bugs where code expecting to run before the next layout
pass didn't because a "half-frame" ran first.

Also, make Tickers start ticking in the frame that they were started in,
if they were started during a frame. This means we no longer spin a
frame for t=0, we jump straight to the first actual frame.

Other changes in this patch:

* rename WidgetsBinding._runApp to WidgetsBinding.attachRootWidget, so
  that tests can use it to more accurately mock out runApp.

* allow loadStructuredData to return synchronously.

* make handleBeginFrame handle not being given a time stamp.

* make DataPipeImageProvider.loadAsync protected (rather than private),
  and document it. There wasn't really a reason for it to be private.

* fix ImageConfiguration.toString.

* introduce debugPrintBuildScope and debugPrintScheduleBuildForStacks,
  which can help debug problems with widgets getting marked as dirty but
  not cleaned.

* make debugPrintRebuildDirtyWidgets say "Building" the first time and
  "Rebuilding" the second, to make it clearer when a widget is first
  created. This makes debugging widget lifecycle issues much easier.

* make debugDumpApp more resilient.

* debugPrintStack now takes a label that is printed before the stack.

* improve the banner shown for debugPrintBeginFrameBanner.

* various and sundry documentation fixes

Currently, we just treat Fuchsia as TargetPlatform.android, but we might
want to do something more sophisticated in the future.

Changes in this patch:
- iOS now uses a different scrollDrag constant than Android.
   - ScrollConfigurationDelegate now knows about target platforms.
   - ScrollBehaviors now know about target platforms.
   - RawInputLine now has to be told what platform it's targetting.
   - PageableList now has a concept of target platform.
- make debugPrintStack filter its stack.
   - move debugPrintStack to `assertions.dart`.
- add support for limiting the number of frames to debugPrintStack.
- make defaultTargetPlatform default to android in test environments.
- remove OverscrollStyle and MaterialApp's overscrollStyle argument. You
  can now control the overscroll style using Theme.platform.
- the default scroll configuration is now private to avoid people
  relying on the defaultTargetPlatform getter in their subclasses (since
  they really should use Theme.of(context).platform).
- fix some typos I noticed in some tests.
- added a test for flinging scrollables, that checks that the behavior
  differs on the two target platforms.
- made flingFrom and fling in the test API pump the frames.
- added more docs to the test API.
- made the TestAsyncUtils.guard() method report uncaught errors to help
  debug errors when using that API.

Also, add a "flutter build flx --report-licensed-packages" option for
when you need to get the list of the packages affected by licenses.

* Fix covariant overrides in SynchronousFuture.

There were two things going on here. In timeout(), the callback's return
type was needlessly tightened to only allow callbacks that return
futures. This makes SynchronousFuture not substitutable with Future,
whose timeout() allows callbacks that return immediate values.

Since SynchronousFuture.timeout() never calls the callback anyway, I
just loosened it to match Future.timeout().

SynchronousFuture.whenComplete() is just wrong. The type error, again,
is that the callback's return type is too tight. Future.whenComplete()
allows synchronous callbacks.

But the actual implementation is wrong as well. whenComplete() should
return a future that completes to the *original value*, not whatever the
callback returns.

So I just fixed the method to work correctly, including handling
callbacks with synchronous results.

* "(error, stackTrace)" -> "(e, stack)".

Adds Scheduler.debugPrintTransientCallbackRegistrationStack so that you
can find out how your current callback got registered.

* General improvoments to the loader app:
   * Show a message after 8 seconds if no connection comes in.
   * Show a progress bar as files are being uploaded.
   * Hide the spinner just before launching the application.

* General improvements to the "flutter run" UI:
   * Add "?" key as a silent alias for "h".
   * Make the help text bold so it doesn't get mixed with the logs.
   * Make "R" do a cold restart when hot reload is enabled.

* Supporting features and bug fixes:
   * Add support for string service extensions.

* Other bug fixes:
   * Expose debugDumpRenderTree() outside debug mode.
   * Logger.supportsColor was missing a getter.
   * Mention in the usage docs that --hot requires --resident.
   * Trivial style fixes.

Fixes https://github.com/flutter/flutter/issues/5086

- show the next error fully after a hot reload
- hide _AssertionError in stacks
- immediately rebuild after a reassemble, so that hit tests work
- catch errors when notifying global key listeners

We'll use this field to adapt material widgets to iOS.

This makes the about page show the licenses of all the Dart packages that a Flutter app uses.

Issues that this does not yet resolve:
- I'm still working on getting the full list of licenses for the sky_engine package.
- Some of the licenses don't print very readably.
- There's no scrollbar on the license page.

I'll provide fixes for the first two in the coming days, but this should unblock anyone who is wanting to see something here, even if it's not quite complete. :-)

----

The patch makes the following changes: 

- The license registry is now asynchronous, since the data comes from disk.
- I moved the default license collector from the foundation package to the services package since it uses the default asset bundle now.
- The FLX builder now includes the LICENSE files of each Dart package mentioned in the `.packages` file.

This patch improves some subtle behaviors about the change notifier.

Overview
========

This patch refactors images to achieve the following goals:

* it allows references to unresolved assets to be passed
  around (previously, almost every layer of the system had to know about
  whether an image came from an asset bundle or the network or
  elsewhere, and had to manually interact with the image cache).

* it allows decorations to use the same API for declaring images as the
  widget tree.

It requires some minor changes to call sites that use images, as
discussed below.

Widgets
-------

Change this:

```dart
      child: new AssetImage(
        name: 'my_asset.png',
        ...
      )
```

...to this:

```dart
      child: new Image(
        image: new AssetImage('my_asset.png'),
        ...
      )
```

Decorations
-----------

Change this:

```dart
      child: new DecoratedBox(
        decoration: new BoxDecoration(
          backgroundImage: new BackgroundImage(
            image: DefaultAssetBundle.of(context).loadImage('my_asset.png'),
            ...
          ),
          ...
        ),
        child: ...
      )
```

...to this:

```dart
      child: new DecoratedBox(
        decoration: new BoxDecoration(
          backgroundImage: new BackgroundImage(
            image: new AssetImage('my_asset.png'),
            ...
          ),
          ...
        ),
        child: ...
      )
```

DETAILED CHANGE LOG
===================

The following APIs have been replaced in this patch:

* The `AssetImage` and `NetworkImage` widgets have been split in two,
  with identically-named `ImageProvider` subclasses providing the
  image-loading logic, and a single `Image` widget providing all the
  widget tree logic.

* `ImageResource` is now `ImageStream`. Rather than configuring it with
  a `Future<ImageInfo>`, you complete it with an `ImageStreamCompleter`.

* `ImageCache.load` and `ImageCache.loadProvider` are replaced by
  `ImageCache.putIfAbsent`.

The following APIs have changed in this patch:

* `ImageCache` works in terms of arbitrary keys and caches
  `ImageStreamCompleter` objects using those keys. With the new model,
  you should never need to interact with the cache directly.

* `Decoration` can now be `const`. The state has moved to the
  `BoxPainter` class. Instead of a list of listeners, there's now just a
  single callback and a `dispose()` method on the painter. The callback
  is passed in to the `createBoxPainter()` method. When invoked, you
  should repaint the painter.

The following new APIs are introduced:

* `AssetBundle.loadStructuredData`.

* `SynchronousFuture`, a variant of `Future` that calls the `then`
  callback synchronously. This enables the asynchronous and
  synchronous (in-the-cache) code paths to look identical yet for the
  latter to avoid returning to the event loop mid-paint.

* `ExactAssetImage`, a variant of `AssetImage` that doesn't do anything clever.

* `ImageConfiguration`, a class that describes parameters that configure
  the `AssetImage` resolver.

The following APIs are entirely removed by this patch:

* `AssetBundle.loadImage` is gone. Use an `AssetImage` instead.

* `AssetVendor` is gone. `AssetImage` handles everything `AssetVendor`
  used to handle.

* `RawImageResource` and `AsyncImage` are gone.

The following code-level changes are performed:

* `Image`, which replaces `AsyncImage`, `NetworkImage`, `AssetImage`,
  and `RawResourceImage`, lives in `image.dart`.

* `DecoratedBox` and `Container` live in their own file now,
  `container.dart` (they reference `image.dart`).

DIRECTIONS FOR FUTURE RESEARCH
==============================

* The `ImageConfiguration` fields are mostly aspirational. Right now
  only `devicePixelRatio` and `bundle` are implemented. `locale` isn't
  even plumbed through, it will require work on the localisation logic.

* We should go through and make `BoxDecoration`, `AssetImage`, and
  `NetworkImage` objects `const` where possible.

* This patch makes supporting animated GIFs much easier.

* This patch makes it possible to create an abstract concept of an
  "Icon" that could be either an image or a font-based glyph (using
  `IconData` or similar). (see
  https://github.com/flutter/flutter/issues/4494)

RELATED ISSUES
==============

Fixes https://github.com/flutter/flutter/issues/4500
Fixes https://github.com/flutter/flutter/issues/4495
Obsoletes https://github.com/flutter/flutter/issues/4496

This introduces the key parts of a paginated data table, not including
the built-in pagination features.

* Provide more data for the data table demo, so there's data to page.

* Introduce a ChangeNotifier class which abstracts out
  addListener/removeListener/notifyListeners. We might be able to use
  this to simplify existing classes as well, though this patch doesn't
  do that.

* Introduce DataTableSource, a delegate for getting data for data
  tables. This will also be used by ScrollingDataTable in due course.

* Introduce PaginatedDataTable, a widget that wraps DataTable and only
  shows N rows at a time, fed by a DataTableSource.

For consistency.

Fixes #4142

Don't suggest filing an issue when we can definitively say that the
assertion in question was not thrown from within the flutter package.
Fixes https://github.com/flutter/flutter/issues/3812.

Put the stack trace first after the message, with more details below the
stack trace, since the stack is often very useful and the stacks are no
longer stupidly long.

Better document the 'rescheduling' feature, and improve the error
handling asserts when it is misused.
Fixes https://github.com/flutter/flutter/issues/3888.

Improve the wording around the stack dump for exceptions during
callbacks.

Improve the color and font size of messages in live tests.
Fixes https://github.com/flutter/flutter/issues/4018.

Also, add some missing docs to http.dart and widgets.dart.

Everything now has dartdocs except one setter whose getter already has
docs.

This exposes the default throttling implementation, and an alternative
non-throttling implementation, of `debugPrint`.

This makes it possible to substitute 'flutter run' for 'flutter test'
and actually watch a test run on a device.

For any test that depends on flutter_test:

1. Remove any import of 'package:test/test.dart'.

2. Replace `testWidgets('...', (WidgetTester tester) {`
      with `testWidgets('...', (WidgetTester tester) async {`

3. Add an "await" in front of calls to any of the following:
    * tap()
    * tapAt()
    * fling()
    * flingFrom()
    * scroll()
    * scrollAt()
    * pump()
    * pumpWidget()

4. Replace any calls to `tester.flushMicrotasks()` with calls to
   `await tester.idle()`.

There's a guarding API that you can use, if you have particularly
complicated tests, to get better error messages. Search for
TestAsyncUtils.

* send debug events for flutter lifecycle events

* remove the route event

The `flutter` package gets more types!

Follow-up from: https://github.com/flutter/flutter/pull/3727.

* Refactor widget test framework

Instead of:

```dart
  test("Card Collection smoke test", () {
    testWidgets((WidgetTester tester) {
```

...you now say:

```dart
  testWidgets("Card Collection smoke test", (WidgetTester tester) {
```

Instead of:

```dart
  expect(tester, hasWidget(find.text('hello')));
```

...you now say:

```dart
  expect(find.text('hello'), findsOneWidget);
```

Instead of the previous API (exists, widgets, widget, stateOf,
elementOf, etc), you now have the following comprehensive API. All these
are functions that take a Finder, except the all* properties.

* `any()` - true if anything matches, c.f. `Iterable.any`
* `allWidgets` - all the widgets in the tree
* `widget()` - the one and only widget that matches the finder
* `firstWidget()` - the first widget that matches the finder
* `allElements` - all the elements in the tree
* `element()` - the one and only element that matches the finder
* `firstElement()` - the first element that matches the finder
* `allStates` - all the `State`s in the tree
* `state()` - the one and only state that matches the finder
* `firstState()` - the first state that matches the finder
* `allRenderObjects` - all the render objects in the tree
* `renderObject()` - the one and only render object that matches the finder
* `firstRenderObject()` - the first render object that matches the finder

There's also `layers' which returns the list of current layers.

`tap`, `fling`, getCenter, getSize, etc, take Finders, like the APIs
above, and expect there to only be one matching widget.

The finders are:

 * `find.text(String text)`
 * `find.widgetWithText(Type widgetType, String text)`
 * `find.byKey(Key key)`
 * `find.byType(Type type)`
 * `find.byElementType(Type type)`
 * `find.byConfig(Widget config)`
 * `find.byWidgetPredicate(WidgetPredicate predicate)`
 * `find.byElementPredicate(ElementPredicate predicate)`

The matchers (for `expect`) are:

 * `findsNothing`
 * `findsWidgets`
 * `findsOneWidget`
 * `findsNWidgets(n)`
 * `isOnStage`
 * `isOffStage`
 * `isInCard`
 * `isNotInCard`

Benchmarks now use benchmarkWidgets instead of testWidgets.

Also, for those of you using mockers, `serviceMocker` now automatically
handles the binding initialization.

This patch also:

* changes how tests are run so that we can more easily swap the logic
  out for a "real" mode instead of FakeAsync.

* introduces CachingIterable.

* changes how flutter_driver interacts with the widget tree to use the
  aforementioned new API rather than ElementTreeTester, which is gone.

* removes ElementTreeTester.

* changes the semantics of a test for scrollables because we couldn't
  convince ourselves that the old semantics made sense; it only worked
  before because flushing the microtasks after every event was broken.

* fixes the flushing of microtasks after every event.

* Reindent the tests

* Fix review comments

This adds in particular the ability to track the time at which the
framework boots up, and the time at which we are confident we have
completed the first useful frame.

The old names were getting silly and started stepping on valuable namespace.

The new names are consistent and clear.

Bindings now have a debugRegisterServiceExtensions() method that is
invoked in debug mode (only). (Once we have a profile mode, there'll be
a registerProfileServiceExtensions() method that gets called in that
mode only to register extensions that apply then.)

The BindingBase class provides convenience methods for registering
service extensions that do the equivalent of:

```dart
void extension() { ... }
bool extension([bool enabled]) { ... }
double extension([double extension])  { ... }
Map<String, String> extension([Map<String, String> parameters]) { ... }
```

The BindingBase class also itself registers ext.flutter.reassemble,
which it has call a function on the binding called
reassembleApplication().

The Scheduler binding now exposes the preexisting
ext.flutter.timeDilation.

The Renderer binding now exposes the preexisting ext.flutter.debugPaint.

The Renderer binding hooks reassembleApplication to trigger the
rendering tree to be reprocessed (in particular, to fix up the
optimisation closures).

All the logic from rendering/debug.dart about service extensions is
replaced by the above.

I moved basic_types to foundation.

The FlutterWidgets binding hooks reassembleApplication to trigger the
widget tree to be entirely rebuilt.

Flutter Driver now uses ext.flutter.driver instead of
ext.flutter_driver, and is hooked using the same binding mechanism.
Eventually we'll probably move the logic into the Flutter library so
that you just get it without having to invoke a special method first.

Fixes https://github.com/flutter/flutter/issues/3352

We're getting back to the point where we have a bunch of foundation APIs
and it's getting confusing having them mixed with services/.