Stability: 2 - Stable

The dialogs module provides simple dialog helpers for interacting with users. The simplest example:

alert("Hello");

This code shows an alert dialog with "Hello", and continues after the user taps "OK". A slightly more complex example:

var clear = confirm("Clear all cache?");
if (clear) {
  alert("Cleared!");
}

confirm() shows a dialog and lets the user choose "OK" or "Cancel". It returns true if the user confirms.

Important: in UI mode, dialogs cannot be used in the same blocking way as usual. Use callbacks or Promise instead. Example:

"ui";
// Callback style
confirm("Clear all cache?", function (clear) {
  if (clear) {
    alert("Cleared!");
  }
});
// Promise style
confirm("Clear all cache?").then((clear) => {
  if (clear) {
    alert("Cleared!");
  }
});

dialogs.alert(title[, content, callback])

• title {string} Dialog title.
• content {string} Optional. Dialog content. Default empty.
• callback {Function} Optional callback. Called when the user taps OK (usually for UI mode).

Shows an alert dialog with only an OK button. The script continues after the user taps OK.

This function can also be used as a global function.

alert("Error", "Unknown error. Please contact the script author.");

In UI mode, this function returns a Promise. Example:

"ui";
alert("Hi").then(() => {
  // Runs after tapping OK
});

dialogs.confirm(title[, content, callback])

• title {string} Dialog title.
• content {string} Optional. Dialog content. Default empty.
• callback {Function} Optional callback. Called when the user taps OK (usually for UI mode).

Shows a confirm dialog with OK and Cancel. Returns true if the user confirms, otherwise false.

This function can also be used as a global function.

In UI mode, this function returns a Promise. Example:

"ui";
confirm("Are you sure?").then((value) => {
  // value is true/false depending on OK/Cancel
});

dialogs.rawInput(title[, prefill, callback])

• title {string} Dialog title.
• prefill {string} Optional initial input value. Default empty.
• callback {Function} Optional callback. Called when the user taps OK (usually for UI mode).

Shows an input dialog. Waits for user input and returns the entered string when the user taps OK. Returns null if the user cancels.

This function can also be used as a global function.

var name = rawInput("Your name", "Tom");
alert("Your name is " + name);

In UI mode, this function returns a Promise. Example:

"ui";
rawInput("Your name", "Tom").then((name) => {
  alert("Your name is " + name);
});

You can also use a callback, for example:

rawInput("Your name", "Tom", (name) => {
  alert("Your name is " + name);
});

dialogs.input(title[, prefill, callback])

Equivalent to eval(dialogs.rawInput(title, prefill, callback)). The difference from rawInput() is that it evaluates the returned string with eval() before returning it, so the return value may not be a string.

You can use it to input numbers, arrays, etc. Example:

var age = dialogs.input("Your age", "18");
// new Date().getYear() + 1900 returns the current year
var year = new Date().getYear() + 1900 - age;
alert("Your birth year is " + year);

In UI mode, this function returns a Promise. Example:

"ui";
dialogs.input("Your age", "18").then((age) => {
  var year = new Date().getYear() + 1900 - age;
  alert("Your birth year is " + year);
});

dialogs.prompt(title[, prefill, callback])

Equivalent to dialogs.rawInput().

dialogs.select(title, items, callback)

• title {string} Dialog title.
• items {Array} Options list (string array).
• callback {Function} Optional callback. Called when the user confirms (usually for UI mode).

Shows a selection dialog and returns the selected option index (0 ~ item.length - 1). Returns -1 if the user cancels.

var options = ["Option A", "Option B", "Option C", "Option D"];
var i = dialogs.select("Select an option", options);
if (i >= 0) {
  toast("You selected: " + options[i]);
} else {
  toast("Cancelled");
}

In UI mode, this function returns a Promise. Example:

"ui";
dialogs
  .select("Select an option", ["Option A", "Option B", "Option C", "Option D"])
  .then((i) => {
    toast(i);
  });

