Table of Contents

file_save

`file_save()` creates a save-file dialog object.

Use it when an Expr script needs the user to choose a destination path.

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

Constructor

file_save()

Creates a save-file dialog.

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

Example: 

dlg = file_save();

Properties

Property Type Description
`title` string Dialog title.
`directory` string Initial directory after host path resolution.
`file` string Initial file name.
`multi_select` boolean Stored multi-select state. Save dialogs ignore it when shown.

Properties are read-only. Use methods such as `title(text)` and `file(name)` 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_save`.

Methods

title(text)

Sets the dialog title.

Argument Type Description
`text` string Title text.

Returns: file_save object.

Example: 

dlg = file_save().title('Save 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_save object.

Example: 

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

file(name)

Sets the initial file name.

Argument Type Description
`name` string Initial file name.

Returns: file_save object.

Example: 

dlg = file_save().file('output.png');

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_save object.

Example: 

dlg = file_save()
    .add_filter('PNG image', '*.png')
    .add_filter('All files', '*.*');

multi_select(enabled)

Stores the multi-select setting.

Argument Type Description
`enabled` boolean Multi-select state. Save dialogs ignore this when shown.

Returns: file_save object.

Example: 

dlg = file_save().multi_select(true);    // ignored by save dialog

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_save object.

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

Example: 

function save_selected(files)
{
    if (!files.empty())
    {
        print('Save to: ', files.get(0));
    }
}
 
file_save()
    .title('Save result')
    .file('result.png')
    .on_result(save_selected)
    .show();

show()

Shows the dialog.

Item Description
Syntax `file_save.show()`
Arguments none
Returns array, file_save 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_save()
    .title('Save image')
    .file('result.png')
    .add_filter('PNG image', '*.png')
    .show();
 
if (!files.is_none())
{
    print('Save to: ', files.get(0));
}

Previous: file_open

Next: msg_ok