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 React

The React wrapper is the BitField component: every property is a prop, every event a prop named on<Event> that receives the CustomEvent, and the methods are called on the element through a ref.

import { BitField } from 'smart-industrial/react/bitfield';

const ref = useRef<BitField>(null);

<BitField ref={ref} interactive={true} interactive={true}
    onChange={(event: CustomEvent) => console.log(event.detail)} />

// methods are called on the wrapper the ref holds, which calls the element
ref.current?.bit(42);

Properties

Prop	Type, default	Description
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	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.
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	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.
radixDisplay	BitFieldRadixDisplay hex	Sets or retrieves how the word value is written beneath the bits.
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	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.
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
onChange 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