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