Number Input Field

This text is AI-generated

This documentation was written with the help of AI and has not been fully reviewed. If something is wrong, unclear or missing, please let us know. Use the feedback form, and say which section it concerns.

The Number Input Field lets the operator type a number. It is found in the Input - OpenBridge section of the Perspective Component Palette as Number Input Field.

The parts of the field:

1. Label — above the field. See Label and Helper Text.
2. Field — the number and its unit, with an optional leading icon. See Value, Number Format and Field.
3. Helper text — below the field, replaced by the error text when the field is in error. See Label and Helper Text and Error.

The Number Input Field is one of the input components. How values are written back, events, disabling, icons and the behavior in the Designer are shared by all of them and are described in Input Components — Common Features. It is the numeric sibling of the Text Input Field: the label, helper text and error work in the same way. This page covers what is specific to the Number Input Field.

A Number Input Field dropped from the palette is empty and has no label:

The field is as wide as the component. The label and the helper text need height: make the component about 96 px tall when both are used.

Value

value is the number in the field. Bind it bidirectionally to a tag or property to connect the field to it (see Values).

Value
Placeholder
Unit

placeholder is a hint shown while the field is empty, and unit is a text shown after the number.

The field accepts digits, a minus sign and a decimal separator; letters are not entered. When the operator empties the field, value is written as null.

When the Value Is Written

deferUpdates decides when the field writes value and fires onActionPerformed:

• false (default) — for every keystroke. A binding on value sees each intermediate number: typing 1234.5 writes 1, 12, 123, 1234 and 1234.5.
• true — once, when the operator leaves the field. Use it when the value goes to a tag or starts an action, so that a half-typed number is not written.

Note: Pressing Enter does not write the value. With deferUpdates set to true the value is written when the field loses focus, for instance when the operator presses Tab or clicks elsewhere.

Updates While the Operator Types

While the field has focus it keeps showing what the operator is typing, also when a binding writes a new value in the meantime. rejectUpdatesWhileFocused is meant to control this, as on the Text Input Field; on the Number Input Field an incoming value was not shown while the field had focus with either setting.

Limiting What Can Be Typed

• maxlength — the highest number of characters the operator can type. With 3, the fourth character is not entered.
• validationPattern — a regular expression. A keystroke or paste is only accepted when the resulting text matches it. With ^[0-9]{0,2}$ the operator can type at most two digits, and no sign or decimals. Leave it empty for the ordinary numeric filter.

Properties

Name	Description	Property Type
value	Number in the field. Written when the operator types. Empty (null) by default.	value
unit	Text shown after the number, for example kn. Empty by default.	value
placeholder	Hint shown while the field is empty.	value
deferUpdates	Write value when the field is left, instead of for every keystroke. Default false.	value
rejectUpdatesWhileFocused	Ignore values written from a binding while the field has focus. Default false.	value
maxlength	Highest number of characters that can be typed. Not set by default: no limit.	value
minlength	Lowest number of characters required. Not set by default. See the note below.	value
validationPattern	Regular expression that the typed text must match for a keystroke to be accepted. Empty.	value

Note: minlength had no visible effect when tested: a shorter number was written and the field was not marked as invalid. Use Error with an expression to check the value.

---

Number Format

numberFormat decides how the number is displayed when the operator is not editing it. It does not change value.

numberFormat	1234.5678 is shown as
#,##0.## (default)
#,##0.00
0.0

The format is written as a Java DecimalFormat pattern, as elsewhere in Ignition. The field reads three things from it:

• a comma turns on the thousands separator,
• each 0 after the decimal point is a decimal that is always shown,
• each # after the decimal point is a decimal that is shown when needed.

numberFormat	1234.5678	0.5	-42
#,##0.## (default)	1,234.57	0.5	-42
#,##0.00	1,234.57	0.50	-42.00
#,##0	1,235	1	-42
0.##	1234.57	0.5	-42
0.00	1234.57	0.50	-42.00
0.0	1234.6	0.5	-42.0
0.000	1234.568	0.500	-42.000
0	1235	1	-42

Things to know:

• The number is rounded to the decimals of the format for display only. With 0.0, typing 1.26 writes 1.26 to value; the field shows 1.3 when the operator leaves it.
• Other parts of a DecimalFormat pattern are ignored: leading zeros (000.0 does not pad the number), prefixes and suffixes, percent and exponent patterns. Use unit for a unit.
• The separators follow the language of the browser. The table shows an English browser; a Norwegian one shows 1 234,57.
• An empty numberFormat is treated as #,##0.

Without a Format

Set formatNumber to false to show every decimal of the value. The numberFormat property is then hidden.

The thousands separator is still shown. To show the number without it, keep formatNumber true and use a format without a comma, such as 0.####.

Properties

Name	Description	Property Type
formatNumber	Round the displayed number to the decimals of numberFormat. Default true.	value
numberFormat	DecimalFormat pattern. Default #,##0.##. Only shown when formatNumber is true.	value

---

Field

Text Alignment

textAlign
right (default)	The number and unit are at the right of the field.
center	The number and unit are in the centre.
right-unit-outside	The number is at the right and the unit is placed after the field.

Size

size
regular (default)	The standard height.
large	A taller field, easier to hit.

Make the component at least 64 px tall for a large field.

Leading Icon

Set hasLeadingIcon to true to show an icon at the start of the field. leadingIcon is chosen with the icon picker. See Icons.

Read-only

Set readonly to true for a field whose number can be read, but not changed. Unlike a disabled field it is not dimmed.

Properties

Name	Description	Property Type
textAlign	right, center or right-unit-outside. Default right.	value
size	Height of the field: regular or large. Default regular.	value
hasLeadingIcon	Show an icon at the start of the field. Default false.	value
leadingIcon	The icon, chosen with the icon picker. Only shown when hasLeadingIcon is true.	object
readonly	The operator cannot change the number. Default false.	value

---

Label and Helper Text

label is shown above the field and helperText below it. Each can be placed to the left, centre or right, and each can have an icon in front of it. They work as on the Text Input Field.

Placement	labelPlacement	helperPlacement
left (default)
center
right

Label icon	Helper icon

Required

Set required to true to mark the field as one that must be filled in. A dot is shown after the label. The mark is only a visual cue: the field does not check the value itself.

Properties

Name	Description	Property Type
label	Text above the field. Empty by default.	value
labelPlacement	left, center or right. Default left.	value
hasLabelIcon	Show an icon before the label. Default false.	value
labelIcon	The icon, chosen with the icon picker. Only shown when hasLabelIcon is true.	object
helperText	Text below the field. Empty by default.	value
helperPlacement	left, center or right. Default left.	value
hasHelperIcon	Show an icon before the helper text. Default false.	value
helperIcon	The icon, chosen with the icon picker. Only shown when hasHelperIcon is true.	object
required	Mark the field as required. Default false.	value

---

Error

Set error to true to show the field as invalid, with a red border. errorText is shown below the field.

With errorText	Without

The field does not check the value against a range itself. Bind error to an expression that checks the value (see Example 2).

Properties

Name	Description	Property Type
error	Show the field as invalid. Default false.	value
errorText	Text shown below the field. Only shown when error is true.	value

---

Disabled

See Disabled.

---

Common Properties

These work in the same way on every input component, and are described in Input Components — Common Features:

• Disabled — disabled.
• Icons — how to choose leadingIcon, labelIcon and helperIcon.
• Appearance — style.

Component Events

Event	Description	Event Object
onActionPerformed	Fired when value is written: for every keystroke, or when the field is left when deferUpdates is true.	—

See Events.

Examples

Example 1 — Speed Setpoint

1. Drop a Number Input Field into the view, make it about 200 × 96 px and set label to Speed.
2. Set unit to kn and numberFormat to 0.0, so the speed is shown with one decimal.
3. Set deferUpdates to true, so the setpoint is written when the operator leaves the field and not for every digit.
4. Bind value to the tag [default]Pump01/Setpoint and enable Bidirectional.

Example 2 — Limit the Range

With the field from Example 1:

1. Bind error to the expression {this.props.value} < 0 || {this.props.value} > 30.
2. Set errorText to Must be between 0 and 30.

The field still writes a value outside the range; the error only shows it to the operator. Check the range where the value is used as well.