dialogs.singleChoice(title, items[, index, callback])

• title {string} Dialog title.
• items {Array} Options list (string array).
• index {number} Default selected index. Default 0.
• callback {Function} Optional callback. Called when the user confirms (usually for UI mode).

Shows a single-choice dialog and returns the selected option index (0 ~ item.length - 1). Returns -1 if the user cancels.

In UI mode, this function returns a Promise.

dialogs.multiChoice(title, items[, indices, callback])

• title {string} Dialog title.
• items {Array} Options list (string array).
• indices {Array} Default selected indices. Default empty array.
• callback {Function} Optional callback. Called when the user confirms (usually for UI mode).

Shows a multi-choice dialog and returns an array of selected indices. Returns [] if the user cancels.

In UI mode, this function returns a Promise.

dialogs.setDefaultDialogType(type)

[Added in Pro 8.8.5]

• type {string} Dialog type

Sets the default dialog type. Supported values:

• overlay {string} Always show dialogs using the floating-window permission, regardless of foreground/background. Throws if floating-window permission is missing.
• app {string} Always show dialogs as in-app dialogs, regardless of whether the app is in the foreground. Throws if there is no UI. If the UI exists but is in the background, it will still be shown but the user will only see it after returning to the app. Note: Auto.js Pro main UI (file list) and the script process are not the same process, so you cannot show in-app dialogs on the Auto.js Pro main UI.
• app-or-overlay {string} If the app has a UI, show as an in-app dialog (may still show while backgrounded, but visible only after returning). If there is no UI, fall back to floating-window dialogs.
• foreground-or-overlay {string} If the app is in the foreground, use an in-app dialog; otherwise use a floating-window dialog, ensuring the user can see it immediately in all cases.

This affects all dialogs shown by the dialogs module. Custom dialogs created by $dialogs.build can override it via the type property.

If you don't call this function, the default is overlay (for backward compatibility).

// Make all dialogs default to foreground-or-overlay (alert, $dialogs.build(), etc.)
$dialogs.setDefaultDialogType("foreground-or-overlay");

let types = ["overlay", "app", "app-or-overlay", "foreground-or-overlay"];
let i = $dialogs.select("Select dialog type", [
  "Floating dialog: overlay",
  "In-app dialog: app",
  "Adaptive dialog: app-or-overlay",
  "Adaptive foreground dialog: foreground-or-overlay",
]);

if (i < 0) {
  exit();
}

let type = types[i];
alert(
  "Selected type: " + type + ". Tap OK and a dialog will be shown after 3 seconds.",
  "Within these 3 seconds, you can press back or switch to background to test dialog behavior.",
);

dialogs.build(properties)

• properties {Object} Dialog properties.
• Returns {Dialog}

Creates a customizable dialog. Example:

dialogs
  .build({
    // Dialog title
    title: "New version available",
    // Dialog content
    content: "Changelog: fixed several bugs",
    // Positive button
    positive: "Download",
    // Negative button
    negative: "Cancel",
    // Neutral button
    neutral: "Download in browser",
    // Checkbox prompt
    checkBoxPrompt: "Don't ask again",
  })
  .on("positive", () => {
    // On positive
    toast("Downloading...");
  })
  .on("neutral", () => {
    // On neutral
    app.openUrl("https://www.autojs.org");
  })
  .on("check", (checked) => {
    // On checkbox
    log(checked);
  })
  .show();

Available properties:

• title {string} Dialog title

• titleColor {string} | {number} Title color

• buttonRippleColor {string} | {number} Button ripple color

• icon {string} | {Image} Dialog icon (URL or Image object)

• content {string} Dialog content text

• contentColor{string} | {number} Content text color

• contentLineSpacing{number} Line-height multiplier for content text (1.0 = normal)

• customView {android.view.View} Custom view. You can create it from XML via ui.inflate.

• items {Array} List items

