Dialog Reference

Related documents

• Template Markup Language (TML) Reference

Table of contents

• Introduction
• Exported identifiers
  • dialog
• dialog methods
  • choose()
  • confirm()
  • notice()
  • textInput()

Introduction

MVCS provides a customizable popup dialog. There are several types: a simple notice, a confirmation, or a multiple choice. Each type has a message template and a callback function argument and displays one or more buttons. The dialog is dismissed when one of the buttons is pressed, and the callback function is called, passing a value associated with the button used.

The dialog is controlled using the dialog object. The dialog.notice() method opens a popup dialog displaying the message with a single "OK" button to dismiss the notification. The dialog.confirm() method opens a dialog that displays the message with an "OK" button and a "Cancel" button. The dialog.choose() method opens a dialog that displays the message with a custom array of buttons

The keypad is implemented as a dialog popup page.

Exported identifiers

dialog

Syntax

import {dialog} from 'common/mvcs/export.js';

The dialog object provides methods and properties to control the popup keypad.

The dialog object is also assigned to the global/window object and does not need to be explicitly imported. In addition, the dialog.notice() method is also globally available as notice().

dialog methods

choose()

Syntax

dialog.choose(message, buttons, callbackFn)
dialog.choose(message, buttons)

The choose() method displays a popup dialog containing the message and the button specified by the buttons array. The message can be a Template or a string, or an array of these, so the message can contain active inputs like state variables. The dialog is dismissed when any button is pressed.

If provided, the callbackFn is called when the dialog is dismissed, with the index of the pressed button as an argument. If callbackFn is omitted, then a Promise is returned that resolves with the index of the pressed button when the user dismisses the dialog.

Parameters

• message
  The message displayed. A Template or a string, or an array of these.
• buttons
  An array of button title strings.
• callbackFn (optional)
  A function that is called when the dialog is dismissed. The function will be passed a single argument that contains the index of the button that was pressed to dismiss the dialog.

Return value

If callbackFn is provided, then a Promise is returned that resolves when the user dismisses the dialog. Otherwise, it returns undefined.

confirm()

Syntax

dialog.confirm(message)
dialog.confirm(message, callbackFn)

The confirm() method displays a popup dialog containing the message and both "OK" and "Cancel" buttons. The message can be a Template or a string, or an array of these, so the message can contain active inputs like state variables. The dialog is dismissed when either button is pressed. If provided, the callbackFn is called when the dialog is dismissed, with a true argument if "OK" is pressed and false if "Cancel" is pressed.

If provided, the callbackFn is called when the dialog is dismissed. If callbackFn is omitted, then a Promise is returned that resolves when the user dismisses the dialog by pressing the "OK" button or rejects when the use presses the "Cancel" button.

Parameters

• message
  The message displayed. A Template or a string, or an array of these.
• callbackFn (optional)
  A function that is called when the dialog is dismissed. The function will be passed a single argument that is true if the "OK" button is pressed and false if the "Cancel" button is pressed.

Return value

If callbackFn is provided, then a Promise is returned that resolves when the user dismisses the dialog. Otherwise, it returns undefined.

notice()

Syntax

dialog.notice(message)
dialog.notice(message, callbackFn)
notice(message)
notice(message, callbackFn)

The notice() method displays a popup dialog containing the message and a single "OK" button. The message can be a Template, a string, or an array of these, so it can contain active inputs like state variables. The dialog is dismissed when the "OK" button is pressed.

If provided, the callbackFn is called when the dialog is dismissed. If callbackFn is omitted, then a Promise is returned that resolves when the user dismisses the dialog.

Parameters

• message
  The message displayed. A Template or a string, or an array of these.
• callbackFn (optional)
  A function that is called when the dialog is dismissed.

Return value

If callbackFn is omitted, then a Promise is returned that resolves when the user dismisses the dialog. Otherwise, it returns undefined.

textInput()

Syntax

dialog.textInput(title)
dialog.textInput(title, initialValue)
dialog.textInput(title, initialValue, size)
dialog.textInput(title, initialValue, size, doneFn)

The textInput() method displays a popup dialog containing the title followed by a single text input field, both "OK" and "Cancel" buttons. The dialog is dismissed when any button is pressed.

If provided, the callbackFn is called when the dialog is dismissed, with the value of the input field as an argument. If callbackFn is omitted, then a Promise is returned that resolves with the value of the input field when the user presses the "OK" button. The value is undefined if the user presses the "Cancel" button.

Parameters

• title
  The title displayed with the text input field.
• initValue (optional)
  The initial value of the text input field. If omitted, the default is "".
• size (optional)
  The size of the text input field in characters. If omitted, the default is 15.
• callbackFn (optional)
  A function that is called when the dialog is dismissed.

Return value

If callbackFn is omitted, then a Promise is returned that resolves when the user dismisses the dialog. Otherwise, it returns undefined.