Skip to content

Commit 17a5a30

Browse files
JeroenWeenerJeroenWeener
committed
Update README structure
1 parent a602c57 commit 17a5a30

File tree

1 file changed

+79
-46
lines changed

1 file changed

+79
-46
lines changed

‎packages/image_picker/image_picker/README.md‎

Lines changed: 79 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -12,57 +12,48 @@ and taking new pictures with the camera.
1212

1313
## Installation
1414

15-
First, add `image_picker` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels).
15+
First, add `image_picker` as a
16+
[dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels).
1617

1718
### iOS
1819

19-
Starting with version **0.8.1** the iOS implementation uses PHPicker to pick (multiple) images on iOS 14 or higher.
20-
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)
21-
22-
Add the following keys to your _Info.plist_ file, located in `<project root>/ios/Runner/Info.plist`:
23-
24-
* `NSPhotoLibraryUsageDescription` - describe why your app needs permission for the photo library. This is called _Privacy - Photo Library Usage Description_ in the visual editor.
25-
* This permission will not be requested if you always pass `false` for `requestFullMetadata`, but App Store policy requires including the plist entry.
26-
* `NSCameraUsageDescription` - describe why your app needs access to the camera. This is called _Privacy - Camera Usage Description_ in the visual editor.
27-
* `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.
20+
Starting with version **0.8.1** the iOS implementation uses PHPicker to pick
21+
(multiple) images on iOS 14 or higher.
22+
As a result of implementing PHPicker it becomes impossible to pick HEIC images
23+
on the iOS simulator in iOS 14+. This is a known issue. Please test this on a
24+
real device, or test with non-HEIC images until Apple solves this issue.
25+
[63426347 - Apple known issue](https://www.google.com/search?q=63426347+apple&sxsrf=ALeKk01YnTMid5S0PYvhL8GbgXJ40ZS[…]t=gws-wiz&ved=0ahUKEwjKh8XH_5HwAhWL_rsIHUmHDN8Q4dUDCA8&uact=5)
26+
27+
Add the following keys to your _Info.plist_ file, located in
28+
`<project root>/ios/Runner/Info.plist`:
29+
30+
* `NSPhotoLibraryUsageDescription` - describe why your app needs permission for
31+
the photo library. This is called _Privacy - Photo Library Usage Description_ in
32+
the visual editor.
33+
* This permission will not be requested if you always pass `false` for
34+
`requestFullMetadata`, but App Store policy requires including the plist
35+
entry.
36+
* `NSCameraUsageDescription` - describe why your app needs access to the camera.
37+
This is called _Privacy - Camera Usage Description_ in the visual editor.
38+
* `NSMicrophoneUsageDescription` - describe why your app needs access to the
39+
microphone, if you intend to record videos. This is called
40+
_Privacy - Microphone Usage Description_ in the visual editor.
2841

2942
### Android
3043

31-
Starting with version **0.8.1** the Android implementation support to pick (multiple) images on Android 4.3 or higher.
44+
Starting with version **0.8.1** the Android implementation support to pick
45+
(multiple) images on Android 4.3 or higher.
3246

33-
No configuration required - the plugin should work out of the box. It is
34-
however highly recommended to prepare for Android killing the application when
35-
low on memory. How to prepare for this is discussed in the [Handling
36-
MainActivity destruction on Android](#handling-mainactivity-destruction-on-android)
47+
No configuration required - the plugin should work out of the box. It is however
48+
highly recommended to prepare for Android killing the application when low on memory. How to prepare for this is discussed in the
49+
[Handling MainActivity destruction on Android](#handling-mainactivity-destruction-on-android)
3750
section.
3851

39-
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.
40-
41-
**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.
42-
If you require your picked image to be stored permanently, it is your responsibility to move it to a more permanent location.
43-
44-
45-
**Note:** 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.
46-
47-
### Example
48-
49-
<?code-excerpt "readme_excerpts.dart (Pick)"?>
50-
``` dart
51-
final ImagePicker picker = ImagePicker();
52-
// Pick an image.
53-
final XFile? image = await picker.pickImage(source: ImageSource.gallery);
54-
// Capture a photo.
55-
final XFile? photo = await picker.pickImage(source: ImageSource.camera);
56-
// Pick a video.
57-
final XFile? galleryVideo =
58-
await picker.pickVideo(source: ImageSource.gallery);
59-
// Capture a video.
60-
final XFile? cameraVideo = await picker.pickVideo(source: ImageSource.camera);
61-
// Pick multiple images.
62-
final List<XFile> images = await picker.pickMultiImage();
63-
```
52+
It is no longer required to add `android:requestLegacyExternalStorage="true"` as
53+
an attribute to the `<application>` tag in AndroidManifest.xml, as
54+
`image_picker` has been updated to make use of scoped storage.
6455

65-
### Handling MainActivity destruction on Android
56+
#### Handling MainActivity destruction
6657

6758
When under high memory pressure the Android system may kill the MainActivity of
6859
the application using the image_picker. On Android the image_picker makes use
@@ -92,17 +83,59 @@ Future<void> getLostData() async {
9283

9384
This check should always be run at startup in order to detect and handle this
9485
case. Please refer to the
95-
[example app](https://pub.dev/packages/image_picker/example) for a more
96-
complete example of handling this flow.
86+
[example app](https://pub.dev/packages/image_picker/example) for a more complete
87+
example of handling this flow.
9788

98-
### Android Photo Picker
89+
#### Permanently storing images and videos
9990

100-
This package has optional [Android Photo Picker](https://developer.android.com/training/data-storage/shared/photopicker) functionality.
91+
Images and videos picked using the camera are saved to your application's local
92+
cache, and should therefore be expected to only be around temporarily.
93+
If you require your picked image to be stored permanently, it is your
94+
responsibility to move it to a more permanent location.
95+
96+
#### Android Photo Picker
97+
98+
This package has optional
99+
[Android Photo Picker](https://developer.android.com/training/data-storage/shared/photopicker)
100+
functionality.
101101
[Learn how to use it](https://pub.dev/packages/image_picker_android).
102102

103+
#### Using `launchMode: singleInstance`
104+
105+
Launching the image picker from an `Activity` with `launchMode: singleInstance`
106+
will always return `RESULT_CANCELED`.
107+
In this launch mode, new activities are created in a separate [Task][2].
108+
As activities cannot communicate between tasks, the image picker activity cannot
109+
send back its eventual result to the calling activity.
110+
To work around this problem, consider using `launchMode: singleTask` instead.
111+
112+
### Example
113+
114+
<?code-excerpt "readme_excerpts.dart (Pick)"?>
115+
``` dart
116+
final ImagePicker picker = ImagePicker();
117+
// Pick an image.
118+
final XFile? image = await picker.pickImage(source: ImageSource.gallery);
119+
// Capture a photo.
120+
final XFile? photo = await picker.pickImage(source: ImageSource.camera);
121+
// Pick a video.
122+
final XFile? galleryVideo =
123+
await picker.pickVideo(source: ImageSource.gallery);
124+
// Capture a video.
125+
final XFile? cameraVideo = await picker.pickVideo(source: ImageSource.camera);
126+
// Pick multiple images.
127+
final List<XFile> images = await picker.pickMultiImage();
128+
```
129+
103130
## Migrating to 0.8.2+
104131

105-
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.
132+
Starting with version **0.8.2** of the image_picker plugin, new methods have
133+
been added for picking files that return `XFile` instances (from the
134+
[cross_file](https://pub.dev/packages/cross_file) package) rather than the
135+
plugin's own `PickedFile` instances. While the previous methods still exist, it
136+
is already recommended to start migrating over to their new equivalents.
137+
Eventually, `PickedFile` and the methods that return instances of it will be
138+
deprecated and removed.
106139

107140
#### Call the new methods
108141

0 commit comments

Comments
 (0)