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

Sidebar

Table of Contents

file_open

Constructor

file_open()

Properties

Common Object Methods

to_string()

Methods

title(text)

directory(path)

file(name)

add_filter(name, pattern)

multi_select(enabled)

on_result(callback)

show()

User Tools

Site Tools

Sidebar

Table of Contents

file_open

Constructor

file_open()

Properties

Common Object Methods

to_string()

Methods

title(text)

directory(path)

file(name)

add_filter(name, pattern)

multi_select(enabled)

on_result(callback)

show()

Page Tools