Instrument readouts and controls

Bit Field <smart-bit-field>

BitField displays a fixed-width register as individual bits with names, keeping the word value and the bits in sync.

<smart-bit-field> · 8 properties, 3 methods, 1 events · source/modules/smart.bitfield.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.bitfield.js';

<smart-bit-field ref="bitField" :interactive="true" :interactive="true"
    @change="onEvent"></smart-bit-field>

// methods are called on the element the ref holds
bitField.value.bit(42);

// an array or an object is set as a property, not converted to an attribute: use .prop
<smart-bit-field :bits.prop="bits"></smart-bit-field>

Properties

Binding	Type, default	Description
:bit-order bitOrder	BitFieldBitOrder msbFirst	Sets or retrieves the display order of the bits. It affects the display only; bits are always numbered from the least significant bit, so bit 3 is the same bit in both orders.
:bits bits	array	Sets or retrieves the register map, as [{ index, label, description, readOnly, color }]. index counts from the least significant bit. A bit marked readOnly refuses to change, a register map is a contract, and a UI that lets an operator flip a reserved bit is lying about the hardware. An entry that is not an object is skipped.
:group-size groupSize	number 4	Sets or gets the number of bits grouped together visually. Groups are counted from the least significant end, so nibble boundaries line up with the hexadecimal digits underneath. 0 removes the grouping.
:interactive interactive	boolean false	Sets or retrieves whether the bits can be toggled by click or keyboard. The property is named for the enabled state because boolean attributes are presence-based, and a property that defaulted to true could not be turned off from markup. When false the bits are not buttons and not in the tab order.
:radix-display radixDisplay	BitFieldRadixDisplay hex	Sets or retrieves how the word value is written beneath the bits.
:show-indices showIndices	boolean true	Sets or retrieves whether each bit shows its number. Boolean attributes are presence-based, so set the property from script to turn it off.
:value value	string | null 0	Sets or retrieves the word. Accepts a number, a BigInt, a boolean, or a string with an optional sign and 0x, 0b or 0o prefix (-0x1 is minus one; 1e3 is 1000); a negative value is treated as two's complement. The value is read back as a decimal string - signed for a signed word length, so an int16 at all ones reads -1 - because a 64-bit value cannot be represented exactly as a number. A value wider than the word length is masked, and one that cannot be read becomes 0: whatever was assigned, the property reads back in this form.
:word-length wordLength	BitFieldWordLength uint16	Sets or retrieves the register width and signedness. Signedness shows only in the decimal readout: the same bit pattern is 65535 as a uint16 and -1 as an int16.

Methods

Method	Description
bit(index: number): boolean	Returns the value of one bit. The index counts from the least significant bit regardless of the bitOrder property. index number Bit position from the least significant bit.
mask(mask: number | string | bigint, on?: boolean): void	Sets or clears every bit that is set in the mask, as a "clear faults" command does. A bit marked readOnly in the register map is not changed, and bits beyond the word length are ignored. mask number | string | bigint The bits to act on. on boolean Set them (the default) or clear them.
setBit(index: number, on?: boolean): void	Sets, clears or toggles one bit. A bit marked readOnly in the register map is not changed. index number Bit position from the least significant bit. on boolean Force a state instead of toggling.

Events

The data of an event is in event.detail. The bit field toggles a bit in value when the operator clicks it, only while interactive is true, and then raises change; setBit() and mask() do the same. A bit marked readOnly in bits stays as it is.

Event	Description and detail
@change	This event is triggered when the word changes through the component, a click, the keyboard, setBit or mask. Assigning the value property directly does not raise it. value string The new word, as a decimal string. oldValue string The previous word. bit number Which bit changed, or null when a mask changed several at once.

Types

type BitFieldBitOrder

'msbFirst' | 'lsbFirst'

type BitFieldRadixDisplay

'hex' | 'dec' | 'bin' | 'oct' | 'none'

type BitFieldWordLength

'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'int64' | 'uint64'

CSS variables

The component declares 5 CSS variables; the CSS page shows how to set them.

--smart-bit-size --smart-bit-off-color --smart-bit-on-color --smart-bit-gap --smart-bit-group-gap