Keypad Reference

Related documents

• NumFmt Reference

Table of contents

• Introduction
• Exported identifiers
  • keypad
• keypad methods
  • number()
  • numFmtLayout()
  • open()
  • stdNumLayout()
• keypad properties
  • backspaceKey
  • plusMinusKey
  • pointKey

Introduction

MVCS provides a customizable popup keypad. The keypad can contain numbers, letters, or symbols in a flexible arrangement. It provides easier data entry for specific inputs and a standard interface across all platform types.

The keypad is controlled using the keypad object. The keypad.open() method will open a custom keypad, while the keypad.number() method will open a numeric keypad. Both methods return a Promise for receiving the results. The keypad.open() method is the most flexible. It provides a custom key layout grid, and custom key handling.

The keypad is implemented as a keypad popup page.

Exported identifiers

keypad

Syntax

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

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

keypad methods

number()

Syntax

keypad.number(numFmt, value, units)
keypad.number(numFmt, value)
keypad.number(numFmt)

Opens a numeric keypad that can handle numbers specified by the numFmt argument. If the value argument is provided, it sets the initial value. Otherwise, the intial value is zero. If the units argument is provided, then it is used to display a unit abbreviation following the value.

The numFmt argument is a NumFmt object. If the format allows both positive and negative numbers the keypad will include +/- key to change the sign of the keypad value. If the format allows fractional digits than a . key will be provided and the keypad will automatically enter a '.' after the maximum integer digits have been entered.

The keypad.number() method returns a Promise. The Promise is resolved with the final value. The Promise will be rejected if the user cancels the data entry.

Parameters

• numFmt
  A NumFmt object to use to layout the keypad and optimize data entry.
• value (optional)
  A number that represents the initial value. If omitted, the initial value is zero.
• units (optional)
  A unit abbreviation string. If provided, the unit abbreviation string will be displayed after the current value on the keypad.

Return value

A Promise that is resolved with the value keypad value when the user dismisses the keypad. The Promise will be rejected if the user cancels the data entry.

numFmtLayout()

Syntax

keypad.numFmtLayout(numFmt)

Returns a numeric keypad layout array appropriate to a given NumFmt object. The numFmt argument is a NumFmt object. If the format allows both positive and negative numbers the keypad will include +/- key to change the sign of the keypad value. If the format allows fractional digits than a . key will be included.

Parameters

• numFmt
  A NumFmt object to use to layout the keypad.

Return value

An keypad layout array suitable for the keypad.open() method.

open()

Syntax

keypad.open(layout, value, units, keyFn)
keypad.open(layout, value, units)
keypad.open(layout, value)
keypad.open(layout)

Open a custom keypad. The layout argument is an array of button rows. Each row is an array of button symbol strings or an object containing both text and value properties. If the value argument is provided, it sets the initial value. Otherwise, the intial value is zero. If the units argument is provided, then it is used to display a unit abbreviation following the value.

If the keyFn argument is provided, it is a function that is called for each new key press. It is given the current keypad value and the value associated with a key, and it returns an updated keypad value. The function is allowed to reject a particular key press by returning the same keypad value it was given. If no keyFn argument is provided, then the value of a pressed key is appended to the current keypad value.

Parameters

• layout
  An array representing each keypad row. Each element is an array representing the buttons in that row. Each entry is either a string representing both the button label and the value or an object with text and value string properties. In the latter case, the text will be used for the button label while the value will be passed as the value of the key press.
• value (optional)
  A number that represents the initial value. If omitted, the initial value is zero.
• units (optional)
  A unit abbreviation string. If provided, the unit abbreviation string will be displayed after the current value on the keypad.
• keyFn (optional)
  A function with signature keyfn(curValue, keyValue) that is called for each key press. The arguments are:
  • curValue
    The current keypad value string.
  • keyValue
    The current value string associated with the pressed key's layout entry.
    The function returns an updated keypad value string. If no keyFn argument is provided, then the value of a pressed key is appended to the current keypad value. However, if the keyValue is the string 'backspace' then the rightmost character of the current key value is deleted.

Return value

A Promise that is resolved with the value keypad value when the user dismisses the keypad. The Promise will be rejected if the user cancels the data entry.

stdNumLayout()

Syntax

keypad.stdNumLayout(left, right)
keypad.stdNumLayout(left)
keypad.stdNumLayout()

Returns a numeric keypad layout array for a standard phone style numeric keypad. The button on the lower left will be blank unless a non-null value is provided in the left argument. The button on the lower right will be a backspace symbol unless a non-null value is provided in the right argument. As with the keypad.open() method layout entries, the arguments can be a single string or an object containing both text and value properties.

Parameters

• left (optional)
  The entry for the lower lefthand button in the keypad. If nullish or not provided, the key will be blank. If provided, the value can be a single string or an object containing both text and value properties.
• right (optional)
  The entry for the lower righthand button in the keypad. If nullish or not provided, the key will be a backspace symbol and will behave as a backspace key. If provided, the value can be a single string or an object containing both text and value properties.

Return value

An keypad layout array suitable for the keypad.open() method.

keypad properties

backspaceKey

A key layout entry representing a backspace key.

Value

A string.

plusMinusKey

A key layout entry representing a +/- or change sign key.

Value

A string.

pointKey

A key layout entry representing a decimal point key.

Value

A string.