JavaScript Documentation / ui

This object contains methods for interacting with the user.

• ui.alert(message, [title], [button1], [button2], ..., [handler])
• ui.hudSuccess([message])
• ui.hudError([message])
• ui.hudProgress([message], [progress])
• ui.hudDismiss()
• ui.input([title], [text], [placeholder], [keyboardType], handler)
• ui.list([title], [data], [multipleSelection], handler)

ui.alert(message, [title], [button1], [button2], ..., [handler])

Displays an alert that can contain text and buttons.

Parameters

• messagerequiredThe text to display in the alert.
• titleoptionalThe text to display in the title bar of the alert.
• button1, button2, ...optionalThe titles of buttons to display in the alert. You can have a maximum of ten buttons on the alert. If this parameters are omitted, the alert will add an "OK" button automatically.
• handleroptionalThe function to execute when the user taps a button. This function takes the button index as its only parameter.

Example

ui.alert('Hello world');

ui.hudSuccess([message])

Displays a HUD with a success icon. The HUD will be dismissed automatically.

Parameters

• messageoptionalThe text to display in the HUD.

Example

ui.hudSuccess('Done');

ui.hudError([message])

Displays a HUD with an error icon. The HUD will be dismissed automatically.

Parameters

• messageoptionalThe text to display in the HUD.

Example

ui.hudError('Failed');

ui.hudProgress([message], [progress])

Displays a HUD with a progress indicator. The HUD will not be dismissed automatically, calls hudSuccess, hudError or hudDismiss to dismiss the HUD.

Parameters

• messageoptionalThe text to display in the HUD.
• progressoptionalA double value between 0.0 and 1.0 to indicate the completion percentage, where 1.0 indicates the completion of the task. If this parameter is omited, the progress indicator will indicate indeterminate status.

Example

ui.hudProgress();
ui.hudProgress(null, 0.2);
ui.hudProgress(null, 0.5);
ui.hudProgress(null, 0.8);
ui.hudSuccess();

ui.hudDismiss()

Dismisses the current HUD.

ui.input([title], [text], [placeholder], [keyboardType], handler)

Shows a view with a single text field, used to ask for user input.

Parameters

• titleoptionalThe text to display in the title bar of the view.
• textoptionalThe text to pre-fill in the text field.
• placeholderoptionalThe text that hints to the user what can be entered in.
• keyboardTypeoptionalThe keyboard style of the text field. Valid values are number, email, url, web and twitter. If this parameter is omitted, the text field will get the default keyboard style.
• handlerrequiredThe function to execute when the user commits the value of the text field, or taps the "Cancel" button. This function takes the input value as its only parameter. If the user taps the "Cancel" button, the input value is undefined.

Example

ui.input('Search', null, 'Enter search term', value => {
    if (value) {
        ui.alert(value);
    }
});

ui.list([title], [data], [multipleSelection], handler)

Shows a list of values that can be filtered by searching, used to ask for user selection.

Parameters

• titleoptionalThe text to display in the title bar of the view.
• dataoptionalAn array of strings of form title[|value][|subtitle] to display in the list. title, value and subtitle are separated by the vertical bar (|).
  • titlerequiredThe text to display in the title label of the cell.
  • valueoptionalThe value of the cell that will be passed in the handler function if selected. If this parameter is omitted, cell's value will be title.
  • subtitleoptionalThe smaller gray text to display below title.
• multipleSelectionoptionalIndicates whether multiple values can be selected. Default value is false.
• handlerrequiredThe function to execute when the user commits the selected values, or taps the "Cancel" button. This function gets passed two arguments:
  • selectedValuesAn array that contains the values of all selected cells. If the user taps the "Cancel" button, the value is undefined.
  • selectedIndicesAn array that contains the zero-based indexes of all selected cells. If the user taps the "Cancel" button, the value is undefined.

Example

ui.hudProgress('Searching');
http.get('https://itunes.apple.com/search', { term: 'jack johnson', limit: 25 }, (data, error) => {
    if (error) {
        ui.hudError();
    }
    else {
        ui.hudDismiss();
        const listData = data.results.map(item => item.trackName);
        ui.list('Search Result', listData, true, selectedValues => {
            if (!selectedValues) {
                return;
            }
            const text = selectedValues.join('\n');
            if (editor.isClosed()) {
                editor.newFile(text);
            }
            else {
                editor.replaceSelection(text);
            }
        });
    }
});