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 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.
It's safe to remove the unneeded `void`s from setters since the blocking issues in the
`always_declare_return_types` lint have been fixed (https://github.com/dart-lang/linter/). We can also safely flip the bit on `avoid_return_types_on_setters`.
I ran into a case where I was setting minHeight=∞ and then calling
layout() with that constraint, which is all kinds of bad. To try to
catch this earlier, this patch now provides a way to catch constraints
that are requiring infinite values.
We don't _always_ check this because there are valid uses for
BoxConstraints.biggest, e.g. as an additionalConstraint.
Each layer is supposed to reexport the parts of the previous layer
that are part of its API.
- In painting.dart, export from dart:ui all the Canvas-related APIs
that make sense to be used at higher levels, e.g. PaintingStyle.
- Delete painting/shadows.dart. It was dead code.
- In rendering/object.dart, export all of painting.dart.
- In widgets/basic.dart, export all of painting.dart and
animation.dart. Some classes in animation/ are renamed to make this
less disruptive and confusing to the namespace.
- Split out Stocks back into an import model rather than a part model,
so that it's easier to manage its dependencies on a per-file basis.
- Move Ticker to scheduler library.
- Remove as many redundant imports as possible now.
- Some minor nit picking cleanup in various files.
The asserting will continue until morale improves!
* Convert all assert(*.isNormalized) checks to use the new
debugAssertIsNormalized technology.
* Convert CustomMultiChildLayout to use the new RenderingError
technology to greatly improve the detail in errors you get when
writing CustomMultiChildLayout delegates.
* Add BoxConstraints.copyWith().
* Indent the descendants in the rendering exception data dump so that
when you have multiple children it's clearer what's going on.
- Add RenderFractionalTranslation, a render box that does a
translation based on a FractionalOffset.
- Make FractionalOffset more like Offset
- dx/dy instead of x/y
- add /, ~/, %
- add .zero
- Add alongOffset and alongSize to FractionalOffset so that you can
easily apply FractionalOffset to Offsets and Sizes. (Better name
suggestions welcome.)
- Add transformHitTests boolean to RenderTransform (also on
RenderFractionalTranslation), and to classes based on it.
- Remove the fade from Dismissable. We can add it back using the
builder-with-child pattern like Draggable if we need it. See #1003
for tha feature request.
- Rename a bunch of variables in dismissable.dart.
- Change the test for dismissable to not handle leftwards dismisses
one pixel different from rightwards dismisses, and cleaned up the
resulting effect on the test (mostly making sure we had the right
number of pumps, with comments explaining what each one was).
Fixes#174.
- Adds dartdoc for all the `of` functions.
- Renames Image to RawImage. This widget is rarely used and shouldn't take up
such a nice global name.
Fixes#361
Add BoxConstraints.isNormalized feature.
Use this feature in asserts in all the intrinsic dimension methods, in
various relevant BoxConstraints methods, and in layout().
Wrap the _DebugSize logic in BoxConstraints.constrain() in an assert
block to avoid a branch in release mode.
Remove the logic in BoxConstraints.isSatisfiedBy() that dealt with
non-normalized values.
Add BoxConstraints.normalize().
Make RenderCustomOneChildLayoutBox.performLayout() only set
parentUsesSize on the child if the constraints aren't tight.
Now a RenderBox is considered hit if one of its children are hit or it itself
decides that it's hit. In particular, empty space inside a flex won't be hit
because none of the children are located there and a RenderFlex doesn't
consider itself hittable.
Fixes#53Fixes#1221
- change how we expose settings at the RenderObject layer so that it's
easier to maintain.
- expose the Widget owner chain in the RenderObject layer debug output
- add debug info to RenderOpacity, RenderIgnorePointer, RenderListener
- make the output for text nodes prettier
Add type annotations in many places.
Fix some identifiers to have more lint-satisfying names.
Make all operator==s consistent in style.
Reorder some functions for consistency.
Make ParentData no longer dynamic, and fix all the code around that.
Now that you import a top-level file for each layer of the Flutter
framework, within the framework we can use relative paths without being
worried about the copy/pasta problem we used to have.
Turns out many of the functions on BoxConstraints weren't used or had callers
that could easily be updated to other functions. I've added dartdoc to all the
public functions as well as renamed some functions that had similar names but
did different things.
Code outside of package:sky should import this code using
package:sky/rendering.dart
package:sky/widgets.dart
Moving this code into the "src" directory is a convention that signifies that
and it cleans up the generated dartdoc because the libraries in the src
directory aren't included in the generated documentation. Instead, the classes
are documented in the widgets.dart and rendering.dart libraries.
