Skip to content

Readout List Item

The Readout List Item is one row of a list of readouts: the label on the left, the value with its unit on the right, and optionally a setpoint, an advice value and the source. It is found in the Maritime - OpenBridge section of the Perspective Component Palette as Readout List Item (Experimental).

Note: This component is experimental: its properties may change in a later version.

Readout List Item: SOG 8.5 kn, setpoint 9.0, source GPS 1

The parts of the row, from the left:

  1. Label — see Label, Unit and Source.
  2. Setpoint — the ordered value, with a triangle. See Setpoint.
  3. Value and unit — see Value.
  4. Source — after a divider. See Label, Unit and Source.

For a stand-alone readout with the label under the value, use the Readout. Most properties work in the same way on both.

A Readout List Item dropped from the palette is 164 × 32 px and shows the value 0 with the label Label:

Readout List Item with default properties

Bind value to the number to show. Set valueUndefined to true, or bind value to null, when there is no value: a dash is shown in its place, and the row keeps its layout.

Row without a value

hasValue set to false removes the value, for a row that is only a label.

Set valueType to text to show a text instead of a number, bound to text: a mode, a state, a name. It is shown as it is, on one line, in the place and colour of the number; numberFormat, maxDigits and the hinted zeros do not apply to it, and an empty text shows a dash. The setpoint and the advice stay numbers.

Row with the text AUTO

Set off to true when the equipment is switched off: the value is replaced by offText (default OFF). The label, unit and source stay.

Row that is off

numberFormat decides how many decimals are shown. It works exactly as on the Readout: only the number of characters after the decimal point is used, # works like 0, there is never a thousands separator, and the decimal separator is always a point.

numberFormat 1234.5678 is shown as
#,##0 (default) Number without decimals
0.0 Number with one decimal
#,##0.## Number with two decimals
numberFormat 1234.5678 0.5 -42
#,##0 (default) 1235 1 -42
0 1235 1 -42
0.0 1234.6 0.5 -42.0
#,##0.00 1234.57 0.50 -42.00
0.00 1234.57 0.50 -42.00
#,##0.## 1234.57 0.50 -42.00
0.### 1234.568 0.500 -42.000
000.0 1234.6 0.5 -42.0

An empty numberFormat is treated as #,##0. The setpoint and the advice use the same number of decimals as the value.

hasDegree adds a degree sign after the value. maxDigits reserves room for that many digits before the decimal point, and with valueOptions.hintedZeros the unused places are drawn as faint zeros:

hasDegree hasDegree, 3 digits and hintedZeros
Heading with degree sign Heading with hinted zeros

The deprecated minValueLength is used only while maxDigits is 0.

hasDegreeSpacer reserves the room of a degree sign after the unit without drawing it, so rows without a degree line up with rows that have one:

Heading with the room of a degree sign

valueOptions.hasSignSpacer reserves the room of a minus sign in front of a value that is not negative; setpointOptions and adviceOptions have it too. The value of a row is aligned to the right, so the spacer only shows where widths are compared, as with a spaceReserver.

Name Description Property Type
hasValue Show the value. Default true. value
value The number. A binding that returns null shows a dash. Only shown when hasValue is true. Default 0. value
valueType number or text. Default number. value
text The text to show when valueType is text. Only shown then. Default empty. value
off Show offText instead of the value. Default false. value
offText The text shown while off is true. Only shown then. Default OFF. value
valueOptions.hasSignSpacer Reserve the room of a minus sign in front of a value that is not negative. Default false. value
valueUndefined Show dashes instead of the value. Only shown when hasValue is true. Default false. value
numberFormat DecimalFormat pattern; only the number of decimals is used. Default #,##0. value
maxDigits Digits before the decimal point to reserve room for. Default 0. value
hasDegree Show a degree sign after the value. Default false. value
hasDegreeSpacer Reserve the room of a degree sign after the unit. Only shown when hasDegree is false. Default false. value

label is the name of the value, unit its unit and src the sensor or system it comes from. Each is shown when its has… property is true. stacking decides where the unit and the source go:

stacking
trailing-unit (default) Unit after the value, source after a divider at the right. Trailing unit
leading-unit Unit under the label; the source stays at the right. Leading unit
leading-src Source under the label; the unit stays after the value. Leading source

