[file_selector] Add file group to save return value - platform interface (#4254)

Platform interface portion of #4222

Part of flutter/flutter#107093

Author: stuartmorgan-g

packages/file_selector/file_selector/lib/file_selector.dart

@@ -98,6 +98,9 @@ Future<String?> getSavePath({
   String? suggestedName,
   String? confirmButtonText,
 }) async {
+  // TODO(stuartmorgan): Update this to getSaveLocation in the next federated
+  // change PR.
+  // ignore: deprecated_member_use
   return FileSelectorPlatform.instance.getSavePath(
       acceptedTypeGroups: acceptedTypeGroups,
       initialDirectory: initialDirectory,

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

@@ -17,6 +17,9 @@ class SaveTextPage extends StatelessWidget {
 
   Future<void> _saveFile() async {
     final String fileName = _nameController.text;
+    // TODO(stuartmorgan): Update this to getSaveLocation in the next federated
+    // change PR.
+    // ignore: deprecated_member_use
     final String? path = await FileSelectorPlatform.instance.getSavePath(
       // Operation was canceled by the user.
       suggestedName: fileName,

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

@@ -17,6 +17,9 @@ class SaveTextPage extends StatelessWidget {
 
   Future<void> _saveFile() async {
     final String fileName = _nameController.text;
+    // TODO(stuartmorgan): Update this to getSaveLocation in the next federated
+    // change PR.
+    // ignore: deprecated_member_use
     final String? path = await FileSelectorPlatform.instance.getSavePath(
       suggestedName: fileName,
     );

packages/file_selector/file_selector_platform_interface/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.6.0
+
+* Adds `getSaveLocation` and deprecates `getSavePath`.
+
 ## 2.5.1
 
 * Adds compatibility with `http` 1.0.

packages/file_selector/file_selector_platform_interface/lib/src/platform_interface/file_selector_interface.dart

@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'dart:async';
-
 import 'package:plugin_platform_interface/plugin_platform_interface.dart';
 
 import '../../file_selector_platform_interface.dart';
@@ -37,7 +35,10 @@ abstract class FileSelectorPlatform extends PlatformInterface {
   }
 
   /// Opens a file dialog for loading files and returns a file path.
-  /// Returns `null` if user cancels the operation.
+  ///
+  /// Returns `null` if the user cancels the operation.
+  // TODO(stuartmorgan): Switch to FileDialogOptions if we ever need to
+  // duplicate this to add a parameter.
   Future<XFile?> openFile({
     List<XTypeGroup>? acceptedTypeGroups,
     String? initialDirectory,
@@ -47,6 +48,10 @@ abstract class FileSelectorPlatform extends PlatformInterface {
   }
 
   /// Opens a file dialog for loading files and returns a list of file paths.
+  ///
+  /// Returns an empty list if the user cancels the operation.
+  // TODO(stuartmorgan): Switch to FileDialogOptions if we ever need to
+  // duplicate this to add a parameter.
   Future<List<XFile>> openFiles({
     List<XTypeGroup>? acceptedTypeGroups,
     String? initialDirectory,
@@ -55,8 +60,13 @@ abstract class FileSelectorPlatform extends PlatformInterface {
     throw UnimplementedError('openFiles() has not been implemented.');
   }
 
-  /// Opens a file dialog for saving files and returns a file path at which to save.
-  /// Returns `null` if user cancels the operation.
+  /// Opens a file dialog for saving files and returns a file path at which to
+  /// save.
+  ///
+  /// Returns `null` if the user cancels the operation.
+  // TODO(stuartmorgan): Switch to FileDialogOptions if we ever need to
+  // duplicate this to add a parameter.
+  @Deprecated('Use getSaveLocation instead')
   Future<String?> getSavePath({
     List<XTypeGroup>? acceptedTypeGroups,
     String? initialDirectory,
@@ -66,16 +76,41 @@ abstract class FileSelectorPlatform extends PlatformInterface {
     throw UnimplementedError('getSavePath() has not been implemented.');
   }
 
+  /// Opens a file dialog for saving files and returns a file location at which
+  /// to save.
+  ///
+  /// Returns `null` if the user cancels the operation.
+  Future<FileSaveLocation?> getSaveLocation({
+    List<XTypeGroup>? acceptedTypeGroups,
+    SaveDialogOptions options = const SaveDialogOptions(),
+  }) async {
+    final String? path = await getSavePath(
+      acceptedTypeGroups: acceptedTypeGroups,
+      initialDirectory: options.initialDirectory,
+      suggestedName: options.suggestedName,
+      confirmButtonText: options.confirmButtonText,
+    );
+    return path == null ? null : FileSaveLocation(path);
+  }
+
   /// Opens a file dialog for loading directories and returns a directory path.
-  /// Returns `null` if user cancels the operation.
+  ///
+  /// Returns `null` if the user cancels the operation.
+  // TODO(stuartmorgan): Switch to FileDialogOptions if we ever need to
+  // duplicate this to add a parameter.
   Future<String?> getDirectoryPath({
     String? initialDirectory,
     String? confirmButtonText,
   }) {
     throw UnimplementedError('getDirectoryPath() has not been implemented.');
   }
 
-  /// Opens a file dialog for loading directories and returns multiple directory paths.
+  /// Opens a file dialog for loading directories and returns multiple directory
+  /// paths.
+  ///
+  /// Returns an empty list if the user cancels the operation.
+  // TODO(stuartmorgan): Switch to FileDialogOptions if we ever need to
+  // duplicate this to add a parameter.
   Future<List<String>> getDirectoryPaths({
     String? initialDirectory,
     String? confirmButtonText,

packages/file_selector/file_selector_platform_interface/lib/src/types/file_dialog_options.dart

@@ -0,0 +1,29 @@
+// 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.
+
+import 'package:flutter/foundation.dart' show immutable;
+
+/// Configuration options for any file selector dialog.
+@immutable
+class FileDialogOptions {
+  /// Creates a new options set with the given settings.
+  const FileDialogOptions({this.initialDirectory, this.confirmButtonText});
+
+  /// The initial directory the dialog should open with.
+  final String? initialDirectory;
+
+  /// The label for the button that confirms selection.
+  final String? confirmButtonText;
+}
+
+/// Configuration options for a save dialog.
+@immutable
+class SaveDialogOptions extends FileDialogOptions {
+  /// Creates a new options set with the given settings.
+  const SaveDialogOptions(
+      {super.initialDirectory, super.confirmButtonText, this.suggestedName});
+
+  /// The suggested name of the file to save or open.
+  final String? suggestedName;
+}

packages/file_selector/file_selector_platform_interface/lib/src/types/file_save_location.dart

@@ -0,0 +1,26 @@
+// 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.
+
+import 'package:flutter/foundation.dart' show immutable;
+
+import 'x_type_group.dart';
+
+export 'x_type_group.dart';
+
+/// The response from a save dialog.
+@immutable
+class FileSaveLocation {
+  /// Creates a result with the given [path] and optional other dialog state.
+  const FileSaveLocation(this.path, {this.activeFilter});
+
+  /// The path to save to.
+  final String path;
+
+  /// The currently active filter group, if any.
+  ///
+  /// This is null on platforms that do not support user-selectable filter
+  /// groups in save dialogs (for example, macOS), or when no filter groups
+  /// were provided when showing the dialog.
+  final XTypeGroup? activeFilter;
+}

packages/file_selector/file_selector_platform_interface/lib/src/types/types.dart

@@ -3,4 +3,6 @@
 // found in the LICENSE file.
 
 export 'package:cross_file/cross_file.dart';
-export 'x_type_group/x_type_group.dart';
+export 'file_dialog_options.dart';
+export 'file_save_location.dart';
+export 'x_type_group.dart';

packages/file_selector/file_selector_platform_interface/lib/src/types/x_type_group/x_type_group.dart renamed to packages/file_selector/file_selector_platform_interface/lib/src/types/x_type_group.dart

@@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/file_selector
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+file_selector%22
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 2.5.1
+version: 2.6.0
 
 environment:
   sdk: ">=2.18.0 <4.0.0"