Skip to content

Commit

Permalink
Adjust readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@SimonWeidemann
SimonWeidemann committed Apr 10, 2023
1 parent ee0eaba commit e10d531
Show file tree
Hide file tree
Showing 7 changed files with 53 additions and 210 deletions.
164 changes: 11 additions & 153 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,132 +8,24 @@

Draw SVG files using Flutter.

## Getting Started
## Overview

This package provides a wrapper around Dart implementations of SVG parsing,
This library consists of two packages:
[**flutter_svg** ](https://github.com/dnfield/flutter_svg/tree/master/packages/flutter_svg)
and
[**flutter_svg_test** ](https://github.com/dnfield/flutter_svg/tree/master/packages/flutter_svg_test).

[flutter_svg](https://github.com/dnfield/flutter_svg/tree/master/packages/flutter_svg_test)
provides a wrapper around Dart implementations of SVG parsing,
including SVG path data. In particular, it provides efficient `BytesLoader`
implementations for [`package:vector_graphics`](https://pub.dev/packages/vector_graphics).
This package is easier to use but not as performant as using the
Ths package is easier to use but not as performant as using the
`vector_graphics` and `vector_graphics_compiler` packages directly. Those
packages allow you to do ahead-of-time compilation and optimization of SVGs,
and offer some more performant rasterization strategies at runtime.

Basic usage (to create an SVG rendering widget from an asset):

```dart
final String assetName = 'assets/image.svg';
final Widget svg = SvgPicture.asset(
assetName,
semanticsLabel: 'Acme Logo'
);
```

You can color/tint the image like so:

```dart
final String assetName = 'assets/up_arrow.svg';
final Widget svgIcon = SvgPicture.asset(
assetName,
colorFilter: ColorFilter.mode(Colors.red, BlendMode.srcIn),
semanticsLabel: 'A red up arrow'
);
```

The default placeholder is an empty box (`LimitedBox`) - although if a `height`
or `width` is specified on the `SvgPicture`, a `SizedBox` will be used instead
(which ensures better layout experience). There is currently no way to show an
Error visually, however errors will get properly logged to the console in debug
mode.

You can also specify a placeholder widget. The placeholder will display during
parsing/loading (normally only relevant for network access).

```dart
// Will print error messages to the console.
final String assetName = 'assets/image_that_does_not_exist.svg';
final Widget svg = SvgPicture.asset(
assetName,
);
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()),
);
```

If you'd like to render the SVG to some other canvas, you can do something like:

```dart
import 'package:flutter_svg/flutter_svg.dart';
final String rawSvg = '''<svg ...>...</svg>''';
final PictureInfo pictureInfo = await vg.loadPicture(SvgStringLoader(rawSvg), null);
// You can draw the picture to a canvas:
canvas.drawPicture(pictureInfo.picture);
// Or convert the picture to a an image:
final ui.Image image = pictureInfo.picture.toImage(...);
pictureInfo.picture.dispose();
```

The `SvgPicture` helps to automate this logic, and it provides some convenience
wrappers for getting assets from multiple sources. Unlike the `vector_graphics`
package, this package _does not render the data to an `Image` at any point_.
This carries a performance penalty for some common use cases, but also allows
for more flexibility around scaling.

See [main.dart](/../master/example/lib/main.dart) for a complete sample.

## Precompiling and Optimizing SVGs

The vector_graphics backend supports SVG compilation which produces a binary
format that is faster to parse and can optimize SVGs to reduce the amount of
clipping, masking, and overdraw. The SVG compilation is provided by
[`package:vector_graphics_compiler`](https://pub.dev/packages/vector_graphics_compiler).

```sh
dart run vector_graphics_compiler -i assets/foo.svg -o assets/foo.svg.vec
```

The output `foo.svg.vec` can be loaded using the default constructor of
`SvgPicture`.

```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')
);
```

### Check SVG compatibility

An SVG can be tested for compatibility with the vector graphics backend by
running the compiler locally to see if any errors are thrown.

```sh
dart run vector_graphics_compiler -i $SVG_FILE -o $TEMPORARY_OUTPUT_TO_BE_DELETED --no-optimize-masks --no-optimize-clips --no-optimize-overdraw --no-tessellate
```

### Testing

For testing this api provides a find extension function.

```dart
import 'package:flutter_svg/flutter_svg_test_helper.dart';
import 'package:flutter_svg/svg.dart';
import 'package:flutter_test/flutter_test.dart';
testWidgets('Finds svg', (WidgetTester widgetTester) async {
final SvgPicture asset = SvgPicture.asset('/test/path/my.svg');
await widgetTester.pumpWidget(asset);
expect(find.svg(asset.bytesLoader), findsOneWidget);
});
```
[**flutter_svg_test** ](https://github.com/dnfield/flutter_svg/tree/master/packages/flutter_svg_test)
provides a set of functions to find images generated by `flutter_svg` in widget tests.

## Out of scope/non-goals

Expand All @@ -145,40 +37,6 @@ testWidgets('Finds svg', (WidgetTester widgetTester) async {
- Foreign elements
- Rendering properties/hints

## Recommended Adobe Illustrator SVG Configuration
- In Styling: choose Presentation Attributes instead of Inline CSS because CSS is not fully supported.
- In Images: choose Embded not Linked to other file to get a single svg with no dependency to other files.
- In Objects IDs: choose layer names to add every layer name to svg tags or you can use minimal,it is optional.
![Export configuration](https://user-images.githubusercontent.com/2842459/62599914-91de9c00-b8fe-11e9-8fb7-4af57d5100f7.png)

## SVG sample attribution

SVGs in `/assets/w3samples` pulled from [W3 sample files](https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/)

SVGs in `/assets/deborah_ufw` provided by @deborah-ufw

SVGs in `/assets/simple` are pulled from trivial examples or generated to test
basic functionality - some of them come directly from the SVG 1.1 spec. Some
have also come or been adapted from issues raised in this repository.

SVGs in `/assets/wikimedia` are pulled from [Wikimedia Commons](https://commons.wikimedia.org/wiki/Main_Page)

Android Drawables in `/assets/android_vd` are pulled from Android Documentation
and examples.

The Flutter Logo created based on the Flutter Logo Widget © Google.

The Dart logo is from
[dartlang.org](https://github.com/dart-lang/site-shared/blob/master/src/_assets/images/dart/logo%2Btext/horizontal/original.svg)
© Google

SVGs in `/assets/noto-emoji` are from [Google i18n noto-emoji](https://github.com/googlei18n/noto-emoji),
licensed under the Apache license.

Please submit SVGs that can't render properly (e.g. that don't render here the
way they do in chrome), as long as they're not using anything "probably out of
scope" (above).

## Alternatives

- [vector_graphics](https://pub.dev/packages/vector_graphics) which powers this package.
Expand Down
25 changes: 0 additions & 25 deletions packages/flutter_svg/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,6 @@ Draw SVG files using Flutter.

## Getting Started

This package provides a wrapper around Dart implementations of SVG parsing,
including SVG path data. In particular, it provides efficient `BytesLoader`
implementations for [`package:vector_graphics`](https://pub.dev/packages/vector_graphics).
This package is easier to use but not as performant as using the
`vector_graphics` and `vector_graphics_compiler` packages directly. Those
packages allow you to do ahead-of-time compilation and optimization of SVGs,
and offer some more performant rasterization strategies at runtime.

Basic usage (to create an SVG rendering widget from an asset):

```dart
Expand Down Expand Up @@ -120,16 +112,6 @@ running the compiler locally to see if any errors are thrown.
dart run vector_graphics_compiler -i $SVG_FILE -o $TEMPORARY_OUTPUT_TO_BE_DELETED --no-optimize-masks --no-optimize-clips --no-optimize-overdraw --no-tessellate
```

## Out of scope/non-goals

- SMIL animations. That just seems crazy. I think it'll be possible to animate
the SVG but probably in a more Flutter driven way.
- Interactivity/events in SVG.
- Any CSS support - preprocess your SVGs (perhaps with [usvg](https://github.com/RazrFalcon/resvg/tree/master/usvg) or [scour](https://github.com/scour-project/scour) to get rid of all CSS?).
- Scripting in SVGs
- Foreign elements
- Rendering properties/hints

## Recommended Adobe Illustrator SVG Configuration
- In Styling: choose Presentation Attributes instead of Inline CSS because CSS is not fully supported.
- In Images: choose Embded not Linked to other file to get a single svg with no dependency to other files.
Expand Down Expand Up @@ -163,10 +145,3 @@ licensed under the Apache license.
Please submit SVGs that can't render properly (e.g. that don't render here the
way they do in chrome), as long as they're not using anything "probably out of
scope" (above).

## Alternatives

- [vector_graphics](https://pub.dev/packages/vector_graphics) which powers this package.
- [Rive](https://rive.app/) supports importing SVGs and animating vector graphics.
- [FlutterShapeMaker](https://fluttershapemaker.com) supports converting SVGs to [CustomPaint](https://api.flutter.dev/flutter/widgets/CustomPaint-class.html) widgets.
- [Jovial SVG](https://pub.dev/packages/jovial_svg) supports a slightly different feature set and a fast binary format.
46 changes: 37 additions & 9 deletions packages/flutter_svg_test/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,44 @@
# flutter_svg_test

A new Flutter project.
### Testing

## Getting Started
This package provides a set of functions to find images generated by
[**flutter_svg** ](https://github.com/dnfield/flutter_svg/tree/master/packages/flutter_svg)
in widget tests.

This project is a starting point for a Flutter application.
The methods find elements with the `SvgPicture` type and compare either the `BytesLoader` or the
configuration of the `BytesLoader` with the giving test attribute.

A few resources to get you started if this is your first Flutter project:
### Example

- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
#### Find by BytesLoader

For help getting started with Flutter development, view the
[online documentation](https://docs.flutter.dev/), which offers tutorials,
samples, guidance on mobile development, and a full API reference.
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);
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.

The following example shows how you can find svgs with the specified attribute.

```dart
testWidgets('asset svg with path', (WidgetTester widgetTester) async {
const String svgPath = 'test/flutter_logo.svg';
await widgetTester.pumpWidget(SvgPicture.asset(svgPath));
expect(find.svgAssetWithPath(svgPath), findsOneWidget);
});
```
17 changes: 0 additions & 17 deletions packages/flutter_svg_test/flutter_svg_test.iml
View file

This file was deleted.

8 changes: 4 additions & 4 deletions packages/flutter_svg_test/lib/flutter_svg_test.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ extension CommonFinderExt on CommonFinders {
/// ```dart
/// expect(svgAssetWithPath('assets/asset_name.svg'), findsOneWidget);
/// ```
/// This will match one [SvgPicture.asset] with the [path] 'assets/asset_name.svg'.
/// This will match [SvgPicture.asset] with the [path] 'assets/asset_name.svg'.
/// If the `skipOffstage` argument is true (the default), then this skips
/// nodes that are [Offstage] or that are from inactive [Route]s.
Finder svgAssetWithPath(String path, {bool skipOffstage = true}) {
Expand All @@ -36,7 +36,7 @@ extension CommonFinderExt on CommonFinders {
/// ```dart
/// expect(find.svgNetworkWithUrl('https://svg.dart'), findsOneWidget);
/// ```
/// This will match one [SvgPicture.network] with the [url] https://svg.dart'.
/// This will match [SvgPicture.network] with the [url] https://svg.dart'.
/// If the `skipOffstage` argument is true (the default), then this skips
/// nodes that are [Offstage] or that are from inactive [Route]s.
Finder svgNetworkWithUrl(String url, {bool skipOffstage = true}) {
Expand All @@ -49,7 +49,7 @@ extension CommonFinderExt on CommonFinders {
/// const Uint8List svgBytes = [1, 2, 3, 4];
/// expect(find.svgMemoryWithBytes(svgBytes), findsOneWidget);
/// ```
/// This will match one [SvgPicture.memory] with the [bytes] [1,2,3,4].
/// This will match [SvgPicture.memory] with the [bytes] [1,2,3,4].
/// If the `skipOffstage` argument is true (the default), then this skips
/// nodes that are [Offstage] or that are from inactive [Route]s.
Finder svgMemoryWithBytes(Uint8List bytes, {bool skipOffstage = true}) {
Expand All @@ -61,7 +61,7 @@ extension CommonFinderExt on CommonFinders {
/// ```dart
/// expect(find.svgFileWithPath('test/flutter_logo.svg'), findsOneWidget);
/// ```
/// This will match one [SvgPicture.file] with the [path] 'test/flutter_logo.svg'.
/// This will match [SvgPicture.file] with the [path] 'test/flutter_logo.svg'.
/// If the `skipOffstage` argument is true (the default), then this skips
/// nodes that are [Offstage] or that are from inactive [Route]s.
Finder svgFileWithPath(String path, {bool skipOffstage = true}) {
Expand Down
1 change: 0 additions & 1 deletion packages/flutter_svg_test/lib/svg_test.dart
View file

This file was deleted.

2 changes: 1 addition & 1 deletion packages/flutter_svg_test/test/flutter_svg_test_test.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import 'dart:typed_data';

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';
import 'package:flutter_svg_test/svg_test.dart';
import 'package:flutter_svg_test/flutter_svg_test.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
Expand Down

0 comments on commit e10d531

Please sign in to comment.