dialogs

Stability: 2-Stable

The dialogs module provides simple dialog support, which can interact with users through dialogs. The simplest example is as follows:

alert("Hello");

This code will pop up a message prompt box to display "Hello", and continue to run after the user clicks "OK". A slightly more complicated example is as follows:

var clear = confirm("Do you want to clear all caches?");
if(clear){
    alert("Clear successfully!");
}

confirm() will pop up a dialog box and let the user choose "Yes" or "No", and return true if "Yes" is selected.

It is important to note that the dialog box cannot be used as usual in ui mode, and the callback function should be used or [Promise](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects /Promise). It may be slightly difficult to understand this. for example:

"ui";
//Callback form
 confirm("Do you want to clear all caches?", function(clear){
     if(clear){
          alert("Clear successfully!");
     }
 });
//Promise form
confirm("Do you want to clear all caches?")
    .then(clear => {
        if(clear){
          alert("Clear successfully!");
        }
    });

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

• title {string} The title of the dialog box.
• content {string} Optional, the content of the dialog box. The default is empty.
• callback {Function} Callback function, optional. Called when the user clicks OK, generally used in ui mode.

A prompt dialog box containing only the "OK" button is displayed. The script does not continue to run until the user clicks OK.

This function can also be used as a global function.

alert("An error occurred~", "An unknown error occurred, please contact the script author");

In ui mode, this function returns a Promise. E.g:

"ui";
alert("hehehe").then(()=>{
    //When you click OK, it will execute here
});

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

• title {string} The title of the dialog box.
• content {string} Optional, the content of the dialog box. The default is empty.
• callback {Function} Callback function, optional. Called when the user clicks OK, generally used in ui mode.

A prompt dialog box containing "OK" and "Cancel" buttons is displayed. If the user clicks "OK", it returns true, otherwise it returns false.

This function can also be used as a global function.

In ui mode, this function returns a Promise. E.g:

"ui";
confirm("Are you sure").then(value=>{
    //When you click OK, it will execute here, the value is true or false, which means you click "OK" or "Cancel"
});

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

• title {string} The title of the dialog box.
• prefill {string} The initial content of the input box, optional, and empty by default.
• callback {Function} Callback function, optional. Called when the user clicks OK, generally used in ui mode.

Display a dialog box containing an input box, wait for the user to input content, and return the input string when the user clicks OK. If the user cancels the input, null is returned.

This function can also be used as a global function.

var name = rawInput("Please enter your name", "小明");
alert("Your name is" + name);

In ui mode, this function returns a Promise. E.g:

"ui";
rawInput("Please enter your name", "小明").then(name => {
    alert("Your name is" + name);
});

Of course, you can also use callback functions, for example:

rawInput("Please enter your name", "Xiaoming", name => {
     alert("Your name is" + name);
});

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

Equivalent to eval(dialogs.rawInput(title, prefill, callback)), the difference between this function and rawInput is that the input string will be calculated by eval and then returned. The returned string may not be a string.

You can use this function to input numbers, arrays, etc. E.g:

var age = dialogs.input("Please enter your age", "18");
// new Date().getYear() + 1900 can get the current year
var year = new Date().getYear() + 1900-age;
alert("Your year of birth is" + year);

In ui mode, this function returns a Promise. E.g:

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

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

Equivalent to dialogs.rawInput();

dialogs.select(title, items, callback)

• title {string} The title of the dialog box.
• items {Array} The option list of the dialog box is an array of strings.
• callback {Function} Callback function, optional. Called when the user clicks OK, generally used in ui mode.

Display a dialog box with a list of options, wait for the user to select, and return the index of the option selected by the user (0 ~ item.length-1). If the user cancels the selection, return -1.

var options = ["Option A", "Option B", "Option C", "Option D"]
var i = dialogs.select("Please select an option", options);
if(i >= 0){
    toast("Your choice is" + options[i]);
}else{
    toast("You canceled the selection");
}

In ui mode, this function returns a Promise. E.g:

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

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

• title {string} The title of the dialog box.
• items {Array} The option list of the dialog box is an array of strings.
• index {number} The position of the initial option of the dialog box, the default is 0.
• callback {Function} Callback function, optional. Called when the user clicks OK, generally used in ui mode.

Display a single-selection list dialog box, wait for the user to select, and return the index of the option selected by the user (0 ~ item.length-1). If the user cancels the selection, return -1.

In ui mode, this function returns a Promise.

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

