[image_picker] Mention launchMode: singleInstance in README

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.

packages/image_picker/image_picker/README.md

@@ -12,54 +12,48 @@ and taking new pictures with the camera.
 
 ## 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)
-
-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.
+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`:
+
+* `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.
-
-**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();
-```
+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.
 
-### 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 @@ Future<void> getLostData() async {
 
 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.
+
+#### Permanently storing images and videos
 
-### Android Photo Picker
+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.
 
-This package has optional [Android Photo Picker](https://developer.android.com/training/data-storage/shared/photopicker) functionality.
+#### 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 @@ Starting with version **0.8.2** of the image_picker plugin, new methods have bee
 | `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

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+3
+version: 0.8.7+4
 
 environment:
   sdk: ">=2.18.0 <4.0.0"