Table of Contents

file_open

`file_open()` creates an open-file dialog object.

Use it when an Expr script needs the user to select one or more existing files.

`file_open` is not cloneable because it represents dialog configuration and optional asynchronous callback state.

Constructor

file_open()

Creates an open-file dialog.

Item Description
Syntax `file_open()`
Arguments none
Returns file_open object

Example: 

dlg = file_open();

Properties

Property Type Description
`title` string Dialog title.
`directory` string Initial directory after host path resolution.
`file` string Initial file name.
`multi_select` boolean `true` when multi-select is enabled.

Properties are read-only. Use methods such as `title(text)` and `directory(path)` to change dialog configuration.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

`clone()` is not supported for `file_open`.

Methods

title(text)

Sets the dialog title.

Argument Type Description
`text` string Title text.

Returns: file_open object.

Example: 

dlg = file_open().title('Open image');

directory(path)

Sets the initial directory. The path is resolved through host profile path rules.

Argument Type Description
`path` string Initial directory path.

Returns: file_open object.

Example: 

dlg = file_open().directory('images');

file(name)

Sets the initial file name.

Argument Type Description
`name` string Initial file name.

Returns: file_open object.

Example: 

dlg = file_open().file('program.expr');

add_filter(name, pattern)

Adds a file filter.

Argument Type Description
`name` string Display name for the filter.
`pattern` string File pattern, for example `*.png;*.jpg`.

Returns: file_open object.

Example: 

dlg = file_open()
    .add_filter('Images', '*.png;*.jpg;*.webp')
    .add_filter('All files', '*.*');

multi_select(enabled)

Enables or disables selecting multiple files.

Argument Type Description
`enabled` boolean Multi-select state.

Returns: file_open object.

Example: 

dlg = file_open().multi_select(true);

on_result(callback)

Sets a callback for asynchronous result handling.

Argument Type Description
`callback` callable object Function reference, method reference, or other object that implements `call(files)`.

Returns: file_open object.

The callback receives one argument: an `array` containing selected file paths. When `on_result()` is used, `show()` displays the dialog and returns the dialog object immediately.

Example: 

function selected(files)
{
    print(files.join('\n'));
}
 
file_open()
    .title('Select files')
    .multi_select(true)
    .on_result(selected)
    .show();

show()

Shows the dialog.

Item Description
Syntax `file_open.show()`
Arguments none
Returns array, file_open object, or none

Without `on_result()`, `show()` blocks until the dialog is closed and returns an `array` of selected paths. If the user cancels, it returns `none()`.

With `on_result(callback)`, `show()` returns the dialog object immediately.

Example: 

files = file_open()
    .title('Open program')
    .add_filter('Expr files', '*.expr;*.txt')
    .show();
 
if (!files.is_none())
{
    print(files.get(0));
}

Previous: Dialogs

Next: file_save