• title {string} The title of the dialog box.
• items {Array} The option list of the dialog box is an array of strings.
• indices {Array} The array of the index of the initially selected item in the option list. The default is an empty array.
• callback {Function} Callback function, optional. Called when the user clicks OK, generally used in ui mode.

Display a multiple-selection list dialog box, wait for the user to select, and return an array of the index of the option selected by the user. If the user cancels the selection, return to [].

In ui mode, this function returns a Promise.

dialogs.build(properties)

• properties {Object} Dialog properties, used to configure dialogs.
• Back to {Dialog}

Create a customizable dialog box, for example:

dialogs.build({
    //Dialog title
    title: "New Version Found",
    //Dialog content
    content: "Update log: Several new bugs have been added",
    //Determine the key content
    positive: "Download",
    //Cancel key content
    negative: "Cancel",
    //Neutral key content
    neutral: "Download to browser",
    //Check box content
    checkBoxPrompt: "Don't prompt anymore"
}).on("positive", ()=>{
    //Monitor confirm key
    toast("Start downloading...");
}).on("neutral", ()=>{
    //Monitor the neutral key
    app.openUrl("https://www.baidu.com");
}).on("check", (checked)=>{
    //Monitor check box
    log(checked);
}).show();

The items that can be configured with the option properties are:

• title {string} dialog title
• titleColor {string} | {number} The color of the dialog title
• buttonRippleColor {string} | {number} The ripple effect color of the dialog button
• icon {string} | {Image} The icon of the dialog box, which is a URL or image object
• content {string} dialog box text content
• contentColor{string} | {number} The color of the text content of the dialog box
• contentLineSpacing{number} The line height multiple of the dialog box text content, 1.0 is double the line height
• customView {android.view.View} The custom view for dialog
• items {Array} dialog box list options
• itemsColor {string} | {number} The text color of the options in the dialog box list
• itemsSelectMode {string} The option selection mode of the dialog box list, which can be:
  • select normal selection mode
  • single single selection mode
  • multi multiple selection mode
• itemsSelectedIndex {number} | {Array} The index of the pre-selected item in the dialog box list, if it is a single-selection mode, it is an index; if it is a multiple-selection mode, it is an array
• positive {string} The text content of the dialog box confirm button (the rightmost button)
• positiveColor {string} | {number} The text color of the dialog box confirm button (the rightmost button)
• neutral {string} The text content of the neutral button in the dialog box (the leftmost button)
• neutralColor {string} | {number} The text color of the neutral button in the dialog box (the leftmost button)
• negative {string} The text content of the cancel button of the dialog box (the button to the left of the OK button)
• negativeColor {string} | {number} The text color of the cancel button in the dialog box (the button to the left of the OK button)
• checkBoxPrompt {string} Check box text content
• checkBoxChecked {boolean} Whether the check box is checked
• progress {Object} Configure the object of the progress bar of the dialog box:
  • max {number} The maximum value of the progress bar, if it is -1, it is an endless loop progress bar
  • horizontal {boolean} If true, the infinite loop progress bar of the dialog is a horizontal progress bar
  • showMinMax {boolean} Whether to display the maximum and minimum values ​​of the progress bar
• cancelable {boolean} Whether the dialog box can be cancelled, if it is false, the dialog box can only be cancelled manually with code
• canceledOnTouchOutside {boolean} Whether the dialog box is automatically cancelled when clicking outside the dialog box, the default is true
• inputHint {string} The input prompt of the input box of the dialog box
• inputPrefill {string} The default input content of the dialog input box

Through these options, you can customize a dialog box, and realize the interaction by monitoring the keystrokes and input events of the returned Dialog object. Here are some examples.

Simulate alert dialog:

dialogs.build({
    title: "Hello",
    content: "Today also be full of vitality",
    positive: "OK"
}).show();

Simulate confirm dialog:

dialogs.build({
    title: "Hello",
    content: "Are you a fool?",
    positive: "Yes",
    negative: "I am a fool"
}).on("positive", ()=>{
    alert("Hahaha fool");
}).on("negative", ()=>{
    alert("Hahaha fool");
}).show();

Simulate radio buttons:

