[file_selector]Improve API docs and examples (flutter#4824)

Author: TowaYamashita

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,5 +1,6 @@
-## NEXT
+## 0.8.4+3
 
+* Improves API docs and examples.
 * Minor fixes for new analysis options.
 
 ## 0.8.4+2

packages/file_selector/file_selector/README.md

@@ -1,5 +1,7 @@
 # file_selector
 
+<?code-excerpt path-base="excerpts/packages/file_selector_example"?>
+
 [![pub package](https://img.shields.io/pub/v/file_selector.svg)](https://pub.dartlang.org/packages/file_selector)
 
 A Flutter plugin that manages files and interactions with file dialogs.
@@ -30,25 +32,48 @@ 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
-final typeGroup = XTypeGroup(label: 'images', extensions: ['jpg', 'png']);
-final file = await openFile(acceptedTypeGroups: [typeGroup]);
+final XTypeGroup typeGroup = XTypeGroup(
+  label: 'images',
+  extensions: <String>['jpg', 'png'],
+);
+final XFile? file =
+    await openFile(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
 ```
 
 #### Open multiple files at once
+<?code-excerpt "open_multiple_images_page.dart (MultiOpen)"?>
 ``` dart
-final typeGroup = XTypeGroup(label: 'images', extensions: ['jpg', 'png']);
-final files = await openFiles(acceptedTypeGroups: [typeGroup]);
+final XTypeGroup jpgsTypeGroup = XTypeGroup(
+  label: 'JPEGs',
+  extensions: <String>['jpg', 'jpeg'],
+);
+final XTypeGroup pngTypeGroup = XTypeGroup(
+  label: 'PNGs',
+  extensions: <String>['png'],
+);
+final List<XFile> files = await openFiles(acceptedTypeGroups: <XTypeGroup>[
+  jpgsTypeGroup,
+  pngTypeGroup,
+]);
 ```
 
 #### Saving a file
+<?code-excerpt "readme_standalone_excerpts.dart (Save)"?>
 ```dart
-final path = await getSavePath();
-final name = "hello_file_selector.txt";
-final data = Uint8List.fromList("Hello World!".codeUnits);
-final mimeType = "text/plain";
-final file = XFile.fromData(data, name: name, mimeType: mimeType);
-await file.saveTo(path);
+const String fileName = 'suggested_name.txt';
+final String? path = await getSavePath(suggestedName: fileName);
+if (path == null) {
+  // Operation was canceled by the user.
+  return;
+}
+
+final Uint8List fileData = Uint8List.fromList('Hello World!'.codeUnits);
+const String mimeType = 'text/plain';
+final XFile textFile =
+    XFile.fromData(fileData, mimeType: mimeType, name: fileName);
+await textFile.saveTo(path);
 ```
 
 [example]:./example

packages/file_selector/file_selector/example/build.excerpt.yaml

@@ -0,0 +1,15 @@
+targets:
+  $default:
+    sources:
+      include:
+        - lib/**
+        # Some default includes that aren't really used here but will prevent
+        # false-negative warnings:
+        - $package$
+        - lib/$lib$
+      exclude:
+        - '**/.*/**'
+        - '**/build/**'
+    builders:
+      code_excerpter|code_excerpter:
+        enabled: true

packages/file_selector/file_selector/example/lib/main.dart

@@ -2,14 +2,15 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'package:example/get_directory_page.dart';
-import 'package:example/home_page.dart';
-import 'package:example/open_image_page.dart';
-import 'package:example/open_multiple_images_page.dart';
-import 'package:example/open_text_page.dart';
-import 'package:example/save_text_page.dart';
 import 'package:flutter/material.dart';
 
+import 'get_directory_page.dart';
+import 'home_page.dart';
+import 'open_image_page.dart';
+import 'open_multiple_images_page.dart';
+import 'open_text_page.dart';
+import 'save_text_page.dart';
+
 void main() {
   runApp(const MyApp());
 }

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

@@ -14,17 +14,18 @@ class OpenImagePage extends StatelessWidget {
   const OpenImagePage({Key? key}) : super(key: key);
 
   Future<void> _openImageFile(BuildContext context) async {
+    // #docregion SingleOpen
     final XTypeGroup typeGroup = XTypeGroup(
       label: 'images',
       extensions: <String>['jpg', 'png'],
     );
-    final List<XFile> files =
-        await openFiles(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
-    if (files.isEmpty) {
+    final XFile? file =
+        await openFile(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
+    // #enddocregion SingleOpen
+    if (file == null) {
       // Operation was canceled by the user.
       return;
     }
-    final XFile file = files[0];
     final String fileName = file.name;
     final String filePath = file.path;
 

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

@@ -14,6 +14,7 @@ class OpenMultipleImagesPage extends StatelessWidget {
   const OpenMultipleImagesPage({Key? key}) : super(key: key);
 
   Future<void> _openImageFile(BuildContext context) async {
+    // #docregion MultiOpen
     final XTypeGroup jpgsTypeGroup = XTypeGroup(
       label: 'JPEGs',
       extensions: <String>['jpg', 'jpeg'],
@@ -26,6 +27,7 @@ class OpenMultipleImagesPage extends StatelessWidget {
       jpgsTypeGroup,
       pngTypeGroup,
     ]);
+    // #enddocregion MultiOpen
     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 {
@@ -15,8 +16,15 @@ class OpenTextPage extends StatelessWidget {
       label: 'text',
       extensions: <String>['txt', 'json'],
     );
-    final XFile? file =
-        await openFile(acceptedTypeGroups: <XTypeGroup>[typeGroup]);
+    // This demonstrates using an initial directory for the prompt, which should
+    // only be done in cases where the application can likely predict where the
+    // file would be. In most cases, this parameter should not be provided.
+    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/readme_standalone_excerpts.dart

@@ -0,0 +1,57 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// This file exists solely to host compiled excerpts for README.md, and is not
+// intended for use as an actual example application.
+
+// ignore_for_file: public_member_api_docs
+
+// TODO(a14n): remove this import once Flutter 3.1 or later reaches stable (including flutter/flutter#104231)
+// ignore: unnecessary_import
+import 'dart:typed_data';
+
+import 'package:file_selector/file_selector.dart';
+import 'package:flutter/material.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatefulWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  State<MyApp> createState() => _MyAppState();
+}
+
+class _MyAppState extends State<MyApp> {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        appBar: AppBar(
+          title: const Text('README snippet app'),
+        ),
+        body: const Text('See example in main.dart'),
+      ),
+    );
+  }
+
+  Future<void> saveFile() async {
+    // #docregion Save
+    const String fileName = 'suggested_name.txt';
+    final String? path = await getSavePath(suggestedName: fileName);
+    if (path == null) {
+      // Operation was canceled by the user.
+      return;
+    }
+
+    final Uint8List fileData = Uint8List.fromList('Hello World!'.codeUnits);
+    const String mimeType = 'text/plain';
+    final XFile textFile =
+        XFile.fromData(fileData, mimeType: mimeType, name: fileName);
+    await textFile.saveTo(path);
+    // #enddocregion Save
+  }
+}

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

@@ -5,6 +5,7 @@
 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 {
@@ -15,17 +16,27 @@ class SaveTextPage extends StatelessWidget {
   final TextEditingController _contentController = TextEditingController();
 
   Future<void> _saveFile() async {
-    final String? path = await getSavePath();
+    final String fileName = _nameController.text;
+    // This demonstrates using an initial directory for the prompt, which should
+    // only be done in cases where the application can likely predict where the
+    // file will be saved. In most cases, this parameter should not be provided.
+    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;
     }
+
     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);
+
     await textFile.saveTo(path);
   }
 

packages/file_selector/file_selector/example/pubspec.yaml

@@ -1,4 +1,4 @@
-name: example
+name: file_selector_example
 description: A new Flutter project.
 publish_to: none
 
@@ -17,8 +17,10 @@ dependencies:
     path: ../
   flutter:
     sdk: flutter
+  path_provider: ^2.0.9
 
 dev_dependencies:
+  build_runner: ^2.1.10
   flutter_test:
     sdk: flutter
 

packages/file_selector/file_selector/example/windows/flutter/generated_plugins.cmake

@@ -6,6 +6,9 @@ list(APPEND FLUTTER_PLUGIN_LIST
   file_selector_windows
 )
 
+list(APPEND FLUTTER_FFI_PLUGIN_LIST
+)
+
 set(PLUGIN_BUNDLED_LIBRARIES)
 
 foreach(plugin ${FLUTTER_PLUGIN_LIST})
@@ -14,3 +17,8 @@ foreach(plugin ${FLUTTER_PLUGIN_LIST})
   list(APPEND PLUGIN_BUNDLED_LIBRARIES $<TARGET_FILE:${plugin}_plugin>)
   list(APPEND PLUGIN_BUNDLED_LIBRARIES ${${plugin}_bundled_libraries})
 endforeach(plugin)
+
+foreach(ffi_plugin ${FLUTTER_FFI_PLUGIN_LIST})
+  add_subdirectory(flutter/ephemeral/.plugin_symlinks/${ffi_plugin}/windows plugins/${ffi_plugin})
+  list(APPEND PLUGIN_BUNDLED_LIBRARIES ${${ffi_plugin}_bundled_libraries})
+endforeach(ffi_plugin)