[image_picker] Migrate image_picker to package:cross_file

packages/image_picker/image_picker/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.8.2
+
+* Added new methods that return `package:cross_file` `XFile` instances. [Docs](https://pub.dev/documentation/cross_file/latest/index.html).
+* Deprecate methods that return `PickedFile` instances:
+  * `getImage`: use **`pickImage`** instead.
+  * `getVideo`: use **`pickVideo`** instead.
+  * `getMultiImage`: use **`pickMultiImage`** instead.
+  * `getLostData`: use **`retrieveLostData`** instead.
+
 ## 0.8.1+4
 
 * Fixes an issue where `preferredCameraDevice` option is not working for `getVideo` method.

packages/image_picker/image_picker/README.md

@@ -12,7 +12,7 @@ First, add `image_picker` as a [dependency in your pubspec.yaml file](https://fl
 ### iOS
 
 Starting with version **0.8.1** the iOS implementation uses PHPicker to pick (multiple) images on iOS 14 or higher.
-As a result of implementing PHPicker it becomes impossible to pick HEIC images on the iOS simulator in iOS 14+. This is a known issue. Please test this on a real device, or test with non-HEIC images until Apple solves this issue.[63426347 - Apple known issue](https://www.google.com/search?q=63426347+apple&sxsrf=ALeKk01YnTMid5S0PYvhL8GbgXJ40ZS[…]t=gws-wiz&ved=0ahUKEwjKh8XH_5HwAhWL_rsIHUmHDN8Q4dUDCA8&uact=5) 
+As a result of implementing PHPicker it becomes impossible to pick HEIC images on the iOS simulator in iOS 14+. This is a known issue. Please test this on a real device, or test with non-HEIC images until Apple solves this issue.[63426347 - Apple known issue](https://www.google.com/search?q=63426347+apple&sxsrf=ALeKk01YnTMid5S0PYvhL8GbgXJ40ZS[…]t=gws-wiz&ved=0ahUKEwjKh8XH_5HwAhWL_rsIHUmHDN8Q4dUDCA8&uact=5)
 
 Add the following keys to your _Info.plist_ file, located in `<project root>/ios/Runner/Info.plist`:
 
@@ -37,7 +37,19 @@ If you require your picked image to be stored permanently, it is your responsibi
 import 'package:image_picker/image_picker.dart';
 
     ...
-    final PickedFile? pickedFile = await picker.getImage(source: ImageSource.camera);
+    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? photo = await _picker.pickVideo(source: ImageSource.camera);
+    // Pick multiple images
+    final List<XFile>? images = await _picker.pickMultiImage(source: ImageSource.gallery);
+    // Pick multiple photos
+    final List<XFile>? photos = await _picker.pickMultiImage(source: ImageSource.camera);
     ...
 ```
 
@@ -46,9 +58,9 @@ import 'package:image_picker/image_picker.dart';
 Android system -- although very rarely -- sometimes kills the MainActivity after the image_picker finishes. When this happens, we lost the data selected from the image_picker. You can use `retrieveLostData` to retrieve the lost data in this situation. For example:
 
 ```dart
-Future<void> retrieveLostData() async {
-  final LostData response =
-      await picker.getLostData();
+Future<void> getLostData() async {
+  final LostDataResponse response =
+      await picker.retrieveLostData();
   if (response.isEmpty) {
     return;
   }
@@ -68,65 +80,17 @@ Future<void> retrieveLostData() async {
 
 There's no way to detect when this happens, so calling this method at the right place is essential. We recommend to wire this into some kind of start up check. Please refer to the example app to see how we used it.
 
-On Android, `getLostData` will only get the last picked image when picking multiple images, see: [#84634](https://github.com/flutter/flutter/issues/84634).
+On Android, `retrieveLostData` will only get the last picked image when picking multiple images, see: [#84634](https://github.com/flutter/flutter/issues/84634).
 
-## Deprecation warnings in `pickImage`, `pickVideo` and `LostDataResponse`
+## Migrating to 0.8.2+
 
-Starting with version **0.6.7** of the image_picker plugin, the API of the plugin changed slightly to allow for web implementations to exist.
-
-The **old methods that returned `dart:io` File objects were marked as deprecated**, and a new set of methods that return [`PickedFile` objects](https://pub.dev/documentation/image_picker_platform_interface/latest/image_picker_platform_interface/PickedFile-class.html) were introduced.
-
-### How to migrate from to ^0.6.7
-
-#### Instantiate the `ImagePicker`
-
-The new ImagePicker API does not rely in static methods anymore, so the first thing you'll need to do is to create a new instance of the plugin where you need it:
-
-```dart
-final _picker = ImagePicker();
-```
+Starting with version **0.8.2** of the image_picker plugin, new methods have been added for picking files that return `XFile` instances (from the [cross_file](https://pub.dev/packages/cross_file) package) rather than the plugin's own `PickedFile` instances. While the previous methods still exist, it is already recommended to start migrating over to their new equivalents. Eventually, `PickedFile` and the methods that return instances of it will be deprecated and removed.
 
 #### Call the new methods
 
-The new methods **receive the same parameters as before**, but they **return a `PickedFile`, instead of a `File`**. The `LostDataResponse` class has been replaced by the [`LostData` class](https://pub.dev/documentation/image_picker_platform_interface/latest/image_picker_platform_interface/LostData-class.html).
-
 | Old API | New API |
 |---------|---------|
-| `File image = await ImagePicker.pickImage(...)` | `PickedFile image = await _picker.getImage(...)` |
-| `File video = await ImagePicker.pickVideo(...)` | `PickedFile video = await _picker.getVideo(...)` |
-| `LostDataResponse response = await ImagePicker.retrieveLostData()` | `LostData response = await _picker.getLostData()` |
-
-#### `PickedFile` to `File`
-
-If your app needs dart:io `File` objects to operate, you may transform `PickedFile` to `File` like so:
-
-```dart
-final pickedFile = await _picker.getImage(...);
-final File file = File(pickedFile.path);
-```
-
-You may also retrieve the bytes from the pickedFile directly if needed:
-
-```dart
-final bytes = await pickedFile.readAsBytes();
-```
-
-#### Getting ready for the web platform
-
-Note that on the web platform (`kIsWeb == true`), `File` is not available, so the `path` of the `PickedFile` will point to a network resource instead:
-
-```dart
-if (kIsWeb) {
-  image = Image.network(pickedFile.path);
-} else {
-  image = Image.file(File(pickedFile.path));
-}
-```
-
-Alternatively, the code may be unified at the expense of memory utilization:
-
-```dart
-image = Image.memory(await pickedFile.readAsBytes())
-```
-
-Take a look at the changes to the `example` app introduced in version 0.6.7 to see the migration steps applied there.
+| `PickedFile image = await _picker.getImage(...)` | `XFile image = await _picker.pickImage(...)` |
+| `List<PickedFile> images = await _picker.getMultiImage(...)` | `List<XFile> images = await _picker.pickMultiImage(...)` |
+| `PickedFile video = await _picker.getVideo(...)` | `XFile video = await _picker.pickVideo(...)` |
+| `LostData response = await _picker.getLostData()` | `LostDataResponse response = await _picker.retrieveLostData()` |

packages/image_picker/image_picker/example/lib/main.dart

@@ -36,9 +36,9 @@ class MyHomePage extends StatefulWidget {
 }
 
 class _MyHomePageState extends State<MyHomePage> {
-  List<PickedFile>? _imageFileList;
+  List<XFile>? _imageFileList;
 
-  set _imageFile(PickedFile? value) {
+  set _imageFile(XFile? value) {
     _imageFileList = value == null ? null : [value];
   }
 
@@ -54,7 +54,7 @@ class _MyHomePageState extends State<MyHomePage> {
   final TextEditingController maxHeightController = TextEditingController();
   final TextEditingController qualityController = TextEditingController();
 
-  Future<void> _playVideo(PickedFile? file) async {
+  Future<void> _playVideo(XFile? file) async {
     if (file != null && mounted) {
       await _disposeVideoController();
       late VideoPlayerController controller;
@@ -84,14 +84,14 @@ class _MyHomePageState extends State<MyHomePage> {
       await _controller!.setVolume(0.0);
     }
     if (isVideo) {
-      final PickedFile? file = await _picker.getVideo(
+      final XFile? file = await _picker.pickVideo(
           source: source, maxDuration: const Duration(seconds: 10));
       await _playVideo(file);
     } else if (isMultiImage) {
       await _displayPickImageDialog(context!,
           (double? maxWidth, double? maxHeight, int? quality) async {
         try {
-          final pickedFileList = await _picker.getMultiImage(
+          final pickedFileList = await _picker.pickMultiImage(
             maxWidth: maxWidth,
             maxHeight: maxHeight,
             imageQuality: quality,
@@ -109,7 +109,7 @@ class _MyHomePageState extends State<MyHomePage> {
       await _displayPickImageDialog(context!,
           (double? maxWidth, double? maxHeight, int? quality) async {
         try {
-          final pickedFile = await _picker.getImage(
+          final pickedFile = await _picker.pickImage(
             source: source,
             maxWidth: maxWidth,
             maxHeight: maxHeight,
@@ -214,7 +214,7 @@ class _MyHomePageState extends State<MyHomePage> {
   }
 
   Future<void> retrieveLostData() async {
-    final LostData response = await _picker.getLostData();
+    final LostDataResponse response = await _picker.retrieveLostData();
     if (response.isEmpty) {
       return;
     }

packages/image_picker/image_picker/lib/image_picker.dart

@@ -2,12 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// ignore_for_file: deprecated_member_use, deprecated_member_use_from_same_package
-
 import 'dart:async';
-
 import 'package:flutter/foundation.dart';
-
 import 'package:image_picker_platform_interface/image_picker_platform_interface.dart';
 
 export 'package:image_picker_platform_interface/image_picker_platform_interface.dart'
@@ -17,7 +13,9 @@ export 'package:image_picker_platform_interface/image_picker_platform_interface.
         ImageSource,
         CameraDevice,
         LostData,
+        LostDataResponse,
         PickedFile,
+        XFile,
         RetrieveType;
 
 /// Provides an easy way to pick an image/video from the image library,
@@ -61,6 +59,7 @@ class ImagePicker {
   /// the camera or photos gallery, no camera is available, plugin is already in use,
   /// temporary file could not be created (iOS only), plugin activity could not
   /// be allocated (Android only) or due to an unknown error.
+  @Deprecated('Switch to using pickImage instead')
   Future<PickedFile?> getImage({
     required ImageSource source,
     double? maxWidth,
@@ -101,6 +100,7 @@ class ImagePicker {
   /// be allocated (Android only) or due to an unknown error.
   ///
   /// See also [getImage] to allow users to only pick a single image.
+  @Deprecated('Switch to using pickMultiImage instead')
   Future<List<PickedFile>?> getMultiImage({
     double? maxWidth,
     double? maxHeight,
@@ -135,6 +135,7 @@ class ImagePicker {
   /// temporary file could not be created and video could not be cached (iOS only),
   /// plugin activity could not be allocated (Android only) or due to an unknown error.
   ///
+  @Deprecated('Switch to using pickVideo instead')
   Future<PickedFile?> getVideo({
     required ImageSource source,
     CameraDevice preferredCameraDevice = CameraDevice.rear,
@@ -160,7 +161,146 @@ class ImagePicker {
   /// See also:
   /// * [LostData], for what's included in the response.
   /// * [Android Activity Lifecycle](https://developer.android.com/reference/android/app/Activity.html), for more information on MainActivity destruction.
+  @Deprecated('Switch to using retrieveLostData instead')
   Future<LostData> getLostData() {
     return platform.retrieveLostData();
   }
+
+  /// Returns an [XFile] object wrapping the image that was picked.
+  ///
+  /// The returned [XFile] is intended to be used within a single APP session. Do not save the file path and use it across sessions.
+  ///
+  /// The `source` argument controls where the image comes from. This can
+  /// be either [ImageSource.camera] or [ImageSource.gallery].
+  ///
+  /// Where iOS supports HEIC images, Android 8 and below doesn't. Android 9 and above only support HEIC images if used
+  /// in addition to a size modification, of which the usage is explained below.
+  ///
+  /// If specified, the image will be at most `maxWidth` wide and
+  /// `maxHeight` tall. Otherwise the image will be returned at it's
+  /// original width and height.
+  /// The `imageQuality` argument modifies the quality of the image, ranging from 0-100
+  /// where 100 is the original/max quality. If `imageQuality` is null, the image with
+  /// the original quality will be returned. Compression is only supported for certain
+  /// image types such as JPEG and on Android PNG and WebP, too. If compression is not supported for the image that is picked,
+  /// a warning message will be logged.
+  ///
+  /// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
+  /// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
+  /// Defaults to [CameraDevice.rear]. Note that Android has no documented parameter for an intent to specify if
+  /// the front or rear camera should be opened, this function is not guaranteed
+  /// to work on an Android device.
+  ///
+  /// In Android, the MainActivity can be destroyed for various reasons. If that happens, the result will be lost
+  /// in this call. You can then call [retrieveLostData] when your app relaunches to retrieve the lost data.
+  ///
+  /// See also [pickMultiImage] to allow users to select multiple images at once.
+  ///
+  /// The method could throw [PlatformException] if the app does not have permission to access
+  /// the camera or photos gallery, no camera is available, plugin is already in use,
+  /// temporary file could not be created (iOS only), plugin activity could not
+  /// be allocated (Android only) or due to an unknown error.
+  Future<XFile?> pickImage({
+    required ImageSource source,
+    double? maxWidth,
+    double? maxHeight,
+    int? imageQuality,
+    CameraDevice preferredCameraDevice = CameraDevice.rear,
+  }) {
+    return platform.getImage(
+      source: source,
+      maxWidth: maxWidth,
+      maxHeight: maxHeight,
+      imageQuality: imageQuality,
+      preferredCameraDevice: preferredCameraDevice,
+    );
+  }
+
+  /// Returns a [List<XFile>] object wrapping the images that were picked.
+  ///
+  /// The returned [List<XFile>] is intended to be used within a single APP session. Do not save the file path and use it across sessions.
+  ///
+  /// Where iOS supports HEIC images, Android 8 and below doesn't. Android 9 and above only support HEIC images if used
+  /// in addition to a size modification, of which the usage is explained below.
+  ///
+  /// This method is not supported in iOS versions lower than 14.
+  ///
+  /// If specified, the images will be at most `maxWidth` wide and
+  /// `maxHeight` tall. Otherwise the images will be returned at it's
+  /// original width and height.
+  /// The `imageQuality` argument modifies the quality of the images, ranging from 0-100
+  /// where 100 is the original/max quality. If `imageQuality` is null, the images with
+  /// the original quality will be returned. Compression is only supported for certain
+  /// image types such as JPEG and on Android PNG and WebP, too. If compression is not supported for the image that is picked,
+  /// a warning message will be logged.
+  ///
+  /// The method could throw [PlatformException] if the app does not have permission to access
+  /// the camera or photos gallery, no camera is available, plugin is already in use,
+  /// temporary file could not be created (iOS only), plugin activity could not
+  /// be allocated (Android only) or due to an unknown error.
+  ///
+  /// See also [pickImage] to allow users to only pick a single image.
+  Future<List<XFile>?> pickMultiImage({
+    double? maxWidth,
+    double? maxHeight,
+    int? imageQuality,
+  }) {
+    return platform.getMultiImage(
+      maxWidth: maxWidth,
+      maxHeight: maxHeight,
+      imageQuality: imageQuality,
+    );
+  }
+
+  /// Returns an [XFile] object wrapping the video that was picked.
+  ///
+  /// The returned [XFile] is intended to be used within a single APP session. Do not save the file path and use it across sessions.
+  ///
+  /// The [source] argument controls where the video comes from. This can
+  /// be either [ImageSource.camera] or [ImageSource.gallery].
+  ///
+  /// The [maxDuration] argument specifies the maximum duration of the captured video. If no [maxDuration] is specified,
+  /// the maximum duration will be infinite.
+  ///
+  /// Use `preferredCameraDevice` to specify the camera to use when the `source` is [ImageSource.camera].
+  /// The `preferredCameraDevice` is ignored when `source` is [ImageSource.gallery]. It is also ignored if the chosen camera is not supported on the device.
+  /// Defaults to [CameraDevice.rear].
+  ///
+  /// In Android, the MainActivity can be destroyed for various fo reasons. If that happens, the result will be lost
+  /// in this call. You can then call [retrieveLostData] when your app relaunches to retrieve the lost data.
+  ///
+  /// The method could throw [PlatformException] if the app does not have permission to access
+  /// the camera or photos gallery, no camera is available, plugin is already in use,
+  /// temporary file could not be created and video could not be cached (iOS only),
+  /// plugin activity could not be allocated (Android only) or due to an unknown error.
+  ///
+  Future<XFile?> pickVideo({
+    required ImageSource source,
+    CameraDevice preferredCameraDevice = CameraDevice.rear,
+    Duration? maxDuration,
+  }) {
+    return platform.getVideo(
+      source: source,
+      preferredCameraDevice: preferredCameraDevice,
+      maxDuration: maxDuration,
+    );
+  }
+
+  /// Retrieve the lost [XFile] when [pickImage], [pickMultiImage] or [pickVideo] failed because the MainActivity
+  /// is destroyed. (Android only)
+  ///
+  /// Image or video can be lost if the MainActivity is destroyed. And there is no guarantee that the MainActivity is always alive.
+  /// Call this method to retrieve the lost data and process the data according to your APP's business logic.
+  ///
+  /// Returns a [LostDataResponse] object if successfully retrieved the lost data. The [LostDataResponse] object can \
+  /// represent either a successful image/video selection, or a failure.
+  ///
+  /// Calling this on a non-Android platform will throw [UnimplementedError] exception.
+  ///
+  /// See also:
+  /// * [LostDataResponse], for what's included in the response.
+  /// * [Android Activity Lifecycle](https://developer.android.com/reference/android/app/Activity.html), for more information on MainActivity destruction.
+  Future<LostDataResponse> retrieveLostData() {
+    return platform.getLostData();
+  }
 }

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/plugins/tree/master/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.1+4
+version: 0.8.2
 
 environment:
   sdk: ">=2.12.0 <3.0.0"
@@ -24,8 +24,8 @@ dependencies:
   flutter:
     sdk: flutter
   flutter_plugin_android_lifecycle: ^2.0.1
-  image_picker_for_web: ^2.0.0
-  image_picker_platform_interface: ^2.1.0
+  image_picker_for_web: ^2.1.0
+  image_picker_platform_interface: ^2.2.0
 
 dev_dependencies:
   flutter_test: