diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f94715..2b5efe0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,28 @@ +## 0.7.0 + +- New APIs and options. +- There's no major breaking changes when updating to `v0.7.0` but there are deprecation notices over Media Store and Environment API. + +### New + +- `openDocument` API with single and multiple files support @honjow. +- `openDocumentTree` it now also supports `persistablePermission` option which flags an one-time operation to avoid unused permission issues. + +### Deprecation notices + +- All non SAF APIs are deprecated (Media Store and Environment APIs), if you are using them, let us know by [opening an issue](https://github.com/alexrintt/shared-storage/issues/new) with your use-case so we can implement a new compatible API using a cross-platform approach. + +### Example project + +- Added a new button that implements `openDocument` API. + ## 0.6.0 This release contains a severe API fixes and some minor doc changes: ### Breaking changes -- Unused arguments in `DocumentFile.getContent` and `DocumentFile.getContentAsString`. [#107](https://github.com/alexrintt/shared-storage/issues/107). +- Unused arguments in `DocumentFile.getContent` and `DocumentFile.getContentAsString`. [#107](https://github.com/alexrintt/shared-storage/issues/107) @clragon. - Package import it's now done through a single import. ## 0.5.0 @@ -170,7 +188,7 @@ See the label [reference here](/docs/Usage/API%20Labeling.md). - Mirror `getStorageDirectory` from [`Environment.getStorageDirectory`](https://developer.android.com/reference/android/os/Environment#getStorageDirectory%28%29). -### Deprecation Notices +### Deprecation notices - `getExternalStoragePublicDirectory` was marked as deprecated and should be replaced with an equivalent API depending on your use-case, see [how to migrate `getExternalStoragePublicDirectory`](https://stackoverflow.com/questions/56468539/getexternalstoragepublicdirectory-deprecated-in-android-q). This deprecation is originated from official Android documentation and not by the plugin itself. diff --git a/docs/Migrate notes/Migrate to v0.7.0.md b/docs/Migrate notes/Migrate to v0.7.0.md new file mode 100644 index 0000000..c25fe64 --- /dev/null +++ b/docs/Migrate notes/Migrate to v0.7.0.md @@ -0,0 +1,12 @@ +There's no major breaking changes when updating to `v0.7.0` but there are deprecation notices if you are using Media Store and Environment API. + +Update your `pubspec.yaml`: + +```yaml +dependencies: + shared_storage: ^0.7.0 +``` + +## Deprecation notices + +All non SAF APIs are deprecated, if you are using them, let us know by [opening an issue](https://github.com/alexrintt/shared-storage/issues/new) with your use-case so we can implement a new compatible API using a cross-platform approach. diff --git a/docs/Usage/Environment.md b/docs/Usage/Environment.md index cc519f2..3ce904a 100644 --- a/docs/Usage/Environment.md +++ b/docs/Usage/Environment.md @@ -1,3 +1,5 @@ +> **WARNING** This API is deprecated and will be removed soon. If you need it, please open an issue with your use-case to include in the next release as part of the new original cross-platform API. + ## Import package ```dart diff --git a/docs/Usage/Media Store.md b/docs/Usage/Media Store.md index 50f76e8..b5476c0 100644 --- a/docs/Usage/Media Store.md +++ b/docs/Usage/Media Store.md @@ -1,3 +1,5 @@ +> **WARNING** This API is deprecated and will be removed soon. If you need it, please open an issue with your use-case to include in the next release as part of the new original cross-platform API. + ## Import package ```dart diff --git a/docs/Usage/Storage Access Framework.md b/docs/Usage/Storage Access Framework.md index 7814827..a89cf0e 100644 --- a/docs/Usage/Storage Access Framework.md +++ b/docs/Usage/Storage Access Framework.md @@ -64,6 +64,46 @@ if (grantedUri != null) { } ``` +### openDocument + +Same as `openDocumentTree` but for file URIs, you can request user to select a file and filter by: + +- Single or multiple files. +- Mime type. + +You can also specify if you want a one-time operation (`persistablePermission` = false) and if you don't need write access (`grantWritePermission` = false). + +```dart +const kDownloadsFolder = + 'content://com.android.externalstorage.documents/tree/primary%3ADownloads/document/primary%3ADownloads'; + +final List? selectedDocumentUris = await openDocument( + // if you have a previously saved URI, + // you can use the specify the tree you user will see at startup of the file picker. + initialUri: Uri.parse(kDownloadsFolder), + + // whether or not allow the user select multiple files. + multiple: true, + + // whether or not the selected URIs should be persisted across app and device reboots. + persistablePermission: true, + + // whether or not grant write permission required to edit file metadata (name) and it's contents. + grantWritePermission: true, + + // whether or not filter by mime type. + mimeType: 'image/*' // default '*/*' +); + +if (selectedDocumentUris == null) { + return print('User cancelled the operation.'); +} + +// If [selectedDocumentUris] are [persistablePermission]s then it will be returned by this function +// along with any another URIs you've got permission over. +final List persistedUris = await persistedUriPermissions(); +``` + ### listFiles This method list files lazily **over a granted uri:**