Manual · API

# `messages`

Talking to the person at the keyboard — dialogs, sounds, progress. Everything here blocks the script until it is answered, which is what a synchronous API means.

Every command on this page carries a worked example.

###
alert function

`messages.alert(text)`

Says something and waits for OK.

Worked example

    messages.alert("The import finished — " + imported + " rows.");

###
confirm function

`messages.confirm(text, [buttons])`

Asks. With your own buttons the answer is the pressed title; without, `true`/`false`.

Name your buttons after the act: ["Delete", "Cancel"] reads in a heartbeat where OK/Cancel makes people re-read the question.
Worked example

    const answer = messages.confirm(
        "Delete " + form.record.name + "?",
        ["Delete", "Cancel"]
    );
    if (answer === "Delete") {
        form.record.delete();
        form.close();
    }

###
prompt function

`messages.prompt(text, defaultValue)`

A question with a text field. `null` when cancelled.

Test for `null` before using the answer — Cancel is an answer too, and treating it as an empty string writes empty strings.
Worked example

    const reason = messages.prompt("Why is this invoice cancelled?", "");
    if (reason === null) { return; }        // Cancel is an answer too
    form.record.cancellationReason = reason;

###
showError function

`messages.showError(text)`

The error face of alert.

Worked example

    if (!files.canWrite(target)) {
        messages.showError("The export folder cannot be written to.");
        files.openPermissionSettings();
    }

###
showProgress function

`messages.showProgress(text, { maximum }) → handle`

A progress window with a working Cancel. Move it with `handle.advance()`, ask `handle.wasCancelled`, end with `handle.close()`.

Ask `wasCancelled` inside the loop, every turn — a Cancel that is only honoured at the end is a button that lies.
Worked example

    const progress = messages.showProgress("Importing…", { maximum: rows.length });
    for (const row of rows) {
        if (progress.wasCancelled) { break; }   // Cancel really works
        importOne(row);
        progress.advance();
    }
    progress.close();

###
beep function

`messages.beep()`

The system alert sound.

Worked example

    if (form.list.value === null) {
        messages.beep();   // a nudge, where a dialog would be shouting
        return;
    }

###
playSound function

`messages.playSound(name, { wait })`

A sound from your assets or Apple's fourteen. Dropped rather than queued when a loop shouts; `{ wait: true }` blocks until it finished.

Worked example

    messages.playSound("Glass");            // one of Apple's fourteen
    messages.playSound("cashRegister");     // or a sound from your assets