JSVision

Appearance

@jsvision/ui / Desktop

Class: Desktop ​

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

The window manager and desktop background. Its children are its windows, in back-to-front order.

Example ​

ts
import { createApplication, Window } from '@jsvision/ui';
import { resolveCapabilities } from '@jsvision/core';

const caps = resolveCapabilities({ env: process.env, platform: process.platform }).profile;
const app = createApplication({ caps });

// Open two windows on the desktop.
const editor = new Window('Editor');
editor.number = 1;
editor.layout.rect = { x: 1, y: 1, width: 30, height: 8 };
app.desktop.addWindow(editor);

const output = new Window('Output');
output.number = 2;
output.layout.rect = { x: 10, y: 4, width: 30, height: 8 };
app.desktop.addWindow(output);

// Arrange them and switch between them.
app.desktop.tile();
app.desktop.focusNextWindow();
app.desktop.shadow = true; // give every window a drop shadow

Extends ​

Constructors ​

Constructor ​

new Desktop(): Desktop

Returns ​

Desktop

Inherited from ​

Group.constructor

Properties ​

background? ​

optional background?: keyof Theme

Defined in: ui/src/view/group.ts:64

Optional background theme role filled before children compose, so overlap never leaks cells.

Inherited from ​

Group.background

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 ​

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

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

Group.centered

children ​

readonly children: View[] = []

Defined in: ui/src/view/group.ts:62

Ordered children; array order is paint order (back-to-front).

Inherited from ​

Group.children

focusable ​

focusable: boolean = false

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

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 ​

Group.focusable

layout ​

layout: LayoutProps = {}

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

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

Inherited from ​

Group.layout

postProcess ​

postProcess: boolean = true

Defined in: ui/src/desktop/desktop.ts:73

Handle the window-management commands after the focused window has had a chance at the event.

Overrides ​

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

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

Group.state

Accessors ​

shadow ​

Get Signature ​

get shadow(): boolean

Defined in: ui/src/desktop/desktop.ts:90

Whether every window casts a drop shadow. Shadows are painted in z-order, so a front window's shadow falls correctly over the windows behind it. Off by default. Setting it updates every current window, and windows added later inherit it.

Returns ​

boolean

Set Signature ​

set shadow(on): void

Defined in: ui/src/desktop/desktop.ts:93

Parameters ​
on ​

boolean

Returns ​

void

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 ​

Group.accelerators

activeWindow() ​

activeWindow(): Window | null

Defined in: ui/src/desktop/desktop.ts:129

The active (front-most, focused) window, or null if there are none.

Returns ​

Window | null

add() ​

add(child): void

Defined in: ui/src/view/group.ts:88

Add a child, appending it on top (later in the array draws in front). If this group is already mounted, the child mounts immediately — its scope nested under this group's — and a reflow is scheduled for the new layout; otherwise the child mounts when this group itself mounts.

Parameters ​

child ​

View

The view to append.

Returns ​

void

Inherited from ​

Group.add

addDynamic() ​

addDynamic(build): void

Defined in: ui/src/view/group.ts:135

Add children reactively from a Show/For accessor, so the set of children updates itself as signals change. When the group is mounted, an effect reads the accessor, mounts any newly produced views, unmounts any that disappeared (firing their onCleanup), and schedules a reflow on change. Pass a factory that builds the combinator inside itself, not an already-built accessor — this lets the group own and dispose the combinator's reactive nodes on unmount.

Parameters ​

build ​

DynamicBuilder

A factory that constructs the combinator, e.g. () => Show(cond, then) or () => For(each, key, render).

Returns ​

void

Example ​

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

const open = signal(false);
const group = new Group();
group.addDynamic(() => Show(() => open(), () => new Panel())); // Panel appears when `open` is true

Inherited from ​

Group.addDynamic

addWindow() ​

addWindow(w): void

Defined in: ui/src/desktop/desktop.ts:134

Add a window to the desktop, bring it to the front, and focus it.

Parameters ​

w ​

Window

Returns ​

void

attachLoop() ​

attachLoop(seam): void

Defined in: ui/src/desktop/desktop.ts:124

Attach the event-loop seam. createApplication calls this after building the loop; you do not call it yourself.

Parameters ​

seam ​

