Skip to content

[image_picker] Update to 1.0 #4285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 23, 2023
Merged

[image_picker] Update to 1.0 #4285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0052792
[image_picker] Update to 1.0
stuartmorgan-g Jun 23, 2023
21311f6
Update README.md
stuartmorgan-g Jun 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion packages/image_picker/image_picker/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,16 @@
## 1.0.0

* **BREAKING CHANGE**: Removes the deprecated `get*` methods. Clients who have
not already done so will need to migrate to the `pick*` versions that use
`XFile` rather than `PickedFile` for return values.
* As this is the only change, we encourage authors of published packages
that depend on `image_picker` to consider using a constraint of
`'>=0.8.9 <2.0.0'` rather than `^1.0.0` when updating dependencies, to
avoid conflicts with packages that have not yet updated.

## 0.8.9

* Adds `getMedia` and `getMultipleMedia` methods.
* Adds `pickMedia` and `pickMultipleMedia` methods.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I generally don't want us changing old changelogs, I noticed that we forgot to adjust the names for the app-facing package, making this wrong, and it's actively confusing when combined with the discussion of removing get in 1.0.0 so I thought it was worthwhile here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch


## 0.8.8

Expand Down
12 changes: 5 additions & 7 deletions packages/image_picker/image_picker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,15 +186,13 @@ final XFile? media = await picker.pickMedia();
final List<XFile> medias = await picker.pickMultipleMedia();
```

## Migrating to 0.8.2+
## Migrating to 1.0

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
Starting with version 0.8.2 of the image_picker plugin, new methods were
added 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.
plugin's own `PickedFile` instances. The previous methods were supported through
0.8.9, and removed in 1.0.0.

#### Call the new methods

Expand Down
151 changes: 7 additions & 144 deletions packages/image_picker/image_picker/lib/image_picker.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,150 +25,10 @@ class ImagePicker {
@visibleForTesting
static ImagePickerPlatform get platform => ImagePickerPlatform.instance;

/// Returns a [PickedFile] object wrapping the image that was picked.
///
/// The returned [PickedFile] 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 [getLostData] when your app relaunches to retrieve the lost data.
///
/// See also [getMultiImage] 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.
@Deprecated('Switch to using pickImage instead')
Future<PickedFile?> getImage({
required ImageSource source,
double? maxWidth,
double? maxHeight,
int? imageQuality,
CameraDevice preferredCameraDevice = CameraDevice.rear,
}) {
return platform.pickImage(
source: source,
maxWidth: maxWidth,
maxHeight: maxHeight,
imageQuality: imageQuality,
preferredCameraDevice: preferredCameraDevice,
);
}

/// Returns a [List<PickedFile>] object wrapping the images that were picked.
///
/// The returned [List<PickedFile>] 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 [getImage] to allow users to only pick a single image.
@Deprecated('Switch to using pickMultiImage instead')
Future<List<PickedFile>?> getMultiImage({
double? maxWidth,
double? maxHeight,
int? imageQuality,
}) {
return platform.pickMultiImage(
maxWidth: maxWidth,
maxHeight: maxHeight,
imageQuality: imageQuality,
);
}

/// Returns a [PickedFile] object wrapping the video that was picked.
///
/// The returned [PickedFile] 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 reasons. If that happens, the result will be lost
/// in this call. You can then call [getLostData] 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.
///
@Deprecated('Switch to using pickVideo instead')
Future<PickedFile?> getVideo({
required ImageSource source,
CameraDevice preferredCameraDevice = CameraDevice.rear,
Duration? maxDuration,
}) {
return platform.pickVideo(
source: source,
preferredCameraDevice: preferredCameraDevice,
maxDuration: maxDuration,
);
}

/// Retrieve the lost [PickedFile] when [selectImage] or [selectVideo] 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 [LostData] object if successfully retrieved the lost data. The [LostData] 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:
/// * [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 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].
Expand Down Expand Up @@ -234,7 +94,8 @@ class ImagePicker {

/// 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.
/// 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.
Expand Down Expand Up @@ -284,7 +145,8 @@ class ImagePicker {
}

/// Returns an [XFile] of the image or video that was picked.
/// The image or videos can only come from the gallery.
///
/// The image or video can only come from the gallery.
///
/// The returned [XFile] is intended to be used within a single app session.
/// Do not save the file path and use it across sessions.
Expand Down Expand Up @@ -339,6 +201,7 @@ class ImagePicker {
}

/// Returns a [List<XFile>] with the images and/or videos that were picked.
///
/// The images and videos come from the gallery.
///
/// The returned [List<XFile>] is intended to be used within a single app session.
Expand Down
2 changes: 1 addition & 1 deletion packages/image_picker/image_picker/pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.9
version: 1.0.0

environment:
sdk: ">=2.18.0 <4.0.0"
Expand Down
Loading