openFiles

Displays a file dialog window to let the user select a list of file paths on the local file system.

Syntax

ui.Interface.frontCall("standard", "openFiles",
 [path,name,wildcards,caption],
 [result])
  1. path - The default path of a directory like "/tmp".
  2. name - The label to be displayed for the file types / wildcards.
  3. wildcards - A space-separated list of file extensions with the star-dot prefix ("*.pdf *.jpg"). Supported file extensions is platform-specific. See Usage section for more details.
  4. caption - The caption to be displayed.
  5. result - The list of selected file paths as a JSON array (or NULL if canceled).

Usage

When invoking the "openFiles" front call, the front-end displays a file dialog window, to let the end user select several file paths from the local file system.

Note: The file dialog window rendering and features depend on the type of front end and the type of the front end platform (desktop OS, web browser).

This front call is typically used to let the end user select several files that will be processed by the application.

Important: With the GBC front-end in a web browser, the path parameter is ignored.
When the file dialog is validated, the result variable contains a JSON formatted string representing an array of file paths:
["/my/first/path",  "/my/second/path",  "/my/third/path"]

The resulting string can then be converted to a DYNAMIC ARRAY OF STRING with the util.JSON.parse() method.

Note: The order of the paths in the result variable can differ from the selection order of the user.

If the user cancels the dialog, the front call returns an empty JSON array ([]) in the result variable.

Tip: When specifying a file path, pay attention to platform specific rules regarding directory separators and space characters in file names. When the front-end executes on a recent Microsoft™ Windows™ system, you can use the / slash character as directory separator, like on Unix systems. A directory or file name can contain spaces, and there is no need to surround the path with double quotes in such case. When using backslash directory separators, make sure to escape backslash characters in string literals with \\.

When using the GMA or GMI front-end, the values returned by openFile and openFiles front calls contains a temporary system location of the file on the mobile device. This path is platform dependent, and may change in future versions. Consider the path returned by these front calls as an opaque local file identifier, and do not use this path as a persistent file name.

Once the file path is known, it is possible to fetch the file content from the device to the program context with the fgl_getfile() API. The procedure is similar to fetching photos from the device. For more details, see the section about file management on mobile devices.

Mobile platform specific notes for the openFile and openFiles front calls:
  • Android/GMA:
    • Using the openFile/openFiles front calls requires the android.permission.READ_EXTERNAL_STORAGE Dangerous Permissions to be specified when building the APK. See Android permissions for more details.
    • The values returned by the front call contain the filename and the extension as a URL query string format: ?name=filename&ext=extension
    • With the openFiles frontcall, the user must use a long tap to select multiple files. Otherwise, with a single tap, the openFiles frontcall will behave like openFile and return a unique element in the result array.
    • The path, name and caption parameters are ignored by GMA. The Android file manager opens by default the last folder where a file was selected. The first time the front call is executed on the device, it opens the "recent files" folder.
    • Supported wildcards are those listed in https://www.iana.org/assignments/media-types/media-types.xhtml (custom extensions are not supported)
    • See Handling files on Android devices for more details.
  • iOS/GMI:
    • The name and the caption parameters are ignored.
    • Prior to iOS 13, the path parameter is ignored and the file chooser always opens in the last location it was used. Startting with iOS 13, the path parameter is used: When running on the device, one can use os.Path.pwd() for example. When running remote, the current directory on the device cannot be known, but "." can be used as a synonym for the "Documents" directory on the device.
    • By default, common extensions like *.pdf or *.png are recognized. Custom extensions like *.err are by default grayed. To enable picking files with custom extension, it must be specified in the Info.plist file.
    • If the filename returned starts with "file:" prefix, it is a URL to a file external to the app, to be fetched with fgl_getfile() for example. When no "file:" prefix is present, it is a file from the app sandbox, that can be used with os.Path methods.
    • See Handling files on iOS devices for more details.

Example

IMPORT util
MAIN
    DEFINE rec RECORD
                path STRING,
                name STRING,
                wildcards STRING,
                caption STRING
           END RECORD
    DEFINE result STRING
    DEFINE files DYNAMIC ARRAY OF STRING
    DEFINE x INTEGER

    LET rec.path = "/tmp"
    LET rec.name = "Image files"
    LET rec.wildcards = "*.jpg *.png"
    LET rec.caption = "Select files"
    CALL ui.Interface.frontCall("standard","openFiles",[rec.*],[result])

    CALL util.JSON.parse( result, files )

    FOR x=1 TO files.getLength()
        DISPLAY SFMT("File %1: %2 ", x, files[x])
    END FOR

END MAIN