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.
<smart-numeric-keypad> · 12 properties, 6 methods, 4 events · source/modules/smart.numerickeypad.js
Usage in JavaScript
The component is a custom element: its properties are set on the element, its events are DOM CustomEvents with the data in event.detail, and its methods are called on the element. The properties can also be written as attributes in kebab case (precision-digits="1").
const numericKeypad = document.querySelector('smart-numeric-keypad');
numericKeypad.min = 42;
numericKeypad.addEventListener('change', (event) => console.log(event.detail));
numericKeypad.open(42);
Properties
| Property | Type, default | Description |
|---|---|---|
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 | number | Sets or retrieves the lowest value accepted. null sets no floor. |
max | number | Sets or retrieves the highest value accepted. null sets no ceiling. |
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 | string | Sets or retrieves the engineering unit, shown next to the entry, the current value and the limits. |
label | string | Sets or retrieves what is being entered, the tag and the quantity, shown above the entry and in its accessible name. |
allowNegative | boolean | Determines whether the sign key is offered. Off, the key becomes a clear key. |
layout | 'calculator' | 'phone' | 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.calculator phone |
showLimits | boolean | Determines whether the limits are shown under the entry. |
showCurrent | boolean | Determines whether the value being replaced stays in view while the new one is typed. |
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 | 'normal' | 'touch' | 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.normal touch |
Methods
| Method | Description |
|---|---|
open(value?) | 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) | 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() | 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() | Abandons the entry, shows the current value again and raises the cancel event. Raises nothing while the keypad is disabled. |
validate() | 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() | 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