hasLeadingIcon draws an icon before the label, chosen in leadingIcon: an icon picker with the path of the icon and useCssColor, which draws the icon in its own colours instead of the text colour. valueOptions.hasIcon and valueOptions.icon do the same before the value.

hasLeadingIcon valueOptions.hasIcon
Row with an icon before the label Row with an icon before the value
Name Description Property Type
hasLabel Show the label. Default true. value
label Name of the value. Only shown when hasLabel is true. Default Label. value
hasUnit Show the unit. Default true. value
unit Unit. Only shown when hasUnit is true. Default empty. value
hasSource Show the source. Default false. value
src Name of the source. Only shown when hasSource is true. Default empty. value
stacking trailing-unit, leading-unit or leading-src. Default trailing-unit. value
hasLeadingIcon Show an icon before the label. Default false. value
leadingIcon.path The icon, from the icon picker. Only shown when hasLeadingIcon is true. Default openbridge/placeholder. value
leadingIcon.useCssColor Draw the icon in its own colours instead of the text colour. Default false. value

size sets the size of the value:

size
small (default) Small row
medium Medium row
large Large row

The row fills the width of the component’s box and keeps its own height at the top of it: about 20 px for small and 48 px for large. Make the box at least that tall. The blue frame is the component’s box:

Row at the top of a taller box

Rows of the same width in a column line up label to label and value to value. To line up values of different length, give every row the same valueOptions.spaceReserver, for example 0000.0.

Name Description Property Type
size small, medium or large. Default small (base is an older name for it). value

Set hasSetpoint to true and bind setpoint to the ordered value. It is shown before the value, smaller, with a triangle:

Row with a setpoint

setpointOptions.interaction decides how the setpoint and the value share the space. The images show a value of 8.5 with a setpoint of 9 (away) and of 8.5 (reached):

interaction Setpoint away
always-visible (default) Always visible, away
equal-size Equal size, away
flip-flop Flip-flop, away
pop-up Pop-up, away
interaction Setpoint reached
always-visible (default) Always visible, reached
equal-size Equal size, reached
flip-flop Flip-flop, reached
pop-up Pop-up, reached

These work as on the Readout: equal-size draws the setpoint in the size of the value, flip-flop makes the setpoint large while it is not reached, and pop-up hides it once the value equals it. setpointOptions.touching shows that the operator is changing the setpoint.

Name Description Property Type
hasSetpoint Show the setpoint. Default false. value
setpoint The ordered value. Only shown when hasSetpoint is true. Default 0. value
setpointUndefined Show dashes instead of the setpoint. Only shown when hasSetpoint is true. Default false. value
setpointOptions.interaction always-visible, equal-size, flip-flop or pop-up. Default always-visible. value
setpointOptions.touching The operator is changing the setpoint. Default false. value

Set hasAdvice to true and bind advice to a recommended value, for example from a route optimiser. It is shown before the value with an advice symbol:

Row with an advice

Name Description Property Type
hasAdvice Show the advice. Default false. value
advice The recommended value. Only shown when hasAdvice is true. Default 0. value
adviceUndefined Show dashes instead of the advice. Only shown when hasAdvice is true. Default false. value

priority set to enhanced draws the value in the enhanced colour. See Priority. valueOptions.weight makes the value bolder without changing its colour.

priority regular (default) priority enhanced
Regular priority Enhanced priority
weight regular (default) semibold
Regular weight Semibold weight
bold
Bold weight
Name Description Property Type
priority regular or enhanced. Two older values are also accepted; see Deprecated Properties. Default regular. value
valueOptions.weight regular, semibold or bold. Default regular. value

dataQuality marks a value that should not be trusted:

dataQuality
none (default) No quality issue. Normal row
low-integrity The value may be wrong, for example a sensor out of calibration. Low integrity
invalid The value is not valid. Invalid

Set hasAlert to true to draw an alert frame around the row. alert is an object with status, type, mode, thickness, textSize and showIcon. The default type is small-side-flip, as in the OpenBridge components: a frame with a flap at the right end that shows the alert symbol. The flap sticks out to the right of the box, so leave room there. In a list, where the rows sit against each other, use regular, a frame that stays inside the box:

Row with a regular alert frame