• itemsColor {string} | {number} List item text color

• itemsSelectMode {string} Selection mode:

  • select Normal selection
  • single Single-choice
  • multi Multi-choice

• itemsSelectedIndex {number} | {Array} Default selected index/indices (number for single, array for multi)

• positive {string} Positive button text (rightmost button)

• positiveColor {string} | {number} Positive button text color

• neutral {string} Neutral button text (leftmost button)

• neutralColor {string} | {number} Neutral button text color

• negative {string} Negative button text (left of positive)

• negativeColor {string} | {number} Negative button text color

• checkBoxPrompt {string} Checkbox prompt text

• checkBoxChecked {boolean} Default checkbox state

• progress {Object} Progress configuration:

  • max {number} Max value. -1 means indeterminate progress.
  • horizontal {boolean} If true, indeterminate progress is horizontal.
  • showMinMax {boolean} Whether to show min/max values

• cancelable {boolean} Whether the dialog is cancelable. If false, it can only be dismissed in code.

• canceledOnTouchOutside {boolean} Whether to cancel when tapping outside. Default true.

• inputHint {string} Input hint text

• inputPrefill {string} Default input value

• type {string} Dialog type. See $dialogs.setDefaultDialogType().

With these options you can customize a dialog, and implement interactions by listening to button/input events on the returned Dialog object. Here are some examples.

Alert-like dialog:

dialogs
  .build({
    title: "Hi",
    content: "Have a great day!",
    positive: "OK",
  })
  .show();

Confirm-like dialog:

dialogs
  .build({
    title: "Question",
    content: "Are you sure?",
    positive: "Yes",
    negative: "No",
  })
  .on("positive", () => {
    alert("Confirmed");
  })
  .on("negative", () => {
    alert("Cancelled");
  })
  .show();

Single-choice dialog:

dialogs
  .build({
    title: "Single choice",
    items: ["Option 1", "Option 2", "Option 3", "Option 4"],
    itemsSelectMode: "single",
    itemsSelectedIndex: 3,
  })
  .on("single_choice", (index, item) => {
    toast("You selected: " + item);
  })
  .show();

"Processing" dialog:

var d = dialogs
  .build({
    title: "Downloading...",
    progress: {
      max: -1,
    },
    cancelable: false,
  })
  .show();

setTimeout(() => {
  d.dismiss();
}, 3000);

Input dialog:

dialogs
  .build({
    title: "Your age",
    inputPrefill: "18",
  })
  .on("input", (input) => {
    var age = parseInt(input);
    toastLog(age);
  })
  .show();

One notable difference when building dialogs is that you need callbacks (you can't synchronously return results like other dialogs.* helpers). However, you can use the threads module to bridge this. For example, show an input dialog and get the result:

var input = threads.disposable();
dialogs
  .build({
    title: "Your age",
    inputPrefill: "18",
  })
  .on("input", (text) => {
    input.setAndNotify(text);
  })
  .show();
var age = parseInt(input.blockedGet());
toastLog(age);

Dialog

The dialog object returned by dialogs.build(). It exposes events to handle user interactions, and APIs to query dialog state/info.

Event: show

• dialog {Dialog} Dialog

Triggered when the dialog is shown. Example:

dialogs
  .build({
    title: "Title",
  })
  .on("show", (dialog) => {
    toast("Dialog shown");
  })
  .show();

Event: cancel

• dialog {Dialog} Dialog

Triggered when the dialog is cancelled. A dialog can be cancelled by tapping Cancel, pressing Back, or tapping outside. Example:

dialogs
  .build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
  })
  .on("cancel", (dialog) => {
    toast("Dialog cancelled");
  })
  .show();

Event: dismiss

• dialog {Dialog} Dialog

Triggered when the dialog is dismissed. It fires when the dialog is cancelled or when you call dialog.dismiss() manually. Example:

var d = dialogs
  .build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
  })
  .on("dismiss", (dialog) => {
    toast("Dialog dismissed");
  })
  .show();

