[image_picker] Improves documentation around the destruction of the MainActivity. (#4672)
diff --git a/packages/image_picker/image_picker/CHANGELOG.md b/packages/image_picker/image_picker/CHANGELOG.md
index ce29eb5..1b7d0ff 100644
--- a/packages/image_picker/image_picker/CHANGELOG.md
+++ b/packages/image_picker/image_picker/CHANGELOG.md
@@ -1,5 +1,6 @@
-## NEXT
+## 0.8.4+5
+* Improves the documentation on handling MainActivity being killed by the Android OS.
* Updates Android compileSdkVersion to 31.
* Fix iOS RunnerUITests search paths.
diff --git a/packages/image_picker/image_picker/README.md b/packages/image_picker/image_picker/README.md
index 100606c..46a7795 100755
--- a/packages/image_picker/image_picker/README.md
+++ b/packages/image_picker/image_picker/README.md
@@ -26,7 +26,11 @@
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.
+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.
@@ -55,7 +59,14 @@
### Handling MainActivity destruction on Android
-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:
+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
+of the default `Intent.ACTION_GET_CONTENT` or `MediaStore.ACTION_IMAGE_CAPTURE`
+intents. This means that while the intent is executing the source application
+is moved to the background and becomes eligable for cleanup when the system is
+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<void> getLostData() async {
@@ -65,7 +76,7 @@
return;
}
if (response.files != null) {
- for(final XFile file in response.files) {
+ for (final XFile file in response.files) {
_handleFile(file);
}
} else {
@@ -74,7 +85,10 @@
}
```
-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.
+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.
## Migrating to 0.8.2+
diff --git a/packages/image_picker/image_picker/pubspec.yaml b/packages/image_picker/image_picker/pubspec.yaml
index 5d8a5b5..836c3ca 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/plugins/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.4+4
+version: 0.8.4+5
environment:
sdk: ">=2.14.0 <3.0.0"
