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 the overlay page keypad, which is separate from the dialog page. The page has the state variables keypad_current (a modelObject holding the current layout, key function, resolve function, and initial value), keypad_className (a modelValue that drives the show/hide slide animation, 'keypad-show' or 'keypad-hide'), keypad_value (a textOutput holding the displayed value string), and keypad_units (a textOutput holding the displayed units string). The page is opened by keypad.open() through nav.overlayPage('keypad', {layout, value, units, keyFn, resolve}); the argument properties are the keypad.open() arguments plus the resolve function of the returned Promise. Applications should use the keypad methods rather than opening the page directly.

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.

Internally the keypad value is a string, which for formats that allow negative numbers starts with a + or - sign; the Promise is resolved with the value converted by Number(). The keypad.number() method returns a Promise. The Promise is resolved with the final value as a number. If the user cancels the data entry, the value is reset to the initial value and the Promise is resolved with it (the Promise is never rejected).

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 keypad value, as a number, when the user dismisses the keypad. If the user cancels, the Promise is resolved with the initial value; it is never rejected.

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. A null or other falsy entry produces a blank cell. 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. Only one keypad can be open at a time.

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; the default does not handle backspace.

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. A null or other falsy entry is rendered as a blank cell.
• value (optional)
  The initial value. The keypad value is handled as a string (it is converted with String() for display and passed to keyFn as a string), although any value can be supplied. 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, the default is (value, key) => value + key: the value of a pressed key is appended to the current keypad value. The default has no special handling of 'backspace', so a layout with a backspace key needs its own keyFn.

Return value

A Promise that is resolved with the final keypad value string when the user dismisses the keypad with "Done". If the user presses "Cancel", the value is reset to the initial value and the Promise is resolved with it; the Promise is never rejected. If a keypad is already open, the call does nothing and returns undefined.

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 value other than undefined is provided in the right argument (null leaves it blank). 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 undefined or not provided, the key will be a backspace symbol (keypad.backspaceKey). If null, the key will be blank. 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

An object {text:'&leftArrowD;', value:'backspace'}.

plusMinusKey

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

Value

The string '+/-'.

pointKey

A key layout entry representing a decimal point key.

Value

An object {text:'•', value:'.'}.