setTimeout(() => {
  d.dismiss();
}, 5000);

Event: positive

• dialog {Dialog} Dialog

Triggered when the positive button is pressed. Example:

var d = dialogs
  .build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
  })
  .on("positive", (dialog) => {
    toast("You tapped OK");
  })
  .show();

Event: negative

• dialog {Dialog} Dialog

Triggered when the negative button is pressed. Example:

var d = dialogs
  .build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
  })
  .on("negative", (dialog) => {
    toast("You tapped Cancel");
  })
  .show();

Event: neutral

• dialog {Dialog} Dialog

Triggered when the neutral button is pressed. Example:

var d = dialogs
  .build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
    neutral: "Later",
  })
  .on("positive", (dialog) => {
    toast("You tapped Later");
  })
  .show();

Event: any

• dialog {Dialog} Dialog

• action

  {string} Which button was pressed. Possible values:

  • positive Positive button
  • negative Negative button
  • neutral Neutral button

Triggered when any button is pressed. Example:

var d = dialogs
  .build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
    neutral: "Later",
  })
  .on("any", (action, dialog) => {
    if (action == "positive") {
      toast("You tapped OK");
    } else if (action == "negative") {
      toast("You tapped Cancel");
    }
  })
  .show();

Event: item_select

• index {number} Selected index (0-based)
• item {Object} Selected item
• dialog {Dialog} Dialog

Triggered when an item is selected in list mode (itemsSelectMode="select"). Example:

var d = dialogs
  .build({
    title: "Select",
    positive: "OK",
    negative: "Cancel",
    items: ["A", "B", "C", "D"],
    itemsSelectMode: "select",
  })
  .on("item_select", (index, item, dialog) => {
    toast("You selected item " + (index + 1) + ": " + item);
  })
  .show();

Event: single_choice

• index {number} Selected index (0-based)
• item {Object} Selected item
• dialog {Dialog} Dialog

Triggered when a single-choice item is confirmed (itemsSelectMode="singleChoice"). Example:

var d = dialogs
  .build({
    title: "Select",
    positive: "OK",
    negative: "Cancel",
    items: ["A", "B", "C", "D"],
    itemsSelectMode: "singleChoice",
  })
  .on("item_select", (index, item, dialog) => {
    toast("You selected item " + (index + 1) + ": " + item);
  })
  .show();

Event: multi_choice

• indices {Array} Selected indices
• items {Array} Selected items
• dialog {Dialog} Dialog

Triggered when multi-choice selection is confirmed (itemsSelectMode="multiChoice"). Example:

var d = dialogs
  .build({
    title: "Select",
    positive: "OK",
    negative: "Cancel",
    items: ["A", "B", "C", "D"],
    itemsSelectMode: "multiChoice",
  })
  .on("item_select", (indices, items, dialog) => {
    toast(util.format("Selected indices: %o, items: %o", indices, items));
  })
  .show();

Event: input

• text {string} Input text
• dialog {Dialog} Dialog

Triggered when the user confirms an input dialog. Example:

dialogs
  .build({
    title: "Input",
    positive: "OK",
    negative: "Cancel",
    inputPrefill: "",
  })
  .on("input", (text, dialog) => {
    toast("You entered: " + text);
  })
  .show();

Event: input_change

• text {string} Input text
• dialog {Dialog} Dialog

Triggered when the input text changes. Example:

dialogs
  .build({
    title: "Input",
    positive: "OK",
    negative: "Cancel",
    inputPrefill: "",
  })
  .on("input_change", (text, dialog) => {
    toast("You entered: " + text);
  })
  .show();

dialog.getProgress()

• Returns {number}

Gets current progress value (integer).

dialog.getMaxProgress()

• Returns {number}

Gets max progress value (integer).

dialog.getActionButton(action)

• action {string} Action, one of:
  • positive
  • negative
  • neutral