Dialog objects let Expr scripts ask the user for input through host application dialogs.
This group contains file selection dialogs and message dialogs. Each dialog has its own reference page because constructor names, result values, and supported methods differ between dialog types.
| Constructor | Page | Description |
|---|---|---|
| `file_open()` | file_open | Opens a file selection dialog. |
| `file_save()` | file_save | Opens a save-file dialog. |
| `msg_ok()` | msg_ok | Shows an OK message dialog. |
| `msg_ok_cancel()` | msg_ok_cancel | Shows an OK/Cancel message dialog. |
| `msg_yes_no()` | msg_yes_no | Shows a Yes/No message dialog. |
| `msg_password()` | msg_password | Shows a password OK/Cancel dialog. |
`file_open()` and `file_save()` use method calls to configure the dialog before it is shown. Their properties are read-only snapshots of the current configuration.
Common file dialog configuration methods are `title(text)`, `directory(path)`, `file(name)`, `add_filter(name, pattern)`, `on_result(callback)`, and `show()`. `file_open()` also supports `multi_select(enabled)`.
Without `on_result()`, `show()` waits for the dialog and returns an `array` of selected paths. If the user cancels, it returns `none()`.
With `on_result(callback)`, `show()` displays the dialog and returns the dialog object immediately. The callback receives one argument: an `array` of selected paths, or `none()` if the dialog is cancelled.
Message dialogs use method calls to set the title, message text, optional buttons, and result callback. Their properties are read-only result/configuration values.
Common message dialog methods are `title(text)`, `message(text)`, `buttons(enabled)`, `on_result(callback)`, `show()`, `click_ok()`, and `click_close()`. `msg_password()` also supports `password_label(text)` and `password(text)`.
Without `on_result()`, `show()` waits for the dialog and returns a result `map`.
With `on_result(callback)`, `show()` displays the dialog and returns the dialog object immediately. The callback receives one argument: the same result `map`.
Common result keys are `action`, `action_code`, `ok`, `cancel`, `affirmative`, `save`, and `password`. The password value is only meaningful for `msg_password()`.