@jsvision/ui / MultiCheckGroup

Class: MultiCheckGroup

Defined in: ui/src/controls/multi-check-group.ts:40

A multi-state checkbox group bound to a number[] signal (one state index per item).

Example

import { Group, MultiCheckGroup, signal } from '@jsvision/ui';

// Three states per item: ' ' (off), 'x' (some), 'X' (all).
const levels = signal([0, 2]); // Volume off, Treble full
const group = new MultiCheckGroup({
  items: ['~V~olume', '~T~reble'],
  states: ' xX',
  value: levels,
});
group.layout = { position: 'absolute', rect: { x: 1, y: 0, width: 20, height: 2 } };

const panel = new Group();
panel.add(group);
// Pressing Space on Volume cycles it 0 -> 1 -> 2 -> 0.

Extends

• Cluster

Constructors

Constructor

new MultiCheckGroup(opts): MultiCheckGroup

Defined in: ui/src/controls/multi-check-group.ts:51

Parameters

opts

MultiCheckGroupOptions

{ items, states, value } — see MultiCheckGroupOptions.

Returns

MultiCheckGroup

Overrides

Cluster.constructor

Properties

bounds

bounds: Rect

Defined in: ui/src/view/view.ts:65

Parent-relative integer rect; written by the layout pass — read it in draw/hit-testing.

Inherited from

Cluster.bounds

---

castsShadow

castsShadow: boolean = false

Defined in: ui/src/view/view.ts:78

