[file_selector]Improve API docs and examples

packages/file_selector/file_selector/AUTHORS

@@ -63,3 +63,4 @@ Aleksandr Yurkovskiy <[email protected]>
 Anton Borries <[email protected]>
 Alex Li <[email protected]>
 Rahul Raj <[email protected]>
+TowaYamashita <[email protected]>

packages/file_selector/file_selector/CHANGELOG.md

@@ -1,3 +1,7 @@
+## NEXT
+
+* Improve API docs and examples.
+
 ## 0.8.4+1
 
 * Adds README information about macOS entitlements.

packages/file_selector/file_selector/example/lib/open_image_page.dart

@@ -7,6 +7,7 @@ import 'dart:io';
 import 'package:file_selector/file_selector.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'package:path_provider/path_provider.dart';
 
 /// Screen that shows an example of openFiles
 class OpenImagePage extends StatelessWidget {
@@ -15,8 +16,12 @@ class OpenImagePage extends StatelessWidget {
       label: 'images',
       extensions: <String>['jpg', 'png'],
     );
-    final List<XFile> files =
-        await openFiles(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
+    final String initialDirectory =
+        (await getApplicationDocumentsDirectory()).path;
+    final List<XFile> files = await openFiles(
+      acceptedTypeGroups: <XTypeGroup>[typeGroup],
+      initialDirectory: initialDirectory,
+    );
     if (files.isEmpty) {
       // Operation was canceled by the user.
       return;

packages/file_selector/file_selector/example/lib/open_multiple_images_page.dart

@@ -7,6 +7,7 @@ import 'dart:io';
 import 'package:file_selector/file_selector.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
+import 'package:path_provider/path_provider.dart';
 
 /// Screen that shows an example of openFiles
 class OpenMultipleImagesPage extends StatelessWidget {
@@ -19,10 +20,15 @@ class OpenMultipleImagesPage extends StatelessWidget {
       label: 'PNGs',
       extensions: <String>['png'],
     );
-    final List<XFile> files = await openFiles(acceptedTypeGroups: <XTypeGroup>[
-      jpgsTypeGroup,
-      pngTypeGroup,
-    ]);
+    final String initialDirectory =
+        (await getApplicationDocumentsDirectory()).path;
+    final List<XFile> files = await openFiles(
+      acceptedTypeGroups: <XTypeGroup>[
+        jpgsTypeGroup,
+        pngTypeGroup,
+      ],
+      initialDirectory: initialDirectory,
+    );
     if (files.isEmpty) {
       // Operation was canceled by the user.
       return;

packages/file_selector/file_selector/example/lib/open_text_page.dart

@@ -4,6 +4,7 @@
 
 import 'package:file_selector/file_selector.dart';
 import 'package:flutter/material.dart';
+import 'package:path_provider/path_provider.dart';
 
 /// Screen that shows an example of openFile
 class OpenTextPage extends StatelessWidget {
@@ -12,8 +13,12 @@ class OpenTextPage extends StatelessWidget {
       label: 'text',
       extensions: <String>['txt', 'json'],
     );
-    final XFile? file =
-        await openFile(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
+    final String initialDirectory =
+        (await getApplicationDocumentsDirectory()).path;
+    final XFile? file = await openFile(
+      acceptedTypeGroups: <XTypeGroup>[typeGroup],
+      initialDirectory: initialDirectory,
+    );
     if (file == null) {
       // Operation was canceled by the user.
       return;

packages/file_selector/file_selector/example/lib/save_text_page.dart

@@ -5,24 +5,31 @@
 import 'dart:typed_data';
 import 'package:file_selector/file_selector.dart';
 import 'package:flutter/material.dart';
+import 'package:path_provider/path_provider.dart';
 
 /// Page for showing an example of saving with file_selector
 class SaveTextPage extends StatelessWidget {
   final TextEditingController _nameController = TextEditingController();
   final TextEditingController _contentController = TextEditingController();
 
   Future<void> _saveFile() async {
-    final String? path = await getSavePath();
-    if (path == null) {
-      // Operation was canceled by the user.
-      return;
-    }
     final String text = _contentController.text;
     final String fileName = _nameController.text;
     final Uint8List fileData = Uint8List.fromList(text.codeUnits);
     const String fileMimeType = 'text/plain';
     final XFile textFile =
         XFile.fromData(fileData, mimeType: fileMimeType, name: fileName);
+    final String initialDirectory =
+        (await getApplicationDocumentsDirectory()).path;
+    final String? path = await getSavePath(
+      initialDirectory: initialDirectory,
+      suggestedName: fileName,
+    );
+    if (path == null) {
+      // Operation was canceled by the user.
+      return;
+    }
+
     await textFile.saveTo(path);
   }
 

packages/file_selector/file_selector/example/pubspec.yaml

@@ -17,6 +17,7 @@ dependencies:
     path: ../
   flutter:
     sdk: flutter
+  path_provider: ^2.0.9
 
 dev_dependencies:
   flutter_test:

packages/file_selector/file_selector/lib/file_selector.dart

@@ -9,7 +9,19 @@ import 'package:file_selector_platform_interface/file_selector_platform_interfac
 export 'package:file_selector_platform_interface/file_selector_platform_interface.dart'
     show XFile, XTypeGroup;
 
-/// Open file dialog for loading files and return a file path
+/// Open file dialog for loading files and return a file path.
+///
+/// [acceptedTypeGroups] is the file type that can be selected in the dialog.
+/// there are differences in behavior depending on the platform as follows.
+/// - Windows: Each group will be an entry in a list of filter options.
+/// - macOS: The union of all types allowed by all of the groups will be allowed.
+///
+/// [initialDirectory] is the full path to the directory that will be displayed when the dialog is opened.
+///
+/// [confirmButtonText] is the text in the confirmation button of the dialog.
+/// when omitted, the default OS label. (for example, "Open")
+///
+/// returns `null` if user cancels the operation.
 Future<XFile?> openFile({
   List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
   String? initialDirectory,
@@ -21,7 +33,17 @@ Future<XFile?> openFile({
       confirmButtonText: confirmButtonText);
 }
 
-/// Open file dialog for loading files and return a list of file paths
+/// Open file dialog for loading files and return a list of file paths.
+///
+/// [acceptedTypeGroups] is the file type that can be selected in the dialog.
+/// there are differences in behavior depending on the platform as follows.
+/// - Windows: Each group will be an entry in a list of filter options.
+/// - macOS: The union of all types allowed by all of the groups will be allowed.
+///
+/// [initialDirectory] is the full path to the directory that will be displayed when the dialog is opened.
+///
+/// [confirmButtonText] is the text in the confirmation button of the dialog.
+/// when omitted, the default OS label. (for example, "Open")
 Future<List<XFile>> openFiles({
   List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
   String? initialDirectory,
@@ -33,7 +55,21 @@ Future<List<XFile>> openFiles({
       confirmButtonText: confirmButtonText);
 }
 
-/// Saves File to user's file system
+/// Saves File to user's file system.
+///
+/// [acceptedTypeGroups] is the file type that can be selected in the dialog.
+/// There are differences in behavior depending on the platform as follows.
+/// - Windows: Each group will be an entry in a list of filter options.
+/// - macOS: The union of all types allowed by all of the groups will be allowed.
+///
+/// [initialDirectory] is the full path to the directory that will be displayed when the dialog is opened.
+///
+/// [suggestedName] is initial value of file name.
+///
+/// [confirmButtonText] is the text in the confirmation button of the dialog.
+/// when omitted, the default OS label. (for example, "Save")
+///
+/// returns `null` if user cancels the operation.
 Future<String?> getSavePath({
   List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
   String? initialDirectory,
@@ -47,7 +83,14 @@ Future<String?> getSavePath({
       confirmButtonText: confirmButtonText);
 }
 
-/// Gets a directory path from a user's file system
+/// Gets a directory path from a user's file system.
+///
+/// [initialDirectory] is the full path to the directory that will be displayed when the dialog is opened.
+///
+/// [confirmButtonText] is the text in the confirmation button of the dialog.
+/// when omitted, the default OS label. (for example, "Open")
+///
+/// returns `null` if user cancels the operation.
 Future<String?> getDirectoryPath({
   String? initialDirectory,
   String? confirmButtonText,

packages/file_selector/file_selector/pubspec.yaml

@@ -3,6 +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.8.4+1
 
 environment: