# gizapp/window

The window front end of an app run (host.giz): the app's pages in a window of the desktop, drawn by the engine (gizbrowser), as giz://NAME/ in a live view: the page's timers fire when due, the changes its live channel brings are drawn as they come, and its actions post to the app. Settings, the file chooser and GizBrowser are such windows.

A window holds its views in layers (Host): the first fills it below its top, and each later one is an overlay drawn above (a bar whose menus spill over the page) that takes the points it covers and leaves the rest to the views below. The desktop's colour scheme (the XDG portal's) reaches every view as it changes. Each view runs in a renderer process (gizbrowser/renderer): the window only sends it input and shows its frames, so a page that faults or is killed ends its renderer, and the window shows that it stopped and goes on.

```gizlang
import * as Window from "gizapp/window";
```

## Types

### `Hooks`

```gizlang
type Hooks = { key: (e: Win.Input, name: string) => bool; command: (name: string) => bool; aside: (href: string) => bool; turn: () => bool; }
```

What an app does in its window's loop: KEY gets each key before the pages (NAME as the page knows it; true when the
app took it), COMMAND each giz: command a page followed (Renderer.commands: "giz:back"), ASIDE a link opened aside (a
middle click or Ctrl+click; true when the app took it: a new tab), and TURN runs after each turn of the loop, for the
app to follow its views (a title, a bar). False from COMMAND or TURN closes the window.

- `key`: `(arg0: gizlang_window.Input, arg1: string) => bool`
- `command`: `(arg0: string) => bool`
- `aside`: `(arg0: string) => bool`
- `turn`: `() => bool`

### `Host`

```gizlang
class Host { win: Win.Window; views: Vec<Renderer> = []; tops: Vec<i64> = []; width: i64 = 0; height: i64 = 0; pointed: i64 = -1; sized: bool = false; dark: bool = false; dirty: bool = true; whole: bool = true; shown: Vec<Vec<i64>> = []; shownCount: i64 = 0; buffers: Map<i64, i64> = new Map(); pressing: bool = false; shownTitle: string = ""; schemes: Task.Channel<bool>; constructor(title: string, id: string, width: i64, height: i64) throws string { const win = Win.open((name: string): Option<string> => sys.environment(name), title, id, width, height); this.win = win; this.width = width; this.height = height; this.schemes = Win.followScheme(win.waker()); } view(name: string, socket: string, asides: bool): Renderer { let sites = new Map<string, string>(); sites.set(name, socket); let v = new Renderer(sys.executable(), sites, this.width, this.height, asides); v.wake = this.win.waker(); return v; } add(v: Renderer, top: i64): void { this.views.push(v); this.tops.push(top); this.fit(this.views.length - 1); } put(i: i64, v: Renderer): void { this.views[i] = v; this.fit(i); } fit(i: i64): void { this.views[i].fit(this.width, this.height - this.tops[i], this.dark, i> 0); this.dirty = true; this.whole = true; } title(text: string): void { if (text === this.shownTitle) { return; } this.shownTitle = text; try { this.win.title(text); } catch (why: string) {} } run(hooks: Hooks): i64 throws string { while (true) { if (this.dirty && this.sized) { this.draw(); } const got = this.win.next(this.dirty ? FRAME_MS: -1); if (got !== undefined) { const e = got!; if (e.kind === Win.CLOSE) { break; } if (!this.input(e, hooks)) { break; } } const scheme = Task.tryReceive(this.schemes); if (scheme !== undefined && scheme! !== this.dark) { this.dark = scheme!; for (let i = 0; i <this.views.length; i + = 1) { this.fit(i); } } let open = true; for (let v of this.views) { if (v.pump()) { this.dirty = true; } for (const c of v.commands) { if (!hooks.command(c)) { open = false; } } v.commands = []; for (const href of v.asides) { hooks.aside(href); } v.asides = []; for (const text of v.copies) { try { this.win.copy(text); } catch (why: string) { say(why); } } v.copies = []; } if (this.pointed> = 0 && this.pointed <this.views.length) { try { this.win.cursor(this.views[this.pointed].pointing); } catch (why: string) { say(why); } } const given = closing(); if (given> = 0) { this.win.close(); return given; } if (!open || !hooks.turn()) { break; } } this.win.close(); return 0; } draw(): void { const canvas = this.win.canvas(); if (canvas === undefined) { return; } const c = canvas!; this.dirty = false; let top = c.height; let bottom = 0; if (this.whole) { top = 0; bottom = c.height; this.buffers = new Map(); this.shown = []; } for (let i = 0; i <this.views.length; i + = 1) { const d = this.views[i].damage(); if (d[0] <d[1]) { const from = d[0] + this.tops[i]; const to = d[1] + this.tops[i]; if (from <top) { top = from; } if (to> bottom) { bottom = to; } } } this.whole = false; if (top <0) { top = 0; } if (bottom> c.height) { bottom = c.height; } if (top> = bottom) { return; } const changed = [top, bottom]; const held = this.buffers.get(c.at); if (held === undefined || this.shownCount - held!> this.shown.length) { top = 0; bottom = c.height; } else { for (let k = this.shown.length - (this.shownCount - held!); k <this.shown.length; k + = 1) { if (this.shown[k][0] <top) { top = this.shown[k][0]; } if (this.shown[k][1]> bottom) { bottom = this.shown[k][1]; } } } for (let i = 0; i <this.views.length; i + = 1) { const at = this.tops[i] <c.height ? this.tops[i]: c.height; this.views[i].draw({ at: c.at + at * c.stride * 4, width: c.width, height: c.height - at, stride: c.stride }, top - at, bottom - at); } this.shown.push(changed); this.shownCount + = 1; if (this.shown.length> 4) { this.shown = this.shown.slice(1, this.shown.length); } this.buffers.set(c.at, this.shownCount); try { this.win.present([0, top, c.width, bottom - top]); } catch (why: string) { say(why); } } at(x: f64, y: f64): i64 { for (let i = this.views.length - 1; i> 0; i - = 1) { const v = this.views[i]; const vy = y - f64(this.tops[i]); if (vy> = 0.0 && (v.holding() || v.covers(x, vy))) { return i; } } return this.views.length> 0 && y> = f64(this.tops[0]) ? 0: -1; } focused(): i64 { for (let i = this.views.length - 1; i> 0; i - = 1) { if (this.views[i].holding() || this.views[i].typing()) { return i; } } return this.views.length> 0 ? 0: -1; } input(e: Win.Input, hooks: Hooks): bool { if (e.kind === Win.RESIZE) { this.width = e.width; this.height = e.height; this.sized = true; for (let i = 0; i <this.views.length; i + = 1) { this.fit(i); } return true; } if (!this.sized) { return true; } if (e.kind === Win.KEY || e.kind === Win.COMPOSE || e.kind === Win.COMMIT) { this.dirty = true; const name = e.kind === Win.KEY ? keyName(e.key, e.text): ""; if (e.kind === Win.KEY && hooks.key(e, name)) { return true; } const i = this.focused(); if (i <0) { return true; } let v = this.views[i]; if (e.kind === Win.COMPOSE) { v.compose(e.text); } else if (e.kind === Win.COMMIT) { v.commit(e.text); } else if (name === "v" && (e.modifiers & (Win.CONTROL | Win.ALT)) === Win.CONTROL && v.typing()) { try { v.paste(this.win.paste()); } catch (why: string) { say(why); } } else if (name !== "") { v.key(name, e.text, e.modifiers); } this.method(); return true; } const i = this.at(e.x, e.y); if (i <0) { return true; } let v = this.views[i]; const y = e.y - f64(this.tops[i]); if (e.kind === Win.WHEEL) { v.wheel(e.x, y, e.dx, e.dy); } else if (e.kind === Win.MOVE) { v.move(e.x, y, this.pressing); this.pointed = i; } else if (e.kind === Win.RELEASE) { this.pressing = false; } else if (e.kind === Win.PRESS) { this.pressing = e.button === Win.BUTTON_LEFT; for (let k = 0; k <this.views.length; k + = 1) { if (k !== i) { this.views[k].blur(); } } const aside = e.button === Win.BUTTON_MIDDLE || (e.button === Win.BUTTON_LEFT && (e.modifiers & Win.CONTROL) !== 0); const button = e.button === Win.BUTTON_LEFT ? 0: e.button === Win.BUTTON_MIDDLE ? 1: e.button === Win.BUTTON_RIGHT ? 2: e.button === Win.BUTTON_BACK ? BUTTON_BACK: e.button === Win.BUTTON_FORWARD ? BUTTON_FORWARD: -1; if (button> = 0) { v.press(e.x, y, button, aside); } this.method(); } return true; } method(): void { const i = this.focused(); const caret = i> = 0 && this.views[i].typing() ? this.views[i].caret(): undefined; try { if (caret === undefined) { this.win.typing(false, 0, 0, 0, 0); } else { const r = caret!; this.win.typing(true, i64(r.x), i64(r.y) + this.tops[i], i64(Math.ceil(r.w)), i64(Math.ceil(r.h))); } } catch (why: string) { say(why); } } }
```

A window of the desktop and the views drawn in it, in layers.

- `win`: `gizlang_window.Window`
- `views`: `Vec<Ref<_gizlang_lib_browser__renderer.Renderer>>` — The layers, bottom first, and how far below the window's top each starts.
- `tops`: `Vec<i64>`
- `width`: `i64`
- `height`: `i64`
- `pointed`: `i64` — The layer the pointer last moved over (-1: none).
- `sized`: `bool` — Whether the desktop sized the window yet (its first RESIZE): nothing is drawn before.
- `dark`: `bool`
- `dirty`: `bool`
- `whole`: `bool` — Whether every row is to be drawn next (a new size, layout or scheme); else only the rows the views changed.
- `shown`: `Vec<Vec<i64>>` — The rows [top, bottom) each frame shown changed, by its number, the last few; and the frame each of the desktop's
buffers holds, by its address. A buffer given back holds an older frame: it takes the rows changed since.
- `shownCount`: `i64`
- `buffers`: `_gizlang_sdk_collections.Map<i64, i64>`
- `pressing`: `bool` — Whether the main button is held since a press in a view: a move then drags a field's selection.
- `shownTitle`: `string`
- `schemes`: `gizlang_task.Channel<bool>`

## Functions

### `plain`

```gizlang
function plain(host: Host, app: string): Hooks
```

The hooks of a window that shows one page: its title is the page's.

Effects: fail, alloc.

### `constructor`

```gizlang
constructor(title: string, id: string, width: i64, height: i64) throws string
```

Opens the desktop window with TITLE, application ID and its initial size in pixels.

Effects: fail, read, write, console, io, alloc.

### `keyName`

```gizlang
function keyName(code: i64, text: string): string
```

The DOM name of the key CODE that types TEXT ("" for a key the page is not told of).

Effects: fail, alloc.

### `show`

```gizlang
function show(site: Site, id: string, width: i64, height: i64): i64
```

Shows SITE in a window of W x H, titled by the page, whose desktop entry is ID, until it closes: the front end of an
app run (host.giz run). The code the app gave (close), else 0; 1 when the window cannot open.

Effects: fail, read, write, console, io, alloc.

## Methods

### `Host.view`

```gizlang
view(name: string, socket: string, asides: bool): Renderer
```

A view for this window in a renderer of its own that reaches the app NAME on SOCKET as giz://NAME, its page not
loaded yet. ASIDES: whether the app takes links opened aside (Hooks.aside).

Effects: fail, read, write, io, alloc.

### `Host.add`

```gizlang
add(v: Renderer, top: i64): void
```

Adds V as the layer above the others, TOP pixels below the window's top: an overlay unless it is the first.

Effects: fail, read, write, io, alloc.

### `Host.put`

```gizlang
put(i: i64, v: Renderer): void
```

Puts V in layer I in place of the one there (a tab that comes to the front); the one there stays as it is.

Effects: fail, read, write, io, alloc.

### `Host.fit`

```gizlang
fit(i: i64): void
```

Lays layer I out for the window: the first is opaque, the others overlays; each fills the window below its top.

Effects: fail, read, write, io, alloc.

### `Host.title`

```gizlang
title(text: string): void
```

Sets the window's title to TEXT.

Effects: fail, read, write, console, io, alloc.

### `Host.run`

```gizlang
run(hooks: Hooks): i64 throws string
```

Runs the window until it closes (the desktop's close, a hook, or `close`): the views take input by layer, and the
window is drawn whenever a renderer sent a frame and the desktop has a buffer free. The program's code: the one
`close` gave, else 0.

Effects: fail, read, write, console, io, alloc.

### `Host.draw`

```gizlang
draw(): void
```

Draws every layer, bottom first, each at its top: only the rows that changed since the frame the buffer holds.

Effects: fail, read, write, console, io, alloc.

### `Host.at`

```gizlang
at(x: f64, y: f64): i64
```

The layer that takes a point at window row Y and X: the top one that holds the input (an open popover) or covers
it, else the first; -1 for none.

Effects: fail, read.

### `Host.focused`

```gizlang
focused(): i64
```

The front layer for keys: the top one that holds the input or has a focused field, else the first.

Effects: fail, read.

### `Host.input`

```gizlang
input(e: Win.Input, hooks: Hooks): bool
```

Gives input E to the app's hooks and the views; false when the window is to close.

Effects: fail, read, write, console, io, alloc.

### `Host.method`

```gizlang
method(): void
```

Tells the input method whether the front view edits a field, and where its caret is in the window.

Effects: fail, read, write, console, io, alloc.

