[image_picker] Mention `launchMode: singleInstance` in README (#3759)
Users of the image picker are reporting issues for Android when setting the `launchMode` of the application activity to `singleInstance`. Namely, the image picker will always return `RESULT_CANCELED`. After investigation, it turned out that this problem is inherent by the way Android handles activities with this launch mode: `singleInstance` instructs the framework to open new activities in a new task. As activities cannot communicate between tasks, the image picker activity is unable to relay back the result to the calling activity.
This PR updates the README to mention this behavior and provide a workaround.
Closes [76856](https://github.com/flutter/flutter/issues/76856).
diff --git a/packages/image_picker/image_picker/CHANGELOG.md b/packages/image_picker/image_picker/CHANGELOG.md
index aeb5437..117f6af 100644
--- a/packages/image_picker/image_picker/CHANGELOG.md
+++ b/packages/image_picker/image_picker/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 0.8.7+4
+
+* Updates README to mention usage of `launchMode: singleInstance` for Android.
+
## 0.8.7+3
* Adds handling of unsupported image types to the example.
diff --git a/packages/image_picker/image_picker/README.md b/packages/image_picker/image_picker/README.md
index 2dfb107..b566116 100755
--- a/packages/image_picker/image_picker/README.md
+++ b/packages/image_picker/image_picker/README.md
@@ -12,54 +12,48 @@
## Installation
-First, add `image_picker` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels).
+First, add `image_picker` as a
+[dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels).
### 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)
+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)
-Add the following keys to your _Info.plist_ file, located in `<project root>/ios/Runner/Info.plist`:
+Add the following keys to your _Info.plist_ file, located in
+`<project root>/ios/Runner/Info.plist`:
-* `NSPhotoLibraryUsageDescription` - describe why your app needs permission for the photo library. This is called _Privacy - Photo Library Usage Description_ in the visual editor.
- * This permission will not be requested if you always pass `false` for `requestFullMetadata`, but App Store policy requires including the plist entry.
-* `NSCameraUsageDescription` - describe why your app needs access to the camera. This is called _Privacy - Camera Usage Description_ in the visual editor.
-* `NSMicrophoneUsageDescription` - describe why your app needs access to the microphone, if you intend to record videos. This is called _Privacy - Microphone Usage Description_ in the visual editor.
+* `NSPhotoLibraryUsageDescription` - describe why your app needs permission for
+the photo library. This is called _Privacy - Photo Library Usage Description_ in
+the visual editor.
+ * This permission will not be requested if you always pass `false` for
+ `requestFullMetadata`, but App Store policy requires including the plist
+ entry.
+* `NSCameraUsageDescription` - describe why your app needs access to the camera.
+This is called _Privacy - Camera Usage Description_ in the visual editor.
+* `NSMicrophoneUsageDescription` - describe why your app needs access to the
+microphone, if you intend to record videos. This is called
+_Privacy - Microphone Usage Description_ in the visual editor.
### Android
-Starting with version **0.8.1** the Android implementation support to pick (multiple) images on Android 4.3 or higher.
+Starting with version **0.8.1** the Android implementation support to pick
+(multiple) images on Android 4.3 or higher.
-No configuration required - the plugin should work out of the box. It is
-however highly recommended to prepare for Android killing the application when
-low on memory. How to prepare for this is discussed in the [Handling
-MainActivity destruction on Android](#handling-mainactivity-destruction-on-android)
+No configuration required - the plugin should work out of the box. It is however
+highly recommended to prepare for Android killing the application when low on memory. How to prepare for this is discussed in the
+[Handling MainActivity destruction on Android](#handling-mainactivity-destruction-on-android)
section.
-It is no longer required to add `android:requestLegacyExternalStorage="true"` as an attribute to the `<application>` tag in AndroidManifest.xml, as `image_picker` has been updated to make use of scoped storage.
+It is no longer required to add `android:requestLegacyExternalStorage="true"` as
+an attribute to the `<application>` tag in AndroidManifest.xml, as
+`image_picker` has been updated to make use of scoped storage.
-**Note:** Images and videos picked using the camera are saved to your application's local cache, and should therefore be expected to only be around temporarily.
-If you require your picked image to be stored permanently, it is your responsibility to move it to a more permanent location.
-
-### Example
-
-<?code-excerpt "readme_excerpts.dart (Pick)"?>
-``` 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? galleryVideo =
- await picker.pickVideo(source: ImageSource.gallery);
-// Capture a video.
-final XFile? cameraVideo = await picker.pickVideo(source: ImageSource.camera);
-// Pick multiple images.
-final List<XFile> images = await picker.pickMultiImage();
-```
-
-### Handling MainActivity destruction on Android
+#### Handling MainActivity destruction
When under high memory pressure the Android system may kill the MainActivity of
the application using the image_picker. On Android the image_picker makes use
@@ -89,17 +83,59 @@
This check should always be run at startup in order to detect and handle this
case. Please refer to the
-[example app](https://pub.dev/packages/image_picker/example) for a more
-complete example of handling this flow.
+[example app](https://pub.dev/packages/image_picker/example) for a more complete
+example of handling this flow.
-### Android Photo Picker
+#### Permanently storing images and videos
-This package has optional [Android Photo Picker](https://developer.android.com/training/data-storage/shared/photopicker) functionality.
+Images and videos picked using the camera are saved to your application's local
+cache, and should therefore be expected to only be around temporarily.
+If you require your picked image to be stored permanently, it is your
+responsibility to move it to a more permanent location.
+
+#### Android Photo Picker
+
+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).
+#### Using `launchMode: singleInstance`
+
+Launching the image picker from an `Activity` with `launchMode: singleInstance`
+will always return `RESULT_CANCELED`.
+In this launch mode, new activities are created in a separate [Task][2].
+As activities cannot communicate between tasks, the image picker activity cannot
+send back its eventual result to the calling activity.
+To work around this problem, consider using `launchMode: singleTask` instead.
+
+### Example
+
+<?code-excerpt "readme_excerpts.dart (Pick)"?>
+``` 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? galleryVideo =
+ await picker.pickVideo(source: ImageSource.gallery);
+// Capture a video.
+final XFile? cameraVideo = await picker.pickVideo(source: ImageSource.camera);
+// Pick multiple images.
+final List<XFile> images = await picker.pickMultiImage();
+```
+
## Migrating to 0.8.2+
-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.
+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
@@ -111,3 +147,4 @@
| `LostData response = await _picker.getLostData()` | `LostDataResponse response = await _picker.retrieveLostData()` |
[1]: https://pub.dev/packages/image_picker_for_web#limitations-on-the-web-platform
+[2]: https://developer.android.com/guide/components/activities/tasks-and-back-stack
diff --git a/packages/image_picker/image_picker/pubspec.yaml b/packages/image_picker/image_picker/pubspec.yaml
index 6c5f52b..c1bb222 100755
--- a/packages/image_picker/image_picker/pubspec.yaml
+++ b/packages/image_picker/image_picker/pubspec.yaml
@@ -3,7 +3,7 @@
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+3
+version: 0.8.7+4
environment:
sdk: ">=2.18.0 <4.0.0"
