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

• message required The text to display in the alert.
• title optional The text to display in the title bar of the alert.
• button1, button2, ... optional The 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.
• handler optional The 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

• message optional The 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

• message optional The 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

• message optional The text to display in the HUD.
• progress optional A 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

• title optional The text to display in the title bar of the view.
• text optional The text to pre-fill in the text field.
• placeholder optional The text that hints to the user what can be entered in.
• keyboardType optional The 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.
• handler required The 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

• title optional The text to display in the title bar of the view.
• data optional An array of strings of form title[|value][|subtitle] to display in the list. title, value and subtitle are separated by the vertical bar (|).
  • title required The text to display in the title label of the cell.
  • value optional The 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.
  • subtitle optional The smaller gray text to display below title.
• multipleSelection optional Indicates whether multiple values can be selected. Default value is false.
• handler required The function to execute when the user commits the selected values, or taps the "Cancel" button. This function gets passed two arguments:
  • selectedValues An array that contains the values of all selected cells. If the user taps the "Cancel" button, the value is undefined.
  • selectedIndices An 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);
              }
          });
      }
  });