[file_selector] Include the missing GetDirectoryPath method example and table of supported platforms (#6454)

Author: VanesaOshiro

packages/file_selector/file_selector/CHANGELOG.md

@@ -1,5 +1,6 @@
-## 0.9.2+1
+## 0.9.2+2
 
+* Improves API docs and examples.
 * Changes XTypeGroup initialization from final to const.
 * Updates minimum Flutter version to 2.10.
 

packages/file_selector/file_selector/README.md

@@ -11,6 +11,7 @@ A Flutter plugin that manages files and interactions with file dialogs.
 | **Support** | iOS 9+ | Any   | 10.11+ | Any | Windows 10+ |
 
 ## Usage
+
 To use this plugin, add `file_selector` as a [dependency in your pubspec.yaml file](https://flutter.dev/platform-plugins/).
 
 ### macOS
@@ -28,10 +29,12 @@ or read/write access:
 depending on your use case.
 
 ### Examples
+
 Here are small examples that show you how to use the API.
 Please also take a look at our [example][example] app.
 
 #### Open a single file
+
 <?code-excerpt "open_image_page.dart (SingleOpen)"?>
 ``` dart
 const XTypeGroup typeGroup = XTypeGroup(
@@ -43,6 +46,7 @@ final XFile? file =
 ```
 
 #### Open multiple files at once
+
 <?code-excerpt "open_multiple_images_page.dart (MultiOpen)"?>
 ``` dart
 const XTypeGroup jpgsTypeGroup = XTypeGroup(
@@ -59,7 +63,8 @@ final List<XFile> files = await openFiles(acceptedTypeGroups: <XTypeGroup>[
 ]);
 ```
 
-#### Saving a file
+#### Save a file
+
 <?code-excerpt "readme_standalone_excerpts.dart (Save)"?>
 ```dart
 const String fileName = 'suggested_name.txt';
@@ -76,6 +81,17 @@ final XFile textFile =
 await textFile.saveTo(path);
 ```
 
+#### Get a directory path
+
+<?code-excerpt "readme_standalone_excerpts.dart (GetDirectory)"?>
+```dart
+final String? directoryPath = await getDirectoryPath();
+if (directoryPath == null) {
+  // Operation was canceled by the user.
+  return;
+}
+```
+
 ### Filtering by file types
 
 Different platforms support different type group filter options. To avoid
@@ -92,5 +108,14 @@ pass different `XTypeGroup`s based on `Platform`.
 
 † `mimeTypes` are not supported on version of macOS earlier than 11 (Big Sur).
 
+### Features supported by platform
+
+| Feature                | Description                        | iOS      | Linux      | macOS    | Windows      | Web         |
+| ---------------------- |----------------------------------- |--------- | ---------- | -------- | ------------ | ----------- |
+| Choose a single file   | Pick a file/image                  | ✔️       | ✔️        | ✔️       | ✔️          | ✔️          |
+| Choose multiple files  | Pick multiple files/images         | ✔️       | ✔️        | ✔️       | ✔️          | ✔️          |
+| Choose a save location | Pick a directory to save a file in | ❌       | ✔️        | ✔️       | ✔️          | ❌          |
+| Choose a directory     | Pick a folder and get its path     | ❌       | ✔️        | ✔️       | ✔️          | ❌          |
+
 [example]:./example
-[entitlement]: https://docs.flutter.dev/desktop#entitlements-and-the-app-sandbox
+[entitlement]: https://docs.flutter.dev/desktop#entitlements-and-the-app-sandbox

packages/file_selector/file_selector/example/lib/readme_standalone_excerpts.dart

@@ -54,4 +54,14 @@ class _MyAppState extends State<MyApp> {
     await textFile.saveTo(path);
     // #enddocregion Save
   }
+
+  Future<void> directoryPath() async {
+    // #docregion GetDirectory
+    final String? directoryPath = await getDirectoryPath();
+    if (directoryPath == null) {
+      // Operation was canceled by the user.
+      return;
+    }
+    // #enddocregion GetDirectory
+  }
 }

packages/file_selector/file_selector/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for opening and saving files, or selecting
   directories, using native file selection UI.
 repository: https://github.com/flutter/plugins/tree/main/packages/file_selector/file_selector
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+file_selector%22
-version: 0.9.2+1
+version: 0.9.2+2
 
 environment:
   sdk: ">=2.12.0 <3.0.0"