The statuses, with the default frame:

level-critical level-high (default)
Critical High
level-medium level-low
Medium Low
level-diagnostic alarm (legacy)
Diagnostic Alarm
warning (legacy) caution (legacy)
Warning Caution

The Designer offers the level-* values. alarm, warning and caution are legacy values: they still work when bound or typed in, and look the same as level-high, level-medium and level-low.

type, mode and thickness work as on the automation buttons; see Alert Frame (there they are called alertFrameType, alertFrameMode and alertFrameThickness).

Name Description Property Type
dataQuality none, low-integrity or invalid. Default none. value
hasAlert Draw an alert frame around the row. Default false. value
alert The frame. Only shown when hasAlert is true. object
alert.status The status: a level-* value (the legacy alarm, warning and caution still work). Default level-high. value
alert.type regular, small-side-flip, large-side-flip, bottom-flip or top-flip. Default small-side-flip. value
alert.mode acked-active, unacked-active or unacked-rectified. Default acked-active. value
alert.thickness small or large. Default small. value
alert.textSize regular or large. Default regular. value
alert.showIcon Default false. value

The value, setpoint, advice, unit and source each have an object of options: valueOptions, setpointOptions, adviceOptions, unitOptions and srcOptions. Each is only shown when its part is shown (hasValue, hasSetpoint, …).

Sub-property In Description
hintedZeros value, setpoint, advice Draw the unused places up to the digit count as faint zeros. Default false.
spaceReserver all The longest text to keep room for, such as 0000.0 or miles, so rows line up. Default empty.
dataQuality value, setpoint, advice, source Data quality of this part only: none, low-integrity or invalid. Default none.
hasAlert value, setpoint, advice, source Draw an alert frame around this part only. Default false.
alert value, setpoint, advice, source That frame, with the sub-properties of alert above. Only shown when hasAlert is true.
weight value See Priority and Weight.
hasIcon value Show an icon before the value, chosen in icon. Default false.
icon value The icon before the value: path and useCssColor. Only shown when hasIcon is true.
hasSignSpacer value, setpoint, advice Reserve the room of a minus sign in front of a value that is not negative. Default false.
interaction setpoint See Setpoint.
touching setpoint See Setpoint.

All of these are value properties inside an object.


Set clickable to true to make the row a button: it looks like a plain row until it is hovered or pressed, and a click fires the onActionPerformed event, for a row that opens a detail view. clickableBorder shapes the pressed area: squared (default), round (a pill) or round-corners.

clickable, pressed clickableBorder = round, pressed
Pressed clickable row Pressed clickable row with round ends
Name Description Property Type
clickable Make the row a button that fires onActionPerformed. Default false. value
clickableBorder squared, round or round-corners. Only shown when clickable is true. Default squared. value

These properties are from an older version of the component. They still work, so that existing views keep working; do not use them in new views.

Name Use instead
size base, priority, enhanced small, medium, large
priority setpoint priority regular with setpointOptions.interaction always-visible
priority setpoint-flip-flop priority regular with setpointOptions.interaction flip-flop
dataState dataQuality, used when dataQuality is none
hasSetpointValue, setpointValue hasSetpoint, setpoint, used when those are missing
hasValueIcon valueOptions.hasIcon
showZeroPadding, hasHintedZeros valueOptions.hintedZeros
minValueLength maxDigits, used while maxDigits is 0
labelOnly hasValue, hasUnit, hasSource, hasSetpoint and hasAdvice set to false

Event Description Event Object
onActionPerformed Fired when the operator clicks a row that has clickable set to true. —

The standard Perspective events, such as onClick, are available in the component’s event configuration too.

  1. Drop a Flex Container (column) into the view, 240 px wide.
  2. Add three Readout List Items, each 240 × 32 px.
  3. Set their label to SOG, COG and DEPTH, and unit to kn, empty and m. On COG set hasDegree to true.
  4. Set numberFormat to 0.0 on all three, and valueOptions.spaceReserver to 000.0 so the values line up.
  5. Bind value to [default]Navigation/SOG, [default]Navigation/COG and [default]Navigation/Depth.
  6. Bind dataQuality on each to an expression such as if(isGood({[default]Navigation/SOG}), 'none', 'invalid').

Built on the OpenBridge Design System