When true, the renderer paints a drop shadow on the cells just below and to the right of this view, in paint order (a later sibling's shadow falls over an earlier one). Default false. The Desktop sets it per window.

Inherited from

Cluster.castsShadow

---

centered

centered: boolean = false

Defined in: ui/src/view/view.ts:86

When true, the layout pass recentres this view within its parent after layout — origin = (parent - self) / 2 on both axes. Intended for absolutely-placed views (a modal dialog, a message box) whose size is fixed and whose origin would otherwise be placed by the caller. Default false; Dialog sets it when centered.

Inherited from

Cluster.centered

---

enabled

protected readonly enabled: boolean[]

Defined in: ui/src/controls/cluster.ts:37

Per-item enabled flags (all enabled by default).

Inherited from

Cluster.enabled

---

focusable

focusable: boolean = true

Defined in: ui/src/controls/cluster.ts:27

Whether this view can receive keyboard focus. Effective focusability also requires the view to be visible and enabled with no hidden/disabled ancestor. Default false; the focus manager drives the state.focused flag.

Inherited from

Cluster.focusable

---

layout

layout: LayoutProps = {}

Defined in: ui/src/view/view.ts:69

Layout props for this view (direction, size, padding, absolute placement, …).

Inherited from

Cluster.layout

---

parsed

protected readonly parsed: readonly ParsedLabel[]

Defined in: ui/src/controls/cluster.ts:35

Parsed hotkeys (letter + column) for Alt+hotkey matching.

Inherited from

Cluster.parsed

---

postProcess

postProcess: boolean = true

Defined in: ui/src/controls/cluster.ts:29

Post-process so an Alt+hotkey is seen dialog-wide, even when this group isn't focused.

Inherited from

Cluster.postProcess

---

preProcess

preProcess: boolean = false

Defined in: ui/src/view/view.ts:96

Take part in the pre-process sweep (root→down, before the focused view sees the event).

Inherited from

Cluster.preProcess

---

rawLabels

protected readonly rawLabels: readonly string[]

Defined in: ui/src/controls/cluster.ts:33

The original tilde-marked labels.

Inherited from

Cluster.rawLabels

---

sel

protected sel: number = 0

Defined in: ui/src/controls/cluster.ts:31

The focused item index.

Inherited from

Cluster.sel

---

selRange

protected readonly selRange: number

Defined in: ui/src/controls/multi-check-group.ts:44

The number of states; pressing an item advances by one and wraps at this count.

---

state

readonly state: ViewState

Defined in: ui/src/view/view.ts:67

Draw-against flags. The object reference is fixed; individual fields mutate (e.g. focused).

Inherited from

Cluster.state

---

states

protected readonly states: string

Defined in: ui/src/controls/multi-check-group.ts:42

The ordered marker glyphs; states[value()[i]] is drawn for item i.

---

value

protected readonly value: Signal<number[]>

Defined in: ui/src/controls/multi-check-group.ts:46

One state index per item; the two-way source of truth.

Methods

accelerators()

accelerators(): readonly string[]

Defined in: ui/src/controls/cluster.ts:55

Every item's ~X~ Alt-hotkey char (lowercase), for duplicate-accelerator detection. A disabled item still contributes — its Alt+hotkey still registers and would shadow a later item.

Returns

readonly string[]

The claimed accelerator chars across all items (unmarked items omitted).

Inherited from

Cluster.accelerators

---

bind()

bind<T>(reader, apply?, opts?): void

Defined in: ui/src/view/view.ts:228

Bind a reactive value to a redraw. Creates an effect (owned by this view's scope) that reads reader() — subscribing to whatever signals it touches — runs the optional apply(value), then requests a frame: a repaint by default, or a reflow when { relayout: true }. It re-runs automatically whenever those signals change, and is disposed when the view unmounts.

Call it from onMount, not the constructor — the view's scope only exists once mounted, so a pre-mount bind throws rather than silently dropping the binding.

Type Parameters

T

T

Parameters

reader

() => T

Reads the reactive source; the signals it reads become dependencies.

apply?

(v) => void

Optional: apply the read value to the widget (e.g. store it in a field).

opts?

Pass { relayout: true } when the change affects layout, so it reflows instead of just repainting.

relayout?

boolean

Returns

void

Example

import { signal } from '@jsvision/ui';

const count = signal(0);
// `status` is a View whose draw() reads count():
status.onMount(() => {
  status.bind(() => count()); // repaint the status line whenever `count` changes
});

Inherited from

Cluster.bind

---

box()

protected box(): ClusterBox

Defined in: ui/src/controls/multi-check-group.ts:76

The marker box for this group kind.

Returns

ClusterBox

Overrides

Cluster.box

---

derived()

protected derived<T>(fn): () => T

Defined in: ui/src/view/view.ts:261

Create a stable derived accessor owned by this view's scope. The returned () => T keeps the same identity for the life of the view, so it is safe to build in the constructor and hand to child views before this view mounts. The backing computed is created lazily under the view's own scope, so it is always owned and disposed at unmount — unlike a bare computed() in the constructor, which would run before any scope exists, leak, and warn.

Reads behave sensibly across the lifecycle:

• Before mount: evaluates fn() directly (correct current value, nothing persisted). Good for a pre-mount natural-size measure.
• After mount: builds and memoizes a computed(fn) under the view's scope.
• After an unmount→remount: the memo is keyed to the scope it was built under, so a remounted view (which gets a fresh scope) re-derives under the new scope instead of returning the previous mount's disposed, now-frozen computed — keeping a Show/For-remounted widget reactive.

Type Parameters

T

T

Parameters

fn

() => T

The derivation (pure; the signals it reads become the computed's dependencies).

Returns

A stable accessor; call it to read the derived value.

() => T

Inherited from

Cluster.derived

---

desiredCaret()

desiredCaret(): Point | null

Defined in: ui/src/view/view.ts:192

Where this view wants the hardware text cursor, in view-local cells, or null for no cursor (the default — most views never show one). A focused text input overrides this to place the caret at the edit position; the event loop reads it after each frame, converts it to an absolute cell, and moves the terminal cursor there.

Returns

Point | null

The view-local caret point (0-based, relative to this view's origin), or null.

Inherited from

Cluster.desiredCaret

---

draw()

draw(ctx): void

Defined in: ui/src/controls/cluster.ts:94

Paint one item per row: the 5-cell marker box + the ~hotkey~ label, in the per-item role.

Parameters

ctx

DrawContext

The clipped, view-local paint context.

Returns

void

Inherited from

Cluster.draw

---

focusSignal()

focusSignal(): Signal<void>

Defined in: ui/src/view/view.ts:136

Subscribe to this view's focus changes. Reading the returned signal inside a bind/effect re-runs that effect whenever this view gains or loses focus — including from another view (e.g. a Label repainting when the control it labels is focused). The signal notifies on every poke even without a value change. Lazy: the backing signal is created on first call.

Returns

Signal<void>

A signal that ticks whenever this view gains or loses focus.

Example

// Inside a widget's onMount, repaint whenever `other` view's focus changes:
this.onMount(() => this.bind(() => other.focusSignal()()));

Inherited from

Cluster.focusSignal

---

invalidate()

invalidate(): void

Defined in: ui/src/view/view.ts:197

Request a repaint of this view. A no-op before the view is mounted (the first frame paints everything).

Returns

void

Inherited from

Cluster.invalidate

---

invalidateLayout()

invalidateLayout(): void

Defined in: ui/src/view/view.ts:202

Request a reflow (re-run layout, then repaint). Use this when a change affects size/position, not just pixels.

Returns

void

Inherited from

Cluster.invalidateLayout

---

markIndex()

protected markIndex(i): number

Defined in: ui/src/controls/multi-check-group.ts:60

The state index of item i into box().markers. Two-state groups return 0 (off) / 1 (on); a multi-state group returns 0..states-1.

Parameters

i

number

Returns

number

Overrides

Cluster.markIndex

---

measure()?

optional measure(available): Size2D

Defined in: ui/src/view/view.ts:71

Optional intrinsic-size hook for auto sizing — return the size this view wants for available.

Parameters

available

Size2D

Returns

Size2D

Inherited from

Cluster.measure

---

movedTo()

protected movedTo(_i): void

Defined in: ui/src/controls/cluster.ts:71

Fired when ↑/↓ moves the selection. A radio group selects on move; a check group does nothing.

Parameters

_i

number

Returns

void

Inherited from

Cluster.movedTo

---

moveSel()

protected moveSel(dir): void

Defined in: ui/src/controls/cluster.ts:167

Move the selection by dir, skipping disabled items and wrapping; a no-op if none are enabled.

Parameters

dir

-1 | 1

Returns

void

Inherited from

Cluster.moveSel

---

onCleanup()

onCleanup(fn): void

Defined in: ui/src/view/view.ts:298

Register a teardown callback that runs once when this view unmounts. Requires a mounted view — so call it from within onMount. Use it to release anything the view acquired (a timer, an external subscription).

Parameters

fn

() => void

The teardown callback.

Returns

void

Inherited from

Cluster.onCleanup

---

onEvent()

onEvent(ev): void

Defined in: ui/src/controls/cluster.ts:123

Keyboard (↑/↓ move, Space press, Alt+hotkey select) and mouse (click a row to focus and press).

Parameters

ev

DispatchEvent

The dispatch envelope (carries local during real mouse dispatch).

Returns

void

Inherited from

Cluster.onEvent

---

onMount()

onMount(fn): void

Defined in: ui/src/view/view.ts:283

Register a callback to run once when the view becomes live (after its first layout gives it bounds). This is where to call bind, since the view's reactive scope exists by then. Registering after the view is already live runs the callback immediately.

Parameters

fn

() => void

Post-mount setup.

Returns

void

Inherited from

Cluster.onMount

---

press()

protected press(i): void

Defined in: ui/src/controls/multi-check-group.ts:65

Toggle / select / cycle item i, writing the bound signal.

Parameters

i

number

Returns

void

Overrides

Cluster.press

---

selectByClick()?

optional selectByClick(): void

Defined in: ui/src/view/view.ts:182

Optional "select + raise on click" hook. Left undefined on the base, so a plain view is not a select/raise target. A container that owns z-order (a Window) overrides it to select and raise itself. The hit-test invokes the first ancestor that defines this — before delivering the mouse-down — so a click always raises the window even if the interior also consumes the click.

Returns

void

Inherited from

Cluster.selectByClick

---

setItemEnabled()

setItemEnabled(i, on): void

Defined in: ui/src/controls/cluster.ts:82

Enable or disable an item. A disabled item is skipped by ↑/↓, is inert to Space/click, and is drawn greyed.

Parameters

i

number

The item index.

on

boolean

Whether the item is enabled.

Returns

void

Inherited from

Cluster.setItemEnabled