Skip to content
This repository has been archived by the owner on Feb 22, 2023. It is now read-only.

[file_selector]Improve API docs and examples #4824

Merged
merged 27 commits into from
Jun 9, 2022
Merged

[file_selector]Improve API docs and examples #4824

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
6c71647
Add detail comment in file_selector
TowaYamashita Feb 13, 2022
b021530
change sample code for file_selector
TowaYamashita Feb 13, 2022
a6cc58f
Update CHAGELOG.md
TowaYamashita Feb 13, 2022
08a3dea
Fix CHANGELOG version
TowaYamashita Feb 13, 2022
2b391d6
Remove const from MyApp() in widget test
TowaYamashita Feb 13, 2022
fe10180
Sort directive sections alphabetically
TowaYamashita Feb 13, 2022
09d9bf8
Update Authors
TowaYamashita Feb 13, 2022
a3a820d
Fix my mailaddress
TowaYamashita Feb 13, 2022
422b133
remove accidentally created test
TowaYamashita Feb 17, 2022
63bbfe8
fix comment of function in file_selector.dart
TowaYamashita Mar 27, 2022
55bd1a5
install path_provider
TowaYamashita Mar 27, 2022
d51b01c
change initial directory to useful example
TowaYamashita Mar 27, 2022
cbed80f
fix not to regress web
TowaYamashita Mar 27, 2022
d9dc0bc
fix typo
TowaYamashita Mar 27, 2022
229657d
fix button labels not to change in example
TowaYamashita Mar 27, 2022
d190b51
fix CHANGELOG.md to follow CHANGELOG style
TowaYamashita Mar 27, 2022
c31eea7
Merge branch 'main' into towayamashita-patch-1
TowaYamashita Mar 27, 2022
750f8b7
Merge branch 'main' into towayamashita-patch-1
stuartmorgan Jun 7, 2022
ef47a7a
Remove some use of initialDirectory, and add comments on the others
stuartmorgan Jun 7, 2022
e0eac1a
Clean up comments
stuartmorgan Jun 7, 2022
bbe266d
Missing newline
stuartmorgan Jun 7, 2022
bd4e16b
Accidentally missed changes
stuartmorgan Jun 7, 2022
fda0ed5
Fix bug in singe-image example
stuartmorgan Jun 7, 2022
e982e74
Convert to code-excerpt
stuartmorgan Jun 7, 2022
28fe8a4
Apply suggestions from code review
stuartmorgan Jun 9, 2022
93a87a5
Merge branch 'main' into towayamashita-patch-1
stuartmorgan Jun 9, 2022
73d596e
Update save example
stuartmorgan Jun 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/file_selector/file_selector/AUTHORS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,4 @@ Aleksandr Yurkovskiy <[email protected]>
Anton Borries <[email protected]>
Alex Li <[email protected]>
Rahul Raj <[email protected]>
TowaYamashita <[email protected]>
3 changes: 3 additions & 0 deletions packages/file_selector/file_selector/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
## 0.8.3+1
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
* Improve API docs and examples
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please follow the CHANGELOG style guide linked from the PR checklist.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not fully resolved; it should be "Improves", not "Improve", as shown in the style guide.


## 0.8.3

* Adds an endorsed Windows implementation.
Expand Down
7 changes: 5 additions & 2 deletions packages/file_selector/file_selector/example/lib/open_image_page.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: '/',
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
confirmButtonText: 'select image file',
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
);
if (files.isEmpty) {
// Operation was canceled by the user.
return;
Expand Down
12 changes: 8 additions & 4 deletions packages/file_selector/file_selector/example/lib/open_multiple_images_page.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
);
if (files.isEmpty) {
// Operation was canceled by the user.
return;
Expand Down
7 changes: 5 additions & 2 deletions packages/file_selector/file_selector/example/lib/open_text_page.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
17 changes: 10 additions & 7 deletions packages/file_selector/file_selector/example/lib/save_text_page.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
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);
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
final String? path = await getSavePath(
initialDirectory: '/',
suggestedName: fileName,
);
if (path == null) {
// Operation was canceled by the user.
return;
}

await textFile.saveTo(path);
}

Expand Down
46 changes: 46 additions & 0 deletions packages/file_selector/file_selector/lib/file_selector.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not a file type, it's a list of possible file types.

It would also be useful to give examples of how this will work on different platforms. E.g., on Windows each group will be an entry in a list of filter options, while on macOS (where there is no such UI, the union of all types allowed by all of the groups will be allowed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has not been resolved.

stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
/// When omitted, Open file dialog with all file types.
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
///
/// 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.)
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
/// When omitted, The result of each platform's `getDirectoryPath()` execution is used.
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
///
/// 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)
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
///
/// Returns `null` if user cancels the operation.
Future<XFile?> openFile({
List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
String? initialDirectory,
Expand All @@ -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({
stuartmorgan marked this conversation as resolved.
Show resolved Hide resolved
List<XTypeGroup> acceptedTypeGroups = const <XTypeGroup>[],
String? initialDirectory,
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/he/the/

This also makes it sound like it forces a name. It's actually just the initial value of the name.

/// When omitted, use UUID(version4) as file name.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What? I have no idea what this is referring to.

///
/// 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,
Expand All @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion packages/file_selector/file_selector/pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down