diff --git a/packages/image_picker/image_picker/CHANGELOG.md b/packages/image_picker/image_picker/CHANGELOG.md index fe845b3ab7..140efae1fb 100644 --- a/packages/image_picker/image_picker/CHANGELOG.md +++ b/packages/image_picker/image_picker/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.8.7+1 + +* Updates README to use code excerpts. + ## 0.8.7 * Adds `usePhotoPickerAndroid` options. diff --git a/packages/image_picker/image_picker/README.md b/packages/image_picker/image_picker/README.md index 3d5a11a73a..2dfb10780f 100755 --- a/packages/image_picker/image_picker/README.md +++ b/packages/image_picker/image_picker/README.md @@ -1,4 +1,5 @@ # Image Picker plugin for Flutter + [![pub package](https://img.shields.io/pub/v/image_picker.svg)](https://pub.dev/packages/image_picker) @@ -42,22 +43,20 @@ If you require your picked image to be stored permanently, it is your responsibi ### Example + ``` dart -import 'package:image_picker/image_picker.dart'; - - ... - final ImagePicker _picker = ImagePicker(); - // Pick an image - final XFile? image = await _picker.pickImage(source: ImageSource.gallery); - // Capture a photo - final XFile? photo = await _picker.pickImage(source: ImageSource.camera); - // Pick a video - final XFile? image = await _picker.pickVideo(source: ImageSource.gallery); - // Capture a video - final XFile? video = await _picker.pickVideo(source: ImageSource.camera); - // Pick multiple images - final List? images = await _picker.pickMultiImage(); - ... +final ImagePicker picker = ImagePicker(); +// Pick an image. +final XFile? image = await picker.pickImage(source: ImageSource.gallery); +// Capture a photo. +final XFile? photo = await picker.pickImage(source: ImageSource.camera); +// Pick a video. +final XFile? galleryVideo = + await picker.pickVideo(source: ImageSource.gallery); +// Capture a video. +final XFile? cameraVideo = await picker.pickVideo(source: ImageSource.camera); +// Pick multiple images. +final List images = await picker.pickMultiImage(); ``` ### Handling MainActivity destruction on Android @@ -71,17 +70,17 @@ low on memory. When the intent finishes executing, Android will restart the application. Since the data is never returned to the original call use the `ImagePicker.retrieveLostData()` method to retrieve the lost data. For example: + ```dart Future getLostData() async { - final LostDataResponse response = - await picker.retrieveLostData(); + final ImagePicker picker = ImagePicker(); + final LostDataResponse response = await picker.retrieveLostData(); if (response.isEmpty) { return; } - if (response.files != null) { - for (final XFile file in response.files) { - _handleFile(file); - } + final List? files = response.files; + if (files != null) { + _handleLostFiles(files); } else { _handleError(response.exception); } @@ -95,7 +94,7 @@ complete example of handling this flow. ### Android Photo Picker -This package has optional [Android Photo Picker](https://developer.android.com/training/data-storage/shared/photopicker) functionality. +This package has optional [Android Photo Picker](https://developer.android.com/training/data-storage/shared/photopicker) functionality. [Learn how to use it](https://pub.dev/packages/image_picker_android). ## Migrating to 0.8.2+ diff --git a/packages/image_picker/image_picker/example/build.excerpt.yaml b/packages/image_picker/image_picker/example/build.excerpt.yaml new file mode 100644 index 0000000000..e317efa11c --- /dev/null +++ b/packages/image_picker/image_picker/example/build.excerpt.yaml @@ -0,0 +1,15 @@ +targets: + $default: + sources: + include: + - lib/** + # Some default includes that aren't really used here but will prevent + # false-negative warnings: + - $package$ + - lib/$lib$ + exclude: + - '**/.*/**' + - '**/build/**' + builders: + code_excerpter|code_excerpter: + enabled: true diff --git a/packages/image_picker/image_picker/example/lib/readme_excerpts.dart b/packages/image_picker/image_picker/example/lib/readme_excerpts.dart new file mode 100644 index 0000000000..3f0f0788ae --- /dev/null +++ b/packages/image_picker/image_picker/example/lib/readme_excerpts.dart @@ -0,0 +1,54 @@ +// 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/services.dart'; +import 'package:image_picker/image_picker.dart'; + +/// Example function for README demonstration of various pick* calls. +Future> readmePickExample() async { + // #docregion Pick + final ImagePicker picker = ImagePicker(); + // Pick an image. + final XFile? image = await picker.pickImage(source: ImageSource.gallery); + // Capture a photo. + final XFile? photo = await picker.pickImage(source: ImageSource.camera); + // Pick a video. + final XFile? galleryVideo = + await picker.pickVideo(source: ImageSource.gallery); + // Capture a video. + final XFile? cameraVideo = await picker.pickVideo(source: ImageSource.camera); + // Pick multiple images. + final List images = await picker.pickMultiImage(); + // #enddocregion Pick + + // Return everything for the sanity check test. + return [ + image, + photo, + galleryVideo, + cameraVideo, + if (images.isEmpty) null else images.first + ]; +} + +/// Example function for README demonstration of getting lost data. +// #docregion LostData +Future getLostData() async { + final ImagePicker picker = ImagePicker(); + final LostDataResponse response = await picker.retrieveLostData(); + if (response.isEmpty) { + return; + } + final List? files = response.files; + if (files != null) { + _handleLostFiles(files); + } else { + _handleError(response.exception); + } +} +// #enddocregion LostData + +// Stubs for the getLostData function. +void _handleLostFiles(List file) {} +void _handleError(PlatformException? exception) {} diff --git a/packages/image_picker/image_picker/example/pubspec.yaml b/packages/image_picker/image_picker/example/pubspec.yaml old mode 100755 new mode 100644 index 81c7861575..462e582188 --- a/packages/image_picker/image_picker/example/pubspec.yaml +++ b/packages/image_picker/image_picker/example/pubspec.yaml @@ -17,9 +17,11 @@ dependencies: # The example app is bundled with the plugin so we use a path dependency on # the parent directory to use the current plugin's version. path: ../ + image_picker_platform_interface: ^2.6.1 video_player: ^2.1.4 dev_dependencies: + build_runner: ^2.1.10 espresso: ^0.2.0 flutter_driver: sdk: flutter diff --git a/packages/image_picker/image_picker/example/test/readme_excerpts_test.dart b/packages/image_picker/image_picker/example/test/readme_excerpts_test.dart new file mode 100644 index 0000000000..771d5d419d --- /dev/null +++ b/packages/image_picker/image_picker/example/test/readme_excerpts_test.dart @@ -0,0 +1,60 @@ +// 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_test/flutter_test.dart'; +import 'package:image_picker_example/readme_excerpts.dart'; +import 'package:image_picker_platform_interface/image_picker_platform_interface.dart'; + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + + setUpAll(() async { + ImagePickerPlatform.instance = FakeImagePicker(); + }); + + test('sanity check readmePickExample', () async { + // Ensure that the snippet code runs successfully. + final List results = await readmePickExample(); + // It should demonstrate a variety of calls. + expect(results.length, greaterThan(4)); + // And the calls should all be different. This works since each fake call + // returns a different result. + expect(results.map((XFile? file) => file?.path).toSet().length, + results.length); + }); + + test('sanity check getLostData', () async { + // Ensure that the snippet code runs successfully. + await getLostData(); + }); +} + +class FakeImagePicker extends ImagePickerPlatform { + @override + Future getImageFromSource( + {required ImageSource source, + ImagePickerOptions options = const ImagePickerOptions()}) async { + return XFile(source == ImageSource.camera ? 'cameraImage' : 'galleryImage'); + } + + @override + Future getLostData() async { + return LostDataResponse.empty(); + } + + @override + Future> getMultiImageWithOptions( + {MultiImagePickerOptions options = + const MultiImagePickerOptions()}) async { + return [XFile('multiImage')]; + } + + @override + Future getVideo( + {required ImageSource source, + CameraDevice preferredCameraDevice = CameraDevice.rear, + Duration? maxDuration}) async { + return XFile(source == ImageSource.camera ? 'cameraVideo' : 'galleryVideo'); + } +} diff --git a/packages/image_picker/image_picker/pubspec.yaml b/packages/image_picker/image_picker/pubspec.yaml index 68f993651a..800738b9c5 100755 --- a/packages/image_picker/image_picker/pubspec.yaml +++ b/packages/image_picker/image_picker/pubspec.yaml @@ -3,7 +3,7 @@ description: Flutter plugin for selecting images from the Android and iOS image library, and taking new pictures with the camera. repository: https://github.com/flutter/packages/tree/main/packages/image_picker/image_picker issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+image_picker%22 -version: 0.8.7 +version: 0.8.7+1 environment: sdk: ">=2.17.0 <4.0.0" diff --git a/script/configs/temp_exclude_excerpt.yaml b/script/configs/temp_exclude_excerpt.yaml index 5c3a632c3d..a2f7438478 100644 --- a/script/configs/temp_exclude_excerpt.yaml +++ b/script/configs/temp_exclude_excerpt.yaml @@ -17,7 +17,6 @@ - google_maps_flutter/google_maps_flutter - google_sign_in/google_sign_in - google_sign_in_web -- image_picker/image_picker - image_picker_for_web - in_app_purchase/in_app_purchase - ios_platform_images