DesktopLoopSeam

The loop operations the desktop needs (capture, commands, focus).

Returns ​

void

beginMove() ​

beginMove(w, grabLocal): void

Defined in: ui/src/desktop/desktop.ts:211

Start dragging a window: record the grab offset and capture the pointer.

Parameters ​

w ​

Window

grabLocal ​

Point

Returns ​

void

beginResize() ​

beginResize(w): void

Defined in: ui/src/desktop/desktop.ts:220

Start resizing a window from its bottom-right corner: fix the top-left and capture the pointer.

Parameters ​

w ​

Window

Returns ​

void

beginResizeLeft() ​

beginResizeLeft(w): void

Defined in: ui/src/desktop/desktop.ts:233

Start resizing a window from its bottom-left corner: anchor the right edge and top and capture the pointer, so the drag grows the bottom-left corner.

Parameters ​

w ​

Window

Returns ​

void

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 ​

Group.bind

cascade() ​

cascade(): void

Defined in: ui/src/desktop/desktop.ts:181

Cascade all windows from the top-left.

Returns ​

void

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 ​

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

Group.desiredCaret

draw() ​

draw(ctx): void

Defined in: ui/src/desktop/desktop.ts:113

Paint the desktop background: fill the whole area with the repeating desktop pattern.

Parameters ​

ctx ​

DrawContext

Returns ​

void

Overrides ​

Group.draw

focusNextWindow() ​

focusNextWindow(): void

Defined in: ui/src/desktop/desktop.ts:193

Bring the next window in z-order to the front.

Returns ​

void

focusPrevWindow() ​

focusPrevWindow(): void

Defined in: ui/src/desktop/desktop.ts:199

Bring the previous window in z-order to the front.

Returns ​

void

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 ​

Group.focusSignal

focusWindowNumber() ​

focusWindowNumber(n): void

Defined in: ui/src/desktop/desktop.ts:205

Bring the window whose number === n to the front (Alt+n); a no-op if there is no such window.

Parameters ​

n ​

number

Returns ​

void

handleCommand() ​

protected handleCommand(command): boolean

Defined in: ui/src/desktop/desktop.ts:291

Run a window-management command (a disabled command never reaches here). Returns true when the command was one the desktop handles, so the caller can mark it consumed.

Parameters ​

command ​

string

Returns ​

boolean

handleViewportResize() ​

handleViewportResize(): void

Defined in: ui/src/desktop/desktop.ts:107

Re-fit every window to the desktop's new size: maximized windows re-maximize to the new area and each window's restored rect is clamped back on-screen. The app calls this on a viewport resize.

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 ​

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

Group.invalidateLayout

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 ​

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

Group.onCleanup

onEvent() ​

onEvent(ev): void

Defined in: ui/src/desktop/desktop.ts:246

Handle a captured drag (move/resize), the window-management commands, and the Alt+digit window-switch keys. During a drag, mouse events arrive here directly with desktop-local coordinates.

Parameters ​

ev ​

DispatchEvent

Returns ​

void

Overrides ​

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

Group.onMount

raise() ​

raise(w): void

Defined in: ui/src/desktop/desktop.ts:165

Bring w to the front, focus it, and re-theme the active/inactive window frames.

Parameters ​

w ​

Window

Returns ​

void

remove() ​

remove(child): void

Defined in: ui/src/view/group.ts:104

Remove a child: dispose its scope (recursively disposing its descendants and running their onCleanup), detach it, and schedule a reflow. Removing a non-child (or removing twice) is a safe no-op.

Parameters ​

child ​

View

The view to remove.

Returns ​

void

Inherited from ​

Group.remove

removeWindow() ​

removeWindow(w): void

Defined in: ui/src/desktop/desktop.ts:144

Remove a window from the desktop; the next window down becomes active.

Parameters ​

w ​

Window

Returns ​

void

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 ​

Group.selectByClick

tile() ​

tile(): void

Defined in: ui/src/desktop/desktop.ts:187

Tile all windows into a grid filling the desktop.

Returns ​

void

windows() ​

protected windows(): Window[]

Defined in: ui/src/desktop/desktop.ts:99

The desktop's windows in z-order (every child is a Window; the filter keeps it type-safe).

Returns ​

Window[]