JSVision

Appearance

@jsvision/ui / ScrollBar

Class: ScrollBar ​

Documented in: Scroll bar

Defined in: ui/src/scroll/scroll-bar.ts:68

A scroll bar: arrows + a page track + a proportional thumb, driven by mouse (see the module docs).

Example ​

ts
import { ScrollBar, Group, createEventLoop, signal } from '@jsvision/ui';
import { resolveCapabilities } from '@jsvision/core';

const caps = resolveCapabilities({ env: {}, platform: 'linux' }).profile;
const pos = signal(0);
const bar = new ScrollBar({ value: pos, min: 0, max: 100, orientation: 'vertical' });
bar.layout = { position: 'absolute', rect: { x: 0, y: 0, width: 1, height: 8 } };

const root = new Group();
root.add(bar);
const loop = createEventLoop({ width: 1, height: 8 }, { caps });
loop.mount(root);
pos.set(50); // scroll externally — the thumb re-renders halfway down

Extends ​

Constructors ​

Constructor ​

new ScrollBar(opts): ScrollBar

Defined in: ui/src/scroll/scroll-bar.ts:87

Parameters ​

opts ​

ScrollBarOptions

value (two-way signal) + optional min/max/pageStep/arrowStep/orientation.

Returns ​

ScrollBar

Overrides ​

View.constructor

Properties ​

arrowStepVal ​

protected arrowStepVal: number

Defined in: ui/src/scroll/scroll-bar.ts:79

Arrow-click step (mutable — an owner viewer re-wires it via setRange).

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 ​

View.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 ​

View.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 ​

View.centered

dragging ​

protected dragging: boolean = false

Defined in: ui/src/scroll/scroll-bar.ts:82

True while a thumb-drag gesture holds the pointer capture.

focusable ​

focusable: boolean = false

Defined in: ui/src/scroll/scroll-bar.ts:69

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.

Overrides ​

View.focusable

layout ​

layout: LayoutProps = {}

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

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

Inherited from ​

View.layout

max ​

protected max: number

Defined in: ui/src/scroll/scroll-bar.ts:75

Range maximum (mutable — see setRange).

min ​

protected min: number

Defined in: ui/src/scroll/scroll-bar.ts:73

Range minimum (mutable — an owner Scroller/ListView re-limits via setRange).

pageStepOpt? ​

protected optional pageStepOpt?: number

Defined in: ui/src/scroll/scroll-bar.ts:77

Explicit page step, or undefined for the axis-length default (mutable via setRange).

postProcess ​

postProcess: boolean = false

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

Take part in the post-process sweep (after the focused view sees the event).

Inherited from ​

View.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 ​

View.preProcess

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 ​

View.state

value ​

protected readonly value: Signal<number>

Defined in: ui/src/scroll/scroll-bar.ts:71

The two-way bound position (source of truth).

vertical ​

protected readonly vertical: boolean

Defined in: ui/src/scroll/scroll-bar.ts:80

Methods ​

accelerators() ​

accelerators(): readonly string[]

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

The Alt+hotkey accelerator characters (lowercase) this view claims in its focus scope, for duplicate-accelerator detection. The base returns none; accelerator-bearing widgets (Button/Label/CheckGroup/RadioGroup) override it to report their ~X~ hotkey(s).

Returns ​

readonly string[]

The claimed accelerator chars, or an empty list when the view claims none.

Inherited from ​

View.accelerators

arrowStep() ​

arrowStep(): number

Defined in: ui/src/scroll/scroll-bar.ts:157

The effective arrow-click step; the wheel steps 3× this.

Returns ​

number

axisLen() ​

protected axisLen(): number

Defined in: ui/src/scroll/scroll-bar.ts:123

The drawn/measured long-axis length in cells (height when vertical, else width).

Returns ​

number

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 ​

ts
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 ​

View.bind

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 ​

View.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 ​

View.desiredCaret

draw() ​

draw(ctx): void

Defined in: ui/src/scroll/scroll-bar.ts:167

Paint the bar: an arrow at each end in the scrollBarControls role, a ▒ track (or a full ▓ fill when disabled) in scrollBarPage, and the thumb in scrollBarControls at its current cell.

Parameters ​

ctx ​

DrawContext

The clipped, view-local paint context.

Returns ​

void

Overrides ​

View.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 ​

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

Inherited from ​

View.focusSignal

getPos() ​

protected getPos(len): number

Defined in: ui/src/scroll/scroll-bar.ts:144

The thumb cell along the axis, in [1, getSize()-2] — the position mapped proportionally from value within [min, max] and pinned between the two end arrows.

