Instrument readouts and controls
Panel Meter <smart-panel-meter>
PanelMeter draws the moving-coil instrument screwed into the front of a rack: a rectangular case, a shallow arc of scale across the top of it and a long needle swinging from a pivot near the bottom.
<smart-panel-meter> · 41 properties, 1 methods, 1 events · source/modules/smart.panelmeter.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.panelmeter.js';
<smart-panel-meter ref="panelMeter" :label="'Bus'" :interactive="true"
@change="onEvent"></smart-panel-meter>
// methods are called on the element the ref holds
panelMeter.value.refresh();
// an array or an object is set as a property, not converted to an attribute: use .prop
<smart-panel-meter :items.prop="items"></smart-panel-meter>
Properties
| Binding | Type, default | Description |
|---|---|---|
:center-zero | boolean | A centre-zero movement: the needle rests in the middle of the scale and a heavier zero line is drawn there. It sets nothing on the scale itself, which is min and max, it marks the rest position. |
:coerce | boolean | When the coerce property is set to true, any value provided will automatically be adjusted to the nearest valid value based on the defined interval. This ensures that the resulting value always conforms to the step size specified by the interval property, even if the original input does not exactly match an allowed value. |
:custom-interval | boolean | Determines whether custom tick marks, which may be placed at uneven intervals, are displayed on the plot. The specific positions of these custom ticks are specified using the customTicks property. This option allows you to override the default tick placement and use your own set of tick values. |
:custom-ticks | Array<number | Date> | When customInterval is enabled, you can define a specific list of tick values to be displayed on the plot. If coerce is set to true, any input value will automatically snap to the nearest tick from this predefined list, ensuring that only these tick values can be selected or represented. |
:damping | number | The inertia of the coil, in milliseconds for the needle to settle. 0 is an undamped movement. The value is never animated, only the needle: a reader of the property gets the reading, and the digital display shows it undamped, so the instrument cannot show two different values for the same instant. |
:date-label-format-string | string | Specifies the format of the date labels that appear when the mode property is set to 'date'. This determines how dates are displayed on the labels (e.g., 'YYYY-MM-DD', 'MM/DD/YYYY'). |
:decimal-separator | string | Sets or gets the character written between the integer and the fractional part of a number, such as "." or ",", in the readout, the scale labels, the setpoint title and the accessible text. Left at "." it follows locale: a German, French or Spanish locale writes a comma, as Intl.NumberFormat does for that locale; any other character is used as set. Digits are never grouped. A value given as a string is always read with a period. |
:interactive | boolean | Lets the reading be set by pointer or keyboard. A meter reads by default: it has role="meter" and is out of the tab order. With interactive on, it has role="slider", takes focus, and an arrow-key step starts from the end stop when the reading is off the scale. |
:interval | number | "When the 'coerce' property is set to 'true', all input values are automatically adjusted to fall within the specified interval. Any value outside the interval will be coerced to the nearest boundary value of the interval." |
:inverted | boolean | Specifies the orientation of the gauge. When set to true, the starting and ending positions of the gauge are reversed, causing the gauge to be displayed in the opposite direction. If false, the gauge follows its default direction. Use this option to customize the gauge's flow based on your application's requirements. |
:label | string | What is being measured, screened on the plate at the left of the movement. It is used as the accessible name of the component. |
:label-format-function | function | null | A callback function that allows you to customize the formatting of the values shown within the gauge labels. This function receives the raw value as an argument and should return the formatted string to be displayed. Use this to control the appearance, number formatting, units, or localization of label values inside the gauge. |
:labels-visibility | LabelsVisibility | Specifies whether the labels within the element are displayed or hidden. When set to true, the labels inside the element are visible; when set to false, the labels are not shown. This property allows you to control the display of label text within the element. |
:localize-format-function | function | null | A callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized strings are structured or displayed before they are delivered to your application, enabling support for advanced formatting, variable interpolation, or context-specific adaptations. |
:logarithmic-scale | boolean | Controls whether the element displays data using a logarithmic scale. When enabled, values are plotted on a logarithmic axis, which is useful for visualizing data that spans several orders of magnitude. When disabled, a standard linear scale is used. |
:max | number | Date | Sets or gets the top of the scale. A reading above it is kept as written: the needle rests against the right end stop and OVER is shown on the plate. |
:mechanical-action | 'switchUntilReleased' | 'switchWhenReleased' | 'switchWhileDragging' | Specifies the event or condition that triggers the update of the element’s value, such as on user input, when focus is lost, or after a specific action occurs. This setting controls how and when changes to the element's value are recognized and processed in the application. |
:min | number | Date | Sets or gets the bottom of the scale. A reading below it is kept as written: the needle rests against the left end stop and UNDER is shown on the plate. |
:mirror | boolean | Draws the anti-parallax mirror band under the scale: the strip an operator lines the needle up with its own reflection in, which is how a moving-coil meter is read accurately. |
:mode | 'date' | 'numeric' | Specifies whether the element is configured to handle numerical values or date values, enabling appropriate functionality and validation for each data type. |
:name | string | Specifies or retrieves the element’s name attribute, which serves as the identifier for the element’s value when form data is submitted to the server. This name is used as the key in the name-value pair sent with the form submission, enabling the server-side application to access the corresponding data. |
:precision-digits | number | Sets or gets how many digits are shown after the decimal point in the readout, the setpoint title and the accessible text. Values outside 0 to 20 are held to that range. null shows the reading as written, to at most twelve significant digits, so an arrow-key step never shows binary noise such as 0.30000000000000004. |
:quality | PanelMeterQuality | Sets or retrieves the quality of the reading: good, uncertain, bad or stale. Reflected to an attribute so the stylesheet can show it: the needle is dimmed for uncertain and stale and greyed over a hatched plate for bad, and the word UNCERTAIN, BAD or STALE is printed at the top left of the plate so it is legible without colour. The scale and its numbers are never dimmed. The quality is also added to the accessible name, for example "Bus, quality bad". A reading whose quality is not good must never look, or read out, as though it were. Carried onto the element by Smart.Industrial.Connect bindings. |
:ranges | {startValue?: number | Date, endValue?: number | Date, className?: string}[] | This property is an array containing multiple objects, where each object defines a distinct range. Each range represents a colored area characterized by its own specific size and properties, such as start and end values, color, and label. These ranges allow you to visually differentiate segments according to predefined criteria on a graphical interface or data visualization component. |
:readonly | boolean | When the element is set to read-only, users are unable to modify its value or content; they can view the information but cannot interact with or edit the element in any way. |
:right-to-left | boolean | Sets or gets whether the Left and Right arrow keys are swapped for a right-to-left language, such as Arabic or Hebrew, when the meter is interactive. A CSS direction of rtl on the component has the same effect. The property does not mirror the drawing. |
:scale-type | ScaleType | Specifies the data type used for the gauge’s value and defines the corresponding scale (e.g., linear, logarithmic). This setting ensures that input values are interpreted correctly and displayed with the appropriate measurement scale on the gauge. |
:scientific-notation | boolean | Specifies whether numerical values should be displayed using scientific notation (e.g., 1.23e+4) instead of standard decimal formatting. Set to true to enable scientific notation, or false to display numbers in regular decimal form. |
:setpoint | number | The value the red set pointer is clipped to on the scale plate. null for none. |
:show-ranges | boolean | This property determines whether the gauge’s range indicators are displayed on the gauge component. When set to true, the range segments (such as colored bands or sections representing value intervals) will be visible on the gauge; when set to false, these range indicators will be hidden. |
:show-setpoint | boolean | Draws the set pointer. |
:show-unit | boolean | Prints the unit on the plate at the right of the movement and after the digital reading. It is on by default: an instrument whose plate does not say what it measures cannot be read. |
:show-value | boolean | Shows the digital reading under the case, at the precision set by precisionDigits. It is never damped, and it shows -- when there is no reading. |
:significant-digits | number | null | Calculates the number of significant digits present in a given number. This property is relevant only when the scaleType is set to 'integer', ensuring that the digit count pertains exclusively to whole numbers, not decimals or other formats. |
:sweep-angle | number | How far the needle travels, in degrees. A moving-coil movement swings about 90 to 120 degrees; a scale wider than that is a dial, which is what the Gauge draws. |
:ticks-visibility | TicksVisibility | Controls whether the ticks are displayed or hidden on the axis. If set to true, ticks will be visible; if false, ticks will be hidden. This option allows you to toggle the tick marks for improved chart customization. |
:unit | string | Sets or gets the unit of the reading, such as bar or °C. It is printed on the scale plate and after the digital reading while showUnit is set. Empty by default, so nothing is printed until a unit is given. |
:unlock-key | string | Provides a way to retrieve or assign the unlockKey property, which is a unique code required to activate or gain access to the product's full features. Use this property to securely manage the product's access control. |
:validation | Validation | Not applied by the panel meter: the reading is never clamped to min and max; a reading past either end is shown as OVER or UNDER. |
:value | string | number | date | Sets or retrieves the reading, as a number or a decimal string, in the unit of the scale. It is kept as written and never clamped: a reading past min or max pins the needle against that end stop, raises the OVER or UNDER flag on the plate and is read out as over range or under range, and the read-only offScale getter returns 'over', 'under' or ''. A value that is not a finite number - null, NaN, an infinity, an empty or non-numeric string such as '0x1F' - is no reading: the needle is removed, the case is dashed, NO DATA is shown on the plate, the readout shows --, and aria-valuenow is removed. With coerce and customInterval, the reading is snapped to the interval. |
:word-length | WordLength | Gets or sets the word length used for values. This property is only applicable when scaleType is set to 'integer'; it has no effect for other scale types. |
Methods
| Method | Description |
|---|---|
refresh(): void | Redraws the face. |
Events
The data of an event is in event.detail. The panel meter sets value as the operator drags the needle or presses an arrow key, only while interactive is true and readonly is false, and then raises change; the application reads the new value from event.detail.
| Event | Description and detail |
|---|---|
@change | This event is triggered when the reading is changed through the component, which only happens when interactive is enabled.value number The new reading. |
Types
type LabelsVisibility
'all' | 'endPoints' | 'none'
type DragMechanicalAction
'switchUntilReleased' | 'switchWhenReleased' | 'switchWhileDragging'
type ScaleMode
'date' | 'numeric'
type PanelMeterQuality
'good' | 'uncertain' | 'bad' | 'stale'
type ScaleType
'floatingPoint' | 'integer'
type TicksVisibility
'major' | 'minor' | 'none'
type Validation
'interaction' | 'strict'
type WordLength
'int8' | 'int16' | 'int32' | 'int64' | 'uint8' | 'uint16' | 'uint32' | 'uint64'
CSS variables
The component declares 8 CSS variables; the CSS page shows how to set them.
--smart-panel-meter-width --smart-panel-meter-plate --smart-panel-meter-bezel --smart-panel-meter-ink --smart-panel-meter-tick --smart-panel-meter-needle --smart-panel-meter-setpoint --smart-panel-meter-mirror