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 JavaScript

The component is a custom element: its properties are set on the element, its events are DOM CustomEvents with the data in event.detail, and its methods are called on the element. The properties can also be written as attributes in kebab case (precision-digits="1").

const bitField = document.querySelector('smart-bit-field');

bitField.interactive = true;
bitField.interactive = true;
bitField.addEventListener('change', (event) => console.log(event.detail));
bitField.bit(42);

Properties

Property	Type, default	Description
bitOrder	'msbFirst' | 'lsbFirst' 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. msbFirst most significant bit on the left, the way hardware documentation is written lsbFirst least significant bit on the left
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	'hex' | 'dec' | 'bin' | 'oct' | 'none' hex	Sets or retrieves how the word value is written beneath the bits. hex 0x-prefixed, zero-padded to the word width dec decimal, signed when the word length is signed bin 0b-prefixed, zero-padded to the word width oct 0o-prefixed none no word readout
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	'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'int64' | 'uint64' 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. int8 int8 uint8 uint8 int16 int16 uint16 uint16 int32 int32 uint32 uint32 int64 int64 uint64 uint64

Methods

Method	Description
bit(index) returns 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, on?)	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, on?)	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