Parameters ​

len ​

number

The long-axis length in cells.

Returns ​

number

The 0-based thumb index.

getSize() ​

protected getSize(len): number

Defined in: ui/src/scroll/scroll-bar.ts:128

The effective bar length, never below 3 (an arrow at each end plus at least one track/thumb cell).

Parameters ​

len ​

number

Returns ​

number

handleDown() ​

protected handleDown(ev, mark): void

Defined in: ui/src/scroll/scroll-bar.ts:222

Mouse-down: on the thumb ⇒ start a captured drag; on an end arrow ⇒ step once; on the track ⇒ jump the thumb to the clicked position and enter the same captured drag, so the pointer keeps driving it.

Parameters ​

ev ​

DispatchEvent

mark ​

number

Returns ​

void

handleDrag() ​

protected handleDrag(ev, mark): void

Defined in: ui/src/scroll/scroll-bar.ts:240

Captured drag: map the axis position back to a proportional value.

Parameters ​

ev ​

DispatchEvent

mark ​

number

Returns ​

void

handleUp() ​

protected handleUp(ev): void

Defined in: ui/src/scroll/scroll-bar.ts:255

Mouse-up: end a drag + release the capture.

Parameters ​

ev ​

DispatchEvent

Returns ​

void

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 ​

View.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 ​

View.invalidateLayout

jumpTo() ​

protected jumpTo(mark, s): void

Defined in: ui/src/scroll/scroll-bar.ts:247

Map an axis position mark to a proportional value, clamped between the two end arrows.

Parameters ​

mark ​

number

s ​

number

Returns ​

void

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 ​

View.measure

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 ​

View.onCleanup

onEvent() ​

onEvent(ev): void

Defined in: ui/src/scroll/scroll-bar.ts:197

Route mouse gestures (the bar owns no keys). Arrow/page click steps once; a thumb click captures the pointer and maps subsequent moves to value; wheel steps 3·arrowStep.

Parameters ​

ev ​

DispatchEvent

The dispatch envelope (carries local + the setCapture/releaseCapture seams).

Returns ​

void

Overrides ​

View.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 ​

View.onMount

pageStep() ​

pageStep(): number

Defined in: ui/src/scroll/scroll-bar.ts:152

The effective page step (the configured pageStep, else the axis length − 1).

Returns ​

number

partCode() ​

protected partCode(mark, pos, s): number

Defined in: ui/src/scroll/scroll-bar.ts:270

Classify a clicked cell into a part code (start/end arrow, page-back/-forward, or the thumb). Vertical parts add 4 so the same code space distinguishes the two orientations.

Parameters ​

mark ​

number

The along-axis click cell.

pos ​

number

The current thumb cell.

s ​

number

The last cell index (getSize()-1).

Returns ​

number

put() ​

protected put(ctx, i, char, style): void

Defined in: ui/src/scroll/scroll-bar.ts:186

Write one glyph at axis index i (col 0 / row 0 on the cross axis).

Parameters ​

ctx ​

DrawContext

i ​

number

char ​

string

style ​

Style

Returns ​

void

readValue() ​

protected readValue(): number

Defined in: ui/src/scroll/scroll-bar.ts:133

The current position clamped into [min,max] (a stray owner write can't index out of range).

Returns ​

number

scrollStep() ​

protected scrollStep(part): number

Defined in: ui/src/scroll/scroll-bar.ts:281

The signed step for a part code: bit 1 selects page vs arrow step, bit 0 selects forward vs back.

Parameters ​

part ​

number

Returns ​

number

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 ​

View.selectByClick

setRange() ​

setRange(min, max, pageStep?, arrowStep?): void

Defined in: ui/src/scroll/scroll-bar.ts:115

Re-limit the bar at runtime — an owning Scroller/ListView calls this when its viewport or content extent changes. The bound value is not written here; it is clamped into the new range on read, so a shrunk range never over-scrolls or throws.

Parameters ​

min ​

number

New range minimum.

max ​

number

New range maximum (raised to min if smaller).

pageStep? ​

number

New page step, or undefined to keep the axis-length default.

arrowStep? ​

number

New arrow step, or undefined to keep the current one. A multi-column list wires this to its row count so an arrow-click jumps a whole column; a single-column owner leaves it at 1.

Returns ​

void

setValue() ​

protected setValue(next): void

Defined in: ui/src/scroll/scroll-bar.ts:287

Write the bound position, clamped to [min,max].

Parameters ​

next ​

number

Returns ​

void