[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,6 @@
+## 0.8.3+1
+* Improve API docs and examples
+
 ## 0.8.3
 
 * Adds an endorsed Windows implementation.

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

@@ -15,8 +15,11 @@ class OpenImagePage extends StatelessWidget {
       label: 'images',
       extensions: <String>['jpg', 'png'],
     );
-    final List<XFile> files =
-        await openFiles(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
+    final List<XFile> files = await openFiles(
+      acceptedTypeGroups: <XTypeGroup>[typeGroup],
+      initialDirectory: '/',
+      confirmButtonText: 'select image file',
+    );
     if (files.isEmpty) {
       // Operation was canceled by the user.
       return;

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

@@ -19,10 +19,14 @@ class OpenMultipleImagesPage extends StatelessWidget {
       label: 'PNGs',
       extensions: <String>['png'],
     );
-    final List<XFile> files = await openFiles(acceptedTypeGroups: <XTypeGroup>[
-      jpgsTypeGroup,
-      pngTypeGroup,
-    ]);
+    final List<XFile> files = await openFiles(
+      acceptedTypeGroups: <XTypeGroup>[
+        jpgsTypeGroup,
+        pngTypeGroup,
+      ],
+      initialDirectory: '/',
+      confirmButtonText: 'select image files',
+    );
     if (files.isEmpty) {
       // Operation was canceled by the user.
       return;

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

@@ -12,8 +12,11 @@ class OpenTextPage extends StatelessWidget {
       label: 'text',
       extensions: <String>['txt', 'json'],
     );
-    final XFile? file =
-        await openFile(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
+    final XFile? file = await openFile(
+      acceptedTypeGroups: <XTypeGroup>[typeGroup],
+      initialDirectory: '/',
+      confirmButtonText: 'select text file',
+    );
     if (file == null) {
       // Operation was canceled by the user.
       return;

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

@@ -12,17 +12,20 @@ class SaveTextPage extends StatelessWidget {
   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 XFile textFile = XFile.fromData(fileData, mimeType: fileMimeType);
+    final String? path = await getSavePath(
+      initialDirectory: '/',
+      suggestedName: fileName,
+    );
+    if (path == null) {
+      // Operation was canceled by the user.
+      return;
+    }
+
     await textFile.saveTo(path);
   }
 

packages/file_selector/file_selector/lib/file_selector.dart

@@ -10,6 +10,18 @@ export 'package:file_selector_platform_interface/file_selector_platform_interfac
     show XFile, XTypeGroup;
 
 /// Open file dialog for loading files and return a file path
+///
+/// The [acceptedTypeGroups] argument is the file type that can be selected in the dialog.
+/// When omitted, Open file dialog with all file types.
+///
+/// The [initialDirectory] argument is directory that will be displayed when the dialog is opened.
+/// (NOTICE: specify a directory as a full path, not a relative path.)
+/// When omitted, The result of each platform's `getDirectoryPath()` execution is used.
+///
+/// The [confirmButtonText] argument is the text in the confirmation button of the dialog.
+/// When omitted, the wording specified in the OS standard is used.(e.g. open)
+///
+/// Returns `null` if user cancels the operation.
 Future<XFile?> openFile({
   List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
   String? initialDirectory,
@@ -22,6 +34,16 @@ Future<XFile?> openFile({
 }
 
 /// Open file dialog for loading files and return a list of file paths
+///
+/// The [acceptedTypeGroups] argument is the file type that can be selected in the dialog.
+/// When omitted, Open file dialog with all file types.
+///
+/// The [initialDirectory] argument is directory that will be displayed when the dialog is opened.
+/// (NOTICE: specify a directory as a full path, not a relative path.)
+/// When omitted, The result of each platform's `getDirectoryPath()` execution is used.
+///
+/// The [confirmButtonText] argument is the text in the confirmation button of the dialog.
+/// When omitted, the wording specified in the OS standard is used.(e.g. open)
 Future<List<XFile>> openFiles({
   List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
   String? initialDirectory,
@@ -34,6 +56,21 @@ Future<List<XFile>> openFiles({
 }
 
 /// Saves File to user's file system
+///
+/// The [acceptedTypeGroups] argument is the file type that can be selected in the dialog.
+/// When omitted, Open file dialog with all file types.
+///
+/// The [initialDirectory] argument is directory that will be displayed when the dialog is opened.
+/// (NOTICE: specify a directory as a full path, not a relative path.)
+/// When omitted, The result of each platform's `getDirectoryPath()` execution is used.
+///
+/// The [suggestedName] argument is he name of the file to save.
+/// When omitted, use UUID(version4) as file name.
+///
+/// The [confirmButtonText] argument is the text in the confirmation button of the dialog.
+/// When omitted, the wording specified in the OS standard is used.(e.g. open)
+///
+/// Returns `null` if user cancels the operation.
 Future<String?> getSavePath({
   List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
   String? initialDirectory,
@@ -48,6 +85,15 @@ Future<String?> getSavePath({
 }
 
 /// Gets a directory path from a user's file system
+///
+/// The [initialDirectory] argument is directory that will be displayed when the dialog is opened.
+/// (NOTICE: specify a directory as a full path, not a relative path.)
+/// When omitted, The result of each platform's `getDirectoryPath()` execution is used.
+///
+/// The [confirmButtonText] argument is the text in the confirmation button of the dialog.
+/// When omitted, the wording specified in the OS standard is used.(e.g. open)
+///
+/// Returns `null` if user cancels the operation.
 Future<String?> getDirectoryPath({
   String? initialDirectory,
   String? confirmButtonText,

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.8.3
+version: 0.8.3+1
 
 environment:
   sdk: ">=2.12.0 <3.0.0"