[path_provider] Documentation update for readme.md and example app (#4686)
diff --git a/packages/path_provider/path_provider/CHANGELOG.md b/packages/path_provider/path_provider/CHANGELOG.md
index bc349f7..d71ebf7 100644
--- a/packages/path_provider/path_provider/CHANGELOG.md
+++ b/packages/path_provider/path_provider/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 2.0.9
+
+* Updates documentation on README.md.
+* Updates example application.
+
## 2.0.8
* Updates example app Android compileSdkVersion to 31.
diff --git a/packages/path_provider/path_provider/README.md b/packages/path_provider/path_provider/README.md
index 47ae689..20d888f 100644
--- a/packages/path_provider/path_provider/README.md
+++ b/packages/path_provider/path_provider/README.md
@@ -2,16 +2,16 @@
[](https://pub.dev/packages/path_provider)
-A Flutter plugin for finding commonly used locations on the filesystem. Supports Android, iOS, Linux, macOS and Windows.
+A Flutter plugin for finding commonly used locations on the filesystem.
+Supports Android, iOS, Linux, macOS and Windows.
Not all methods are supported on all platforms.
## Usage
To use this plugin, add `path_provider` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/platform-integration/platform-channels).
-### Example
-
-``` dart
+## Example
+```dart
Directory tempDir = await getTemporaryDirectory();
String tempPath = tempDir.path;
@@ -19,11 +19,25 @@
String appDocPath = appDocDir.path;
```
-Please see the example app of this plugin for a full example.
+## Supported platforms and paths
-### Usage in tests
+Directories support by platform:
-`path_provider` now uses a `PlatformInterface`, meaning that not all platforms share the a single `PlatformChannel`-based implementation.
+| Directory | Android | iOS | Linux | macOS | Windows |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| Temporary | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
+| Application Support | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
+| Application Library | ❌️ | ✔️ | ❌️ | ✔️ | ❌️ |
+| Application Documents | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
+| External Storage | ✔️ | ❌ | ❌ | ❌️ | ❌️ |
+| External Cache Directories | ✔️ | ❌ | ❌ | ❌️ | ❌️ |
+| External Storage Directories | ✔️ | ❌ | ❌ | ❌️ | ❌️ |
+| Downloads | ❌ | ❌ | ✔️ | ✔️ | ✔️ |
+
+## Testing
+
+`path_provider` now uses a `PlatformInterface`, meaning that not all platforms share a single `PlatformChannel`-based implementation.
With that change, tests should be updated to mock `PathProviderPlatform` rather than `PlatformChannel`.
See this `path_provider` [test](https://github.com/flutter/plugins/blob/master/packages/path_provider/path_provider/test/path_provider_test.dart) for an example.
+
diff --git a/packages/path_provider/path_provider/example/integration_test/path_provider_test.dart b/packages/path_provider/path_provider/example/integration_test/path_provider_test.dart
index 9f8feee..27493a7 100644
--- a/packages/path_provider/path_provider/example/integration_test/path_provider_test.dart
+++ b/packages/path_provider/path_provider/example/integration_test/path_provider_test.dart
@@ -85,6 +85,16 @@
}
});
}
+
+ testWidgets('getDownloadsDirectory', (WidgetTester tester) async {
+ if (Platform.isIOS || Platform.isAndroid) {
+ final Future<Directory?> result = getDownloadsDirectory();
+ expect(result, throwsA(isInstanceOf<UnsupportedError>()));
+ } else {
+ final Directory? result = await getDownloadsDirectory();
+ _verifySampleFile(result, 'downloads');
+ }
+ });
}
/// Verify a file called [name] in [directory] by recreating it with test
diff --git a/packages/path_provider/path_provider/example/lib/main.dart b/packages/path_provider/path_provider/example/lib/main.dart
index c0ac126..90c2ccb 100644
--- a/packages/path_provider/path_provider/example/lib/main.dart
+++ b/packages/path_provider/path_provider/example/lib/main.dart
@@ -42,6 +42,7 @@
Future<Directory?>? _externalDocumentsDirectory;
Future<List<Directory>?>? _externalStorageDirectories;
Future<List<Directory>?>? _externalCacheDirectories;
+ Future<Directory?>? _downloadsDirectory;
void _requestTempDirectory() {
setState(() {
@@ -117,6 +118,12 @@
});
}
+ void _requestDownloadsDirectory() {
+ setState(() {
+ _downloadsDirectory = getDownloadsDirectory();
+ });
+ }
+
@override
Widget build(BuildContext context) {
return Scaffold(
@@ -126,88 +133,165 @@
body: Center(
child: ListView(
children: <Widget>[
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: const Text('Get Temporary Directory'),
- onPressed: _requestTempDirectory,
- ),
- ),
- FutureBuilder<Directory?>(
- future: _tempDirectory, builder: _buildDirectory),
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: const Text('Get Application Documents Directory'),
- onPressed: _requestAppDocumentsDirectory,
- ),
- ),
- FutureBuilder<Directory?>(
- future: _appDocumentsDirectory, builder: _buildDirectory),
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: const Text('Get Application Support Directory'),
- onPressed: _requestAppSupportDirectory,
- ),
- ),
- FutureBuilder<Directory?>(
- future: _appSupportDirectory, builder: _buildDirectory),
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: const Text('Get Application Library Directory'),
- onPressed: _requestAppLibraryDirectory,
- ),
- ),
- FutureBuilder<Directory?>(
- future: _appLibraryDirectory, builder: _buildDirectory),
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: Text(Platform.isIOS
- ? 'External directories are unavailable on iOS'
- : 'Get External Storage Directory'),
- onPressed:
- Platform.isIOS ? null : _requestExternalStorageDirectory,
- ),
- ),
- FutureBuilder<Directory?>(
- future: _externalDocumentsDirectory, builder: _buildDirectory),
- Column(children: <Widget>[
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: Text(Platform.isIOS
- ? 'External directories are unavailable on iOS'
- : 'Get External Storage Directories'),
- onPressed: Platform.isIOS
- ? null
- : () {
- _requestExternalStorageDirectories(
- StorageDirectory.music,
- );
- },
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: const Text(
+ 'Get Temporary Directory',
+ ),
+ onPressed: _requestTempDirectory,
+ ),
),
- ),
- ]),
- FutureBuilder<List<Directory>?>(
- future: _externalStorageDirectories,
- builder: _buildDirectories),
- Column(children: <Widget>[
- Padding(
- padding: const EdgeInsets.all(16.0),
- child: ElevatedButton(
- child: Text(Platform.isIOS
- ? 'External directories are unavailable on iOS'
- : 'Get External Cache Directories'),
- onPressed:
- Platform.isIOS ? null : _requestExternalCacheDirectories,
+ FutureBuilder<Directory?>(
+ future: _tempDirectory,
+ builder: _buildDirectory,
),
- ),
- ]),
- FutureBuilder<List<Directory>?>(
- future: _externalCacheDirectories, builder: _buildDirectories),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: const Text(
+ 'Get Application Documents Directory',
+ ),
+ onPressed: _requestAppDocumentsDirectory,
+ ),
+ ),
+ FutureBuilder<Directory?>(
+ future: _appDocumentsDirectory,
+ builder: _buildDirectory,
+ ),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: const Text(
+ 'Get Application Support Directory',
+ ),
+ onPressed: _requestAppSupportDirectory,
+ ),
+ ),
+ FutureBuilder<Directory?>(
+ future: _appSupportDirectory,
+ builder: _buildDirectory,
+ ),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: Text(
+ Platform.isAndroid
+ ? 'Application Library Directory unavailable'
+ : 'Get Application Library Directory',
+ ),
+ onPressed:
+ Platform.isAndroid ? null : _requestAppLibraryDirectory,
+ ),
+ ),
+ FutureBuilder<Directory?>(
+ future: _appLibraryDirectory,
+ builder: _buildDirectory,
+ ),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: Text(
+ !Platform.isAndroid
+ ? 'External storage is unavailable'
+ : 'Get External Storage Directory',
+ ),
+ onPressed: !Platform.isAndroid
+ ? null
+ : _requestExternalStorageDirectory,
+ ),
+ ),
+ FutureBuilder<Directory?>(
+ future: _externalDocumentsDirectory,
+ builder: _buildDirectory,
+ ),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: Text(
+ !Platform.isAndroid
+ ? 'External directories are unavailable'
+ : 'Get External Storage Directories',
+ ),
+ onPressed: !Platform.isAndroid
+ ? null
+ : () {
+ _requestExternalStorageDirectories(
+ StorageDirectory.music,
+ );
+ },
+ ),
+ ),
+ FutureBuilder<List<Directory>?>(
+ future: _externalStorageDirectories,
+ builder: _buildDirectories,
+ ),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: Text(
+ !Platform.isAndroid
+ ? 'External directories are unavailable'
+ : 'Get External Cache Directories',
+ ),
+ onPressed: !Platform.isAndroid
+ ? null
+ : _requestExternalCacheDirectories,
+ ),
+ ),
+ FutureBuilder<List<Directory>?>(
+ future: _externalCacheDirectories,
+ builder: _buildDirectories,
+ ),
+ ],
+ ),
+ Column(
+ children: <Widget>[
+ Padding(
+ padding: const EdgeInsets.all(16.0),
+ child: ElevatedButton(
+ child: Text(
+ Platform.isAndroid || Platform.isIOS
+ ? 'Downloads directory is unavailable'
+ : 'Get Downloads Directory',
+ ),
+ onPressed: Platform.isAndroid || Platform.isIOS
+ ? null
+ : _requestDownloadsDirectory,
+ ),
+ ),
+ FutureBuilder<Directory?>(
+ future: _downloadsDirectory,
+ builder: _buildDirectory,
+ ),
+ ],
+ ),
],
),
),
diff --git a/packages/path_provider/path_provider/example/macos/Runner/DebugProfile.entitlements b/packages/path_provider/path_provider/example/macos/Runner/DebugProfile.entitlements
index dddb8a3..f83e1f4 100644
--- a/packages/path_provider/path_provider/example/macos/Runner/DebugProfile.entitlements
+++ b/packages/path_provider/path_provider/example/macos/Runner/DebugProfile.entitlements
@@ -8,5 +8,7 @@
<true/>
<key>com.apple.security.network.server</key>
<true/>
+ <key>com.apple.security.files.downloads.read-write</key>
+ <true/>
</dict>
</plist>
diff --git a/packages/path_provider/path_provider/example/macos/Runner/Release.entitlements b/packages/path_provider/path_provider/example/macos/Runner/Release.entitlements
index 852fa1a..9d37992 100644
--- a/packages/path_provider/path_provider/example/macos/Runner/Release.entitlements
+++ b/packages/path_provider/path_provider/example/macos/Runner/Release.entitlements
@@ -4,5 +4,7 @@
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
+ <key>com.apple.security.files.downloads.read-write</key>
+ <true/>
</dict>
</plist>
diff --git a/packages/path_provider/path_provider/pubspec.yaml b/packages/path_provider/path_provider/pubspec.yaml
index 0c2b391..ea08369 100644
--- a/packages/path_provider/path_provider/pubspec.yaml
+++ b/packages/path_provider/path_provider/pubspec.yaml
@@ -2,7 +2,7 @@
description: Flutter plugin for getting commonly used locations on host platform file systems, such as the temp and app data directories.
repository: https://github.com/flutter/plugins/tree/main/packages/path_provider/path_provider
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22
-version: 2.0.8
+version: 2.0.9
environment:
sdk: ">=2.14.0 <3.0.0"
