Instrument readouts and controls
<smart-numeric-keypad>NumericKeypad is an on-screen keypad for entering a numeric value such as a setpoint on a touch panel.
It validates the entry against min and max and shows the reason when the value is out of range instead of clamping it, limits the entry to the configured precisionDigits, keeps the current value in view while the new one is typed, and provides optional step keys. Accepting the entry raises the change event. A physical keyboard can also type into the keypad while it has focus, and the touch density enlarges the keys for gloved use. The decimal separator shown is the locale's, a comma for de, fr and es, and the entry is announced to screen readers as it is typed.
<smart-numeric-keypad>smart-industrial/source/modules/smart.numerickeypad.jsNumericKeypadModule from smart-industrial/angular/numerickeypadNumericKeypad from smart-industrial/react/numerickeypad<NumericKeypad> in Smart.Blazor.Industrial
Install the package, load the two stylesheets and the component's module, and put the element on the page. The element below is the first one of the demo. Put the script after the module, in a <script type="module">, so that it runs once the component is defined.
npm install smart-industrial
<link rel="stylesheet" href="node_modules/smart-industrial/source/styles/smart.default.css" />
<link rel="stylesheet" href="node_modules/smart-industrial/source/styles/smart.industrial-elements.css" />
<script type="module" src="node_modules/smart-industrial/source/modules/smart.numerickeypad.js"></script>
<smart-numeric-keypad id="flow" label="FIC-101 setpoint" unit="m³/h" min="0" max="120"
precision-digits="1" allow-negative="false"></smart-numeric-keypad>
const numericKeypad = document.getElementById('flow');
// raised when an entry is accepted
numericKeypad.addEventListener('change', (event) => {
const { value, previousValue } = event.detail;
// ...
});
// the same values as properties
numericKeypad.min = 0;
numericKeypad.max = 120;
numericKeypad.precisionDigits = 1;
numericKeypad.label = 'FIC-101 setpoint';
The getting started guide covers the bundle, the ISA-101 themes and the license key; the connectivity guide covers feeding the properties from plant tags.
The properties the demo sets, then the next ones; the API page lists all 12 with their types and defaults.
| Name | Type, default | Description |
|---|---|---|
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. |
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 | string | 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. |
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. |
layout | string | 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. |
The events carry their data 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. |
| 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. |
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. |
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. |
The same element with its wrapper. Each page has the installation steps and the full demo in that framework.
import { NumericKeypadModule } from 'smart-industrial/angular/numerickeypad';
// Angular 14 and later; an NgModule application lists NumericKeypadModule in its imports
@Component({
standalone: true,
imports: [NumericKeypadModule],
template: `<smart-numeric-keypad label="FIC-101 setpoint"
(onChange)="onChange($event)">
</smart-numeric-keypad>`
})
import { NumericKeypad } from 'smart-industrial/react/numerickeypad';
<NumericKeypad label="FIC-101 setpoint"
onChange={(event: CustomEvent) => onChange(event.detail)} />
import 'smart-industrial/source/modules/smart.numerickeypad.js';
<smart-numeric-keypad label="FIC-101 setpoint"
@change="onChange"></smart-numeric-keypad>
@using Smart.Blazor.Industrial
@rendermode InteractiveServer
<NumericKeypad Label="FIC-101 setpoint"
OnChange="OnChange" />
The NumericKeypad is one tab stop and accepts input from a physical keyboard: the digits, the decimal point, minus, Backspace, Delete, Enter and Escape work while it has focus, so an operator at a desk does not need the on-screen keys. The entry field is a read-only text box named for the value being entered, the current value and the limits are plain text next to it, and a rejected entry is an alert with the reason, read as soon as Enter is pressed.
| Key | Action |
|---|---|
| Tab | Moves onto the keypad, and off it. The keypad is one stop. |
| 0-9 | Types a digit. The first key after opening replaces the shown value; a digit beyond the precision does nothing. |
| . or , | Types the decimal point, unless the precision is 0. |
| - | Changes the sign, when negative values are allowed. |
| Backspace / Delete | Removes the last character / clears the entry. |
| Enter | Accepts the entry, raising change - or refuses it with the reason, raising invalid, and leaves it on screen. |
| Escape | Cancels the entry and shows the value in force again, raising cancel. |
The accessibility page has every attribute, key and announcement; the WCAG 2.2 conformance report covers the whole library.
The component follows the theme on the page: the default theme, or the ISA-101 light and dark themes that ship with the package. It declares 7 CSS variables of its own, among them --smart-numeric-keypad-key-size, --smart-numeric-keypad-gap, --smart-numeric-keypad-key-background, --smart-numeric-keypad-key-border. The CSS page lists them; the themes guide covers the tokens every component shares.
Bar Graph Bit Field Jog Panel Knob Momentary Button Panel Meter Selector Switch Seven Segment Thermometer Touch Keyboard