dialogs.build({
    title: "Single Selection",
    items: ["Option 1", "Option 2", "Option 3", "Option 4"],
    itemsSelectMode: "single",
    itemsSelectedIndex: 3
}).on("single_choice", (index, item)=>{
    toast("Your choice is" + 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: "Please enter your age",
    inputPrefill: "18"
}).on("input", (input)=>{
    var age = parseInt(input);
    toastLog(age);
}).show();

Using this function to construct a dialog box, one obvious difference is that you need to use a callback function instead of returning results synchronously like other dialogs functions; but it can also be achieved through the threads module. For example, display an input box and get the input result as:

var input = threads.disposable();
dialogs.build({
    title: "Please enter 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() has some built-in events to respond to user interaction, and you can also get the status and information of the dialog.

Event: show

• dialog {Dialog} dialog

The event that will be triggered when the dialog box is displayed. E.g:

dialogs.build({
    title: "Title"
}).on("show", (dialog)=>{
    toast("The dialog box is displayed");
}).show();

Event: cancel

• dialog {Dialog} dialog

The event that will be triggered when the dialog is cancelled. A dialog box may be canceled by pressing the cancel button, the return key, or by clicking outside the dialog box. E.g:

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

Event: dismiss

• dialog {Dialog} dialog

The event that will be triggered when the dialog box disappears. The event will be triggered when the dialog is cancelled or the dialog.dismiss() function is manually called. E.g:

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

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

Event: positive

• dialog {Dialog} dialog

Determines the event that is triggered when the button is pressed. E.g:

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

Event: negative

• dialog {Dialog} dialog

The event triggered when the cancel button is pressed. E.g:

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

Event: neutral

• dialog {Dialog} dialog

Event triggered when the neutral button is pressed. E.g:

var d = dialogs.build({
    title: "Title",
    positive: "OK",
    negative: "Cancel",
    neutral: "Reminder later"
}).on("positive", (dialog)=>{
    toast("You clicked and prompt later");
}).show();

Event: any

• dialog {Dialog} dialog
• action {string} The button that was clicked, the possible values ​​are:
  • positive OK button
  • negative cancel button
  • neutral button

Event triggered when any button is pressed. E.g:

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

Event: item_select

• index {number} The index of the selected item, starting from 0
• item {Object} the selected item
• dialog {Dialog} dialog

The event that is triggered when an item in the dialog box list (itemsSelectMode is "select") is clicked and selected. E.g:

var d = dialogs.build({
    title: "Please select",
    positive: "OK",
    negative: "Cancel",
    items: ["A", "B", "C", "D"],
    itemsSelectMode: "select"
}).on("item_select", (index, item, dialog)=>{
    toast("Your choice is the first" + (index + 1) + "item, the option is "+ item);
}).show();

Event: single_choice

• index {number} The index of the selected item, starting from 0
• item {Object} the selected item
• dialog {Dialog} dialog

The event that is triggered when an item in the dialog box single-selection list (itemsSelectMode is "singleChoice") is selected and OK is clicked. E.g:

var d = dialogs.build({
    title: "Please select",
    positive: "OK",
    negative: "Cancel",
    items: ["A", "B", "C", "D"],
    itemsSelectMode: "singleChoice"
}).on("item_select", (index, item, dialog)=>{
    toast("Your choice is the first" + (index + 1) + "item, the option is "+ item);
}).show();

Event: multi_choice

• indices {Array} Array of indexes of selected items
• items {Array} Array of selected items
• dialog {Dialog} dialog

The event that is triggered when an item in the dialog box multi-selection list (itemsSelectMode is "multiChoice") is selected and clicked OK. E.g:

var d = dialogs.build({
    title: "Please select",
    positive: "OK",
    negative: "Cancel",
    items: ["A", "B", "C", "D"],
    itemsSelectMode: "multiChoice"
}).on("item_select", (indices, items, dialog)=>{
    toast(util.format("The item you selected is %o, the option is %o", indices, items));
}).show();

Event: input

• text {string}The content of the input box
• dialog {Dialog} dialog

The event that will be triggered when the dialog box with the input box is clicked. E.g:

dialogs.build({
    title: "Please enter",
    positive: "OK",
    negative: "Cancel",
    inputPrefill: ""
}).on("input", (text, dialog)=>{
    toast("What you entered is" + text);
}).show();

Event: input_change

• text {string} the content of the input box
• dialog {Dialog} dialog

An event that is triggered when the text of the input box of the dialog box changes. E.g:

dialogs.build({
    title: "Please enter",
    positive: "OK",
    negative: "Cancel",
    inputPrefill: ""
}).on("input_change", (text, dialog)=>{
    toast("What you entered is" + text);
}).show();

dialog.getProgress()

• Return {number}

Get the progress value of the current progress bar, which is an integer

dialog.getMaxProgress()

• Return {number}

Get the maximum progress value of the current progress bar, as an integer

dialog.getActionButton(action)

• action {string} Action, including:
  • positive
  • negative
  • neutral