Instrument readouts and controls

Numeric Keypad `<smart-numeric-keypad>`

NumericKeypad is an on-screen keypad for entering a numeric value such as a setpoint on a touch panel.

JavaScript TypeScript Angular React Vue Blazor

<smart-numeric-keypad> · 12 properties, 6 methods, 4 events · source/modules/smart.numerickeypad.js

Usage in Vue

Vue uses the custom element directly. A property is bound with :kebab-name; an array or an object needs the .prop modifier so that Vue sets the property rather than an attribute. Events are listened to with @eventName; methods are called on the element through a template ref.

import 'smart-industrial/source/modules/smart.numerickeypad.js';

<smart-numeric-keypad ref="numericKeypad" :min="42"
    @change="onEvent"></smart-numeric-keypad>

// methods are called on the element the ref holds
numericKeypad.value.open(42);

// an array or an object is set as a property, not converted to an attribute: use .prop
<smart-numeric-keypad :steps.prop="steps"></smart-numeric-keypad>

Properties

Binding	Type, default	Description
`:value` value	number	Sets or retrieves the last accepted value, or the value the keypad was opened with. It is shown as the current value while a new value is typed.
`:min` min	number	Sets or retrieves the lowest value accepted. null sets no floor.
`:max` max	number	Sets or retrieves the highest value accepted. null sets no ceiling.
`:precision-digits` precisionDigits	number	Sets or retrieves the maximum number of decimal places of the entry. null allows any number of decimals; 0 makes the keypad integer-only and replaces the decimal key with a clear key. A key that would exceed the precision is ignored. Values above 15 are taken as 15, the most decimal places a number holds. A step key finer than the precision moves the entry by at least one decimal place in its direction.
`:unit` unit	string	Sets or retrieves the engineering unit, shown next to the entry, the current value and the limits.
`:label` label	string	Sets or retrieves what is being entered, the tag and the quantity, shown above the entry and in its accessible name.
`:allow-negative` allowNegative	boolean true	Determines whether the sign key is offered. Off, the key becomes a clear key.
`:layout` layout	NumericKeypadLayout calculator	Sets or retrieves the digit layout. calculator places 7 8 9 on the top row, as on an HMI keypad; phone places 1 2 3 there.
`:show-limits` showLimits	boolean true	Determines whether the limits are shown under the entry.
`:show-current` showCurrent	boolean true	Determines whether the value being replaced stays in view while the new one is typed.
`:steps` steps	array	Sets or retrieves quick steps, for example [-10, -1, 1, 10], shown as keys that adjust the entry from the current value.
`:density` density	NumericKeypadDensity normal	Sets or retrieves the key size. touch makes keys 60 px with a wider gap, for a panel PC with gloves. Reflected to an attribute the stylesheet keys on.

Methods

Method	Description
`open(value?: number): void`	Starts an entry from a value, shows it as the current value and takes focus. The first key replaces the shown value, as on a calculator. `value` number The value to start from. Defaults to the value property.
`press(key: any): void`	Presses a key: a digit, '.', '-', 'backspace', 'clear', 'enter', 'escape', or a step given as a number. A digit beyond fifteen significant digits is ignored, as a number holds no more. `key` any The key.
`accept(): boolean`	Validates the entry against the limits and the precision. If the entry is valid, sets the value and raises the change event. If it is not, the entry stays on screen, the reason is shown and the invalid event is raised. Returns whether the entry was accepted. Only something typed is accepted: with nothing typed since open, accept or cancel - a second Enter, a double click or a double tap on Enter, a held Enter - it raises nothing and returns false, and it returns false while the keypad is disabled.
`cancel(): void`	Abandons the entry, shows the current value again and raises the cancel event. Raises nothing while the keypad is disabled.
`validate(): string`	Returns the reason the entry would be rejected ('empty', 'notANumber', 'tooPrecise', 'belowMin' or 'aboveMax'), or null when it would be accepted. A point typed first shows as 0. and is 'empty' until a digit follows: the zero was not typed.
`text(): string`	Returns the text entered so far.

Events

The data of an event is in event.detail. input reports the text being typed and invalid an entry the numeric keypad refused. On accept the keypad sets value and then raises change, and cancel follows once the entry is back at the current value.

Event	Description and detail
`@change`	This event is triggered when an entry is accepted. Raised once per entry. `value` number The value accepted. `previousValue` number The value it replaces, or null.
`@invalid`	This event is triggered when an entry is refused. Nothing is written. `text` string The entry as typed. `reason` string 'empty', 'notANumber', 'tooPrecise', 'belowMin' or 'aboveMax'.
`@cancel`	This event is triggered when the entry is abandoned.
`@input`	This event is triggered on every key that changes the entry. `text` string The entry so far.

Types

`type NumericKeypadLayout`

'calculator' | 'phone'

`type NumericKeypadDensity`

'normal' | 'touch'

CSS variables

The component declares 7 CSS variables; the CSS page shows how to set them.

--smart-numeric-keypad-key-size --smart-numeric-keypad-gap --smart-numeric-keypad-key-background --smart-numeric-keypad-key-border --smart-numeric-keypad-accept --smart-numeric-keypad-accept-text --smart-numeric-keypad-refuse