From cf308cd4cb6f1e1b9759c4e3174608472ea1ef0e Mon Sep 17 00:00:00 2001 From: player-03 Date: Thu, 7 Oct 2021 13:30:58 -0400 Subject: [PATCH] Clarify `FileDialog.hx` documentation. If we're going to write documentation here, we should include all the features and edge cases. --- src/lime/ui/FileDialog.hx | 76 ++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/src/lime/ui/FileDialog.hx b/src/lime/ui/FileDialog.hx index 01856a5a2..95d88e31f 100644 --- a/src/lime/ui/FileDialog.hx +++ b/src/lime/ui/FileDialog.hx @@ -20,8 +20,7 @@ import js.html.Blob; #end /** - Simple file dialog used for asking user where to save a file, or select - files to open. + Simple file dialog used for asking user where to save a file, or select files to open. Example usage: ```haxe @@ -31,13 +30,16 @@ import js.html.Blob; fileDialog.onSave.add( path -> trace("File saved in " + path) ); - fileDialog.onOpen.add( res -> trace("Size of the file = " + cast(res, haxe.io.Bytes).length) ); + fileDialog.onOpen.add( res -> trace("Size of the file = " + (res:haxe.io.Bytes).length) ); if ( fileDialog.open("jpg", null, "Load file") ) - trace("Triggered opening file"); + trace("File dialog opened, waiting for selection..."); else trace("This dialog is unsupported."); ``` + + Availability note: most file dialog operations are only available on desktop targets, though + `save()` is also available in HTML5. **/ #if !lime_debug @@ -50,29 +52,31 @@ class FileDialog { /** - Handles clicking the "Cancel" button by the user. It is also triggered on unsupported platforms (like HTML5 for `open()`). + Triggers when the user clicks "Cancel" during any operation, or when a function is unsupported + (such as `open()` on HTML5). **/ public var onCancel = new EventVoid>(); /** - Triggers when file was successfuly opened. `lime.utils.Resource` is the argument passed - which in essence is `haxe.io.Bytes` of the selected file's contents. Triggers only when used with `open()`. + Triggers when `open()` is successful. The `lime.utils.Resource` contains the file's data, and can + be implicitly cast to `haxe.io.Bytes`. **/ public var onOpen = new EventVoid>(); /** - Triggers when file was successfuly saved by the user. Argument is `String` - the path under which the file was saved. - Triggers only when used with `save()`. + Triggers when `save()` is successful. The `String` is the path to the saved file. **/ public var onSave = new EventVoid>(); /** - Selected single file from `browse()`. Passes `String` path to the file. + Triggers when `browse()` is successful and `type` is anything other than + `FileDialogType.OPEN_MULTIPLE`. The `String` is the path to the selected file. **/ public var onSelect = new EventVoid>(); /** - Is called with array of selected file paths from `browse()` with `FileDialogType.OPEN_MULTIPLE`. + Triggers when `browse()` is successful and `type` is `FileDialogType.OPEN_MULTIPLE`. The + `Array` contains all selected file paths. **/ public var onSelectMultiple = new Event->Void>(); @@ -80,12 +84,17 @@ class FileDialog public function new() {} /** - Opens a file dialog that will trigger either `onSelect` or `onSelectMultiple` returting path(s) to file(s). - @param type type of the file dialog: `OPEN`, `SAVE`, `OPEN_DIRECTORY` or `OPEN_MULTIPLE`. - @param filter filter to be used when browsing for the file. For example for `"*.jpg"` it will be `"jpg"`. - @param defaultPath directory in which to start browsing. Default is current working directory of the application. - @param title title to give the dialog window. - @return `false` if the dialog is unsupported. + Opens a file selection dialog. If successful, either `onSelect` or `onSelectMultiple` will trigger + with the result(s). + + This function only works on desktop targets, and will return `false` otherwise. + @param type Type of the file dialog: `OPEN`, `SAVE`, `OPEN_DIRECTORY` or `OPEN_MULTIPLE`. + @param filter A filter to use when browsing. Asterisks are treated as wildcards. For example, + `"*.jpg"` will match any file ending in `.jpg`. + @param defaultPath The directory in which to start browsing and/or the default filename to + suggest. Defaults to `Sys.getCwd()`, with no default filename. + @param title The title to give the dialog window. + @return Whether `browse()` is supported on this target. **/ public function browse(type:FileDialogType = null, filter:String = null, defaultPath:String = null, title:String = null):Bool { @@ -213,11 +222,15 @@ class FileDialog } /** - Shows an open file dialog and immediately returns the contents of the file in `onOpen` listeners. - @param filter filter to be used when browsing for the file. For example for `"*.jpg"` it will be `"jpg"`. - @param defaultPath directory in which to start browsing. Default is current working directory of the application. - @param title title to give the dialog window. - @return `false` if the dialog is unsupported. + Shows an open file dialog. If successful, `onOpen` will trigger with the file contents. + + This function only works on desktop targets, and will return `false` otherwise. + @param filter A filter to use when browsing. Asterisks are treated as wildcards. For example, + `"*.jpg"` will match any file ending in `.jpg`. + @param defaultPath The directory in which to start browsing and/or the default filename to + suggest. Defaults to `Sys.getCwd()`, with no default filename. + @param title The title to give the dialog window. + @return Whether `open()` is supported on this target. **/ public function open(filter:String = null, defaultPath:String = null, title:String = null):Bool { @@ -267,12 +280,19 @@ class FileDialog } /** - Asks the user where to save the `data`. Will return path of the saved file in `onSave`. - @param filter filter to be used when browsing for the file. For example for `"*.jpg"` it will be `"jpg"`. - @param defaultPath directory in which to start browsing. Default is current working directory of the application. - @param title title to give the dialog window. - @param type MIME type of the file. Used only on HTML5 targets. - @return `false` if the dialog is unsupported. + Shows an open file dialog. If successful, `onSave` will trigger with the selected path. + + This function only works on desktop and HMTL5 targets, and will return `false` otherwise. + @param data The file contents, in `haxe.io.Bytes` format. (Implicit casting possible.) + @param filter A filter to use when browsing. Asterisks are treated as wildcards. For example, + `"*.jpg"` will match any file ending in `.jpg`. Used only if targeting deskop. + @param defaultPath The directory in which to start browsing and/or the default filename to + suggest. When targeting destkop, this defaults to `Sys.getCwd()` with no default filename. When targeting + HTML5, this defaults to the browser's download directory, with a default filename based on the MIME type. + @param title The title to give the dialog window. + @param type The default MIME type of the file, in case the type can't be determined from the + file data. Used only if targeting HTML5. + @return Whether `save()` is supported on this target. **/ public function save(data:Resource, filter:String = null, defaultPath:String = null, title:String = null, type:String = "application/octet-stream"):Bool {