[flutter_svg] Adopt code excerpts (#8181)
Converts the README from unmanaged code examples to code excerpted from
analyzed and compiled code.
Part of https://github.com/flutter/flutter/issues/102679
diff --git a/script/configs/temp_exclude_excerpt.yaml b/script/configs/temp_exclude_excerpt.yaml
index 47b9639..3d39abc 100644
--- a/script/configs/temp_exclude_excerpt.yaml
+++ b/script/configs/temp_exclude_excerpt.yaml
@@ -6,8 +6,6 @@
# TODO(stuartmorgan): Remove everything from this list. See
# https://github.com/flutter/flutter/issues/102679
- espresso
-- flutter_svg
-- flutter_svg_test
- in_app_purchase/in_app_purchase
- pointer_interceptor
- quick_actions/quick_actions
diff --git a/third_party/packages/flutter_svg/CHANGELOG.md b/third_party/packages/flutter_svg/CHANGELOG.md
index 7f88983..aa5285a 100644
--- a/third_party/packages/flutter_svg/CHANGELOG.md
+++ b/third_party/packages/flutter_svg/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 2.0.16
+
+* Adopts code excerpts for README.
+
## 2.0.15
* Fixes `SvgNetworkLoader` not closing internally created http clients.
diff --git a/third_party/packages/flutter_svg/README.md b/third_party/packages/flutter_svg/README.md
index 31147a6..d4d205c 100644
--- a/third_party/packages/flutter_svg/README.md
+++ b/third_party/packages/flutter_svg/README.md
@@ -12,22 +12,24 @@
Basic usage (to create an SVG rendering widget from an asset):
+<?code-excerpt "example/lib/readme_excerpts.dart (SimpleAsset)"?>
```dart
-final String assetName = 'assets/image.svg';
+const String assetName = 'assets/dart.svg';
final Widget svg = SvgPicture.asset(
assetName,
- semanticsLabel: 'Acme Logo'
+ semanticsLabel: 'Dart Logo',
);
```
You can color/tint the image like so:
+<?code-excerpt "example/lib/readme_excerpts.dart (ColorizedAsset)"?>
```dart
-final String assetName = 'assets/up_arrow.svg';
+const String assetName = 'assets/simple/dash_path.svg';
final Widget svgIcon = SvgPicture.asset(
assetName,
- colorFilter: ColorFilter.mode(Colors.red, BlendMode.srcIn),
- semanticsLabel: 'A red up arrow'
+ colorFilter: const ColorFilter.mode(Colors.red, BlendMode.srcIn),
+ semanticsLabel: 'Red dash paths',
);
```
@@ -40,13 +42,17 @@
You can also specify a placeholder widget. The placeholder will display during
parsing/loading (normally only relevant for network access).
+<?code-excerpt "example/lib/readme_excerpts.dart (MissingAsset)"?>
```dart
// Will print error messages to the console.
-final String assetName = 'assets/image_that_does_not_exist.svg';
+const String assetName = 'assets/image_that_does_not_exist.svg';
final Widget svg = SvgPicture.asset(
assetName,
);
+```
+<?code-excerpt "example/lib/readme_excerpts.dart (AssetWithPlaceholder)"?>
+```dart
final Widget networkSvg = SvgPicture.network(
'https://site-that-takes-a-while.com/image.svg',
semanticsLabel: 'A shark?!',
@@ -58,18 +64,21 @@
If you'd like to render the SVG to some other canvas, you can do something like:
+<?code-excerpt "example/lib/readme_excerpts.dart (OutputConversion)"?>
```dart
-import 'package:flutter_svg/flutter_svg.dart';
-final String rawSvg = '''<svg ...>...</svg>''';
-final PictureInfo pictureInfo = await vg.loadPicture(SvgStringLoader(rawSvg), null);
+import 'dart:ui' as ui;
+// ···
+ const String rawSvg = '''<svg ...>...</svg>''';
+ final PictureInfo pictureInfo =
+ await vg.loadPicture(const SvgStringLoader(rawSvg), null);
-// You can draw the picture to a canvas:
-canvas.drawPicture(pictureInfo.picture);
+ // You can draw the picture to a canvas:
+ canvas.drawPicture(pictureInfo.picture);
-// Or convert the picture to an image:
-final ui.Image image = pictureInfo.picture.toImage(...);
+ // Or convert the picture to an image:
+ final ui.Image image = await pictureInfo.picture.toImage(width, height);
-pictureInfo.picture.dispose();
+ pictureInfo.picture.dispose();
```
The `SvgPicture` helps to automate this logic, and it provides some convenience
@@ -92,13 +101,11 @@
The output `foo.svg.vec` can be loaded using the default constructor of
`SvgPicture`.
+<?code-excerpt "example/lib/readme_excerpts.dart (PrecompiledAsset)"?>
```dart
-import 'package:flutter_svg/flutter_svg.dart';
import 'package:vector_graphics/vector_graphics.dart';
-
-final Widget svg = SvgPicture(
- const AssetBytesLoader('assets/foo.svg.vec')
-);
+// ···
+ const Widget svg = SvgPicture(AssetBytesLoader('assets/foo.svg.vec'));
```
### Check SVG compatibility
diff --git a/third_party/packages/flutter_svg/example/lib/readme_excerpts.dart b/third_party/packages/flutter_svg/example/lib/readme_excerpts.dart
new file mode 100644
index 0000000..fc17e62
--- /dev/null
+++ b/third_party/packages/flutter_svg/example/lib/readme_excerpts.dart
@@ -0,0 +1,103 @@
+// Copyright 2013 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.
+
+// This file exists solely to host compiled excerpts for README.md, and is not
+// intended for use as an actual example application.
+
+// #docregion OutputConversion
+import 'dart:ui' as ui;
+// #enddocregion OutputConversion
+
+import 'package:flutter/material.dart';
+import 'package:flutter_svg/flutter_svg.dart';
+// #docregion PrecompiledAsset
+import 'package:vector_graphics/vector_graphics.dart';
+// #enddocregion PrecompiledAsset
+
+/// Loads an SVG asset.
+Widget loadAsset() {
+ // #docregion SimpleAsset
+ const String assetName = 'assets/dart.svg';
+ final Widget svg = SvgPicture.asset(
+ assetName,
+ semanticsLabel: 'Dart Logo',
+ );
+ // #enddocregion SimpleAsset
+ return svg;
+}
+
+/// Loads an SVG asset.
+Widget loadColorizedAsset() {
+ // #docregion ColorizedAsset
+ const String assetName = 'assets/simple/dash_path.svg';
+ final Widget svgIcon = SvgPicture.asset(
+ assetName,
+ colorFilter: const ColorFilter.mode(Colors.red, BlendMode.srcIn),
+ semanticsLabel: 'Red dash paths',
+ );
+ // #enddocregion ColorizedAsset
+ return svgIcon;
+}
+
+/// Demonstrates loading an asset that doesn't exist.
+Widget loadMissingAsset() {
+ // #docregion MissingAsset
+ // Will print error messages to the console.
+ const String assetName = 'assets/image_that_does_not_exist.svg';
+ final Widget svg = SvgPicture.asset(
+ assetName,
+ );
+ // #enddocregion MissingAsset
+ return svg;
+}
+
+/// Demonstrates loading an asset with a placeholder.
+// This method should *not* be called in tests, as tests should not be
+// attempting to load from random uncontrolled locations. Using a real URL,
+// such as a GitHub URL pointing to this package's assets, would make the
+// README example harder to understand.
+Widget loadNetworkAssetWithPlaceholder() {
+ // #docregion AssetWithPlaceholder
+ final Widget networkSvg = SvgPicture.network(
+ 'https://site-that-takes-a-while.com/image.svg',
+ semanticsLabel: 'A shark?!',
+ placeholderBuilder: (BuildContext context) => Container(
+ padding: const EdgeInsets.all(30.0),
+ child: const CircularProgressIndicator()),
+ );
+ // #enddocregion AssetWithPlaceholder
+ return networkSvg;
+}
+
+/// Demonstrates loading a precompiled asset.
+// This asset doesn't exist in the example app, but this code can still be run
+// to sanity-check the structure of the example code.
+Widget loadPrecompiledAsset() {
+ // #docregion PrecompiledAsset
+ const Widget svg = SvgPicture(AssetBytesLoader('assets/foo.svg.vec'));
+ // #enddocregion PrecompiledAsset
+ return svg;
+}
+
+/// Demonstrates converting SVG to another type.
+Future<ui.Image> convertSvgOutput() async {
+ final Canvas canvas = Canvas(ui.PictureRecorder());
+ const int width = 100;
+ const int height = 100;
+
+ // #docregion OutputConversion
+ const String rawSvg = '''<svg ...>...</svg>''';
+ final PictureInfo pictureInfo =
+ await vg.loadPicture(const SvgStringLoader(rawSvg), null);
+
+ // You can draw the picture to a canvas:
+ canvas.drawPicture(pictureInfo.picture);
+
+ // Or convert the picture to an image:
+ final ui.Image image = await pictureInfo.picture.toImage(width, height);
+
+ pictureInfo.picture.dispose();
+ // #enddocregion OutputConversion
+ return image;
+}
diff --git a/third_party/packages/flutter_svg/example/pubspec.yaml b/third_party/packages/flutter_svg/example/pubspec.yaml
index 65f4afd..ffa1c13 100644
--- a/third_party/packages/flutter_svg/example/pubspec.yaml
+++ b/third_party/packages/flutter_svg/example/pubspec.yaml
@@ -13,6 +13,11 @@
sdk: flutter
flutter_svg:
path: ../
+ vector_graphics: ^1.1.13
+
+dev_dependencies:
+ flutter_test:
+ sdk: flutter
# The following section is specific to Flutter.
flutter:
diff --git a/third_party/packages/flutter_svg/example/test/readme_excerpts_test.dart b/third_party/packages/flutter_svg/example/test/readme_excerpts_test.dart
new file mode 100644
index 0000000..c0fee59
--- /dev/null
+++ b/third_party/packages/flutter_svg/example/test/readme_excerpts_test.dart
@@ -0,0 +1,29 @@
+// Copyright 2013 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 'package:flutter/material.dart';
+import 'package:flutter_svg_example/readme_excerpts.dart' as excerpts;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+ test('example simple loadAsset works', () async {
+ final Widget svg = excerpts.loadAsset();
+ expect(svg, isNotNull);
+ });
+
+ test('example loadAsset with color filter works', () async {
+ final Widget svg = excerpts.loadAsset();
+ expect(svg, isNotNull);
+ });
+
+ test('example loadAsset with a non-existent asset works', () async {
+ final Widget svg = excerpts.loadMissingAsset();
+ expect(svg, isNotNull);
+ });
+
+ test('example loadAsset with a precompiled asset works', () async {
+ final Widget svg = excerpts.loadPrecompiledAsset();
+ expect(svg, isNotNull);
+ });
+}
diff --git a/third_party/packages/flutter_svg/pubspec.yaml b/third_party/packages/flutter_svg/pubspec.yaml
index f08db3a..c90f9e0 100644
--- a/third_party/packages/flutter_svg/pubspec.yaml
+++ b/third_party/packages/flutter_svg/pubspec.yaml
@@ -2,7 +2,7 @@
description: An SVG rendering and widget library for Flutter, which allows painting and displaying Scalable Vector Graphics 1.1 files.
repository: https://github.com/flutter/packages/tree/main/third_party/packages/flutter_svg
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+flutter_svg%22
-version: 2.0.15
+version: 2.0.16
environment:
sdk: ^3.4.0
diff --git a/third_party/packages/flutter_svg_test/CHANGELOG.md b/third_party/packages/flutter_svg_test/CHANGELOG.md
index c8758dc..6666608 100644
--- a/third_party/packages/flutter_svg_test/CHANGELOG.md
+++ b/third_party/packages/flutter_svg_test/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.0.3
+
+* Adopts code excerpts for README.
+
## 1.0.2
* Transfers the package source from https://github.com/dnfield/flutter_svg
diff --git a/third_party/packages/flutter_svg_test/README.md b/third_party/packages/flutter_svg_test/README.md
index fbad0fc..50d2d8d 100644
--- a/third_party/packages/flutter_svg_test/README.md
+++ b/third_party/packages/flutter_svg_test/README.md
@@ -15,33 +15,42 @@
The following example shows how you can find svgs with the matching `SvgAssetLoader`.
- ```dart
-testWidgets('Finds svg', (WidgetTester widgetTester) async {
-
- final SvgPicture asset = SvgPicture.asset('/test/path/my.svg');
-
- await widgetTester.pumpWidget(asset);
-
+<?code-excerpt "test/flutter_svg_test_test.dart (ByLoader)"?>
+```dart
+testWidgets('asset svg', (WidgetTester widgetTester) async {
+ final SvgPicture asset = SvgPicture.asset('test/flutter_logo.svg');
+ await widgetTester.pumpWidget(
+ DefaultAssetBundle(
+ bundle: _FakeAssetBundle(),
+ child: asset,
+ ),
+ );
+
expect(find.svg(asset.bytesLoader), findsOneWidget);
});
```
#### Find by svg path
-Sometimes it is more convenient instead of instantiate the whole `BytesLoader` to
-compare only specific attributes.
+Sometimes it is more convenient instead of instantiating the whole `BytesLoader`
+to compare only specific attributes.
The following example shows how you can find svgs with the specified attribute.
- ```dart
+<?code-excerpt "test/flutter_svg_test_test.dart (ByPath)"?>
+```dart
testWidgets('asset svg with path', (WidgetTester widgetTester) async {
const String svgPath = 'test/flutter_logo.svg';
-
- await widgetTester.pumpWidget(SvgPicture.asset(svgPath));
-
+ await widgetTester.pumpWidget(
+ DefaultAssetBundle(
+ bundle: _FakeAssetBundle(),
+ child: SvgPicture.asset(svgPath),
+ ),
+ );
+
expect(find.svgAssetWithPath(svgPath), findsOneWidget);
});
- ```
+```
## Commemoration
diff --git a/third_party/packages/flutter_svg_test/pubspec.yaml b/third_party/packages/flutter_svg_test/pubspec.yaml
index 49bb06b..627ac2f 100644
--- a/third_party/packages/flutter_svg_test/pubspec.yaml
+++ b/third_party/packages/flutter_svg_test/pubspec.yaml
@@ -2,7 +2,7 @@
description: A testing library which makes it easy to test flutter_svg. Built to be used with the flutter_svg package.
repository: https://github.com/flutter/packages/tree/main/third_party/packages/flutter_svg_test
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+flutter_svg%22
-version: 1.0.2
+version: 1.0.3
environment:
sdk: ^3.4.0
diff --git a/third_party/packages/flutter_svg_test/test/flutter_svg_test_test.dart b/third_party/packages/flutter_svg_test/test/flutter_svg_test_test.dart
index d00ce7a..349aead 100644
--- a/third_party/packages/flutter_svg_test/test/flutter_svg_test_test.dart
+++ b/third_party/packages/flutter_svg_test/test/flutter_svg_test_test.dart
@@ -11,6 +11,7 @@
void main() {
group('finds', () {
group('with bytesLoader', () {
+ // #docregion ByLoader
testWidgets('asset svg', (WidgetTester widgetTester) async {
final SvgPicture asset = SvgPicture.asset('test/flutter_logo.svg');
await widgetTester.pumpWidget(
@@ -22,6 +23,7 @@
expect(find.svg(asset.bytesLoader), findsOneWidget);
});
+ // #enddocregion ByLoader
testWidgets('network svg', (WidgetTester widgetTester) async {
final http.Client fakeClient = _FakeHttpClient();
@@ -57,6 +59,7 @@
});
});
+ // #docregion ByPath
testWidgets('asset svg with path', (WidgetTester widgetTester) async {
const String svgPath = 'test/flutter_logo.svg';
await widgetTester.pumpWidget(
@@ -68,6 +71,7 @@
expect(find.svgAssetWithPath(svgPath), findsOneWidget);
});
+ // #enddocregion ByPath
testWidgets('network svg with url', (WidgetTester widgetTester) async {
const String svgUri = 'svg.dart';
@@ -76,7 +80,7 @@
expect(find.svgNetworkWithUrl(svgUri), findsOneWidget);
});
- testWidgets('file svg wit path', (WidgetTester widgetTester) async {
+ testWidgets('file svg with path', (WidgetTester widgetTester) async {
const String svgPath = 'test/flutter_logo.svg';
await widgetTester.pumpWidget(SvgPicture.file(File(svgPath)));