# gizlang/window

A window of the desktop: a surface to draw into and the input that comes to it, one interface for every program that shows itself (GizBrowser, the desktop's apps). The program draws a frame into canvas() and shows it with present(); next() gives it its input one at a time (pointer, wheel, keys, a new size, a close) and waits for it with a timeout, so a program can do other work (a picture that comes) between inputs. copy() and paste() use the desktop's clipboard; cursor() sets the pointer's shape over the window by its CSS name; typing() tells the input method where the program edits text, and the method's text comes as COMPOSE and COMMIT inputs. Window is the one interface; a backend serves it on each system. On GizOS and on Linux it is a Wayland client (gizlang/wayland): two frames in shared memory, each busy until the compositor releases it. On Windows it is Win32 (below): a thread of its own pumps the window's messages, and a frame is drawn with SetDIBitsToDevice. macOS has no backend: open throws there.

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

## Types

### `Input`

```gizlang
type Input = { kind: i64; x: f64; y: f64; button: i64; key: i64; text: string; dx: f64; dy: f64; width: i64; height: i64; modifiers: i64; }
```

One input: its kind, the pointer's position in window pixels, the button, the key and its text, the wheel's
pixels, the window's size (RESIZE) and the modifiers held.

- `kind`: `i64`
- `x`: `f64`
- `y`: `f64`
- `button`: `i64`
- `key`: `i64`
- `text`: `string`
- `dx`: `f64`
- `dy`: `f64`
- `width`: `i64`
- `height`: `i64`
- `modifiers`: `i64`

### `Layout`

```gizlang
type Layout = { name: string; keys: string; shifted: string; }
```

A keyboard layout: its XKB name, and its printing keys from evdev code 2 to 53, unshifted and shifted (a space is a
key that types none: Backspace, Tab, Enter, Ctrl, Shift). A dead key types its own mark.

- `name`: `string`
- `keys`: `string`
- `shifted`: `string`

### `Window`

```gizlang
class Window { wayland: Option<Wayland> = undefined; win32: Option<Win32> = undefined; constructor() {} next(ms: i64): Option<Input> throws string { const w = this.win32; if (w !== undefined) { return w!.next(ms); } return this.wayland!.next(ms); } canvas(): Option<Canvas> { const w = this.win32; if (w !== undefined) { return w!.canvas(); } return this.wayland!.canvas(); } present(damage: Vec<i64>): void throws string { const w = this.win32; if (w !== undefined) { w!.present(damage); return; } this.wayland!.present(damage); } title(text: string): void throws string { const w = this.win32; if (w !== undefined) { w!.title(text); return; } this.wayland!.title(text); } copy(text: string): void throws string { const w = this.win32; if (w !== undefined) { w!.copy(text); return; } this.wayland!.copy(text); } paste(): string throws string { const w = this.win32; if (w !== undefined) { return w!.paste(); } return this.wayland!.paste(); } typing(on: bool, x: i64, y: i64, w: i64, h: i64): void throws string { const win = this.win32; if (win !== undefined) { win!.typing(on, x, y, w, h); return; } this.wayland!.typing(on, x, y, w, h); } cursor(name: string): void throws string { const shape = CURSORS.indexOf(name) + 1; const win = this.win32; if (win !== undefined) { win!.cursor(shape); return; } this.wayland!.cursor(shape); } close(): void { const w = this.win32; if (w !== undefined) { w!.close(); return; } this.wayland!.close(); } waker(): () => void { const w = this.win32; if (w !== undefined) { return w!.waker(); } return this.wayland!.waker(); } }
```

A window on the desktop: one interface over each system's backend (open picks it).

- `wayland`: `_gizlang_sdk_core.Option<Ref<gizlang_window.Wayland>>`
- `win32`: `_gizlang_sdk_core.Option<Ref<gizlang_window.Win32>>`

## Functions

### `layout`

```gizlang
function layout(name: string): Layout
```

The layout NAME, or US for any other name.

Effects: fail, alloc.

### `keyText`

```gizlang
function keyText(code: i64, shift: bool, caps: bool, on: Layout = LAYOUTS[0]): string
```

The text the key CODE types on LAYOUT, with SHIFT (and CAPS for letters); "" when it types none.

Effects: fail, alloc.

### `constructor`

```gizlang
constructor()
```

A window with no backend yet: open gives it one.

Effects: fail, write, alloc.

### `constructor`

```gizlang
constructor(c: Client, width: i64, height: i64, scratch: i64)
```

A window on the connection C, of WIDTH x HEIGHT, with SCRATCH (128 bytes: the window's polls, then its waiter
thread's; then CHUNK bytes for the clipboard's pipes); open() makes one.

Effects: fail, read, write, alloc.

### `open`

```gizlang
function open(environment: (name: string) => Option<string>, title: string, app: string, width: i64, height: i64): Window throws string
```

Opens a window of WIDTH x HEIGHT named TITLE, of the program APP (its desktop file's name): on WAYLAND_SOCKET when
the desktop gave one, else on $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY. It shows once the desktop configures it (the first
RESIZE input). The backend is the Wayland client on Linux and on GizOS (whose uname says GizOS), and Win32
on Windows (APP is unused there); on another system it throws before any system call, so a program there runs
without windows (GizBrowser's command line draws PNGs).
ENVIRONMENT reads the variables: SYS's, or a test's own.

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

### `followScheme`

```gizlang
function followScheme(wake: () => void): Channel<bool>
```

The desktop's colour scheme as it is and as it changes: a task on the session bus reads the portal's color-scheme,
then each SettingChanged of it, and sends whether it prefers dark to the channel it returns, calling WAKE after each
(a window's waker). With no session bus or portal (macOS, Windows, a bare Linux) nothing comes: the scheme stays
light.

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

### `constructor`

```gizlang
constructor(nat: Native, asks: Channel<Win32Ask>, answers: Channel<Win32Answer>, failures: Channel<string>, askEvent: u64, wakeEvent: u64, setEvent: u64, width: i64, height: i64)
```

The program's side of a Win32 window whose thread NAT runs: the channels and events it talks to that thread with.

Effects: fail, read, write, alloc.

## Methods

### `Window.next`

```gizlang
next(ms: i64): Option<Input> throws string
```

Waits at most MS ms (-1: until one comes) for the next input; none when the time passed first or the waker was
called. A lost connection throws.

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

### `Window.canvas`

```gizlang
canvas(): Option<Canvas>
```

A frame of the window's size to draw the next picture into; none while the backend cannot take one yet (both
of Wayland's frames on the screen, or before the window is configured).

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

### `Window.present`

```gizlang
present(damage: Vec<i64>): void throws string
```

Shows the frame canvas() gave; DAMAGE is the changed part [x, y, w, h] (empty: all of it).

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

### `Window.title`

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

Names the window TEXT in the desktop's title bar and task list.

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

### `Window.copy`

```gizlang
copy(text: string): void throws string
```

Puts TEXT on the desktop's clipboard.

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

### `Window.paste`

```gizlang
paste(): string throws string
```

The text on the desktop's clipboard ("" when none).

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

### `Window.typing`

```gizlang
typing(on: bool, x: i64, y: i64, w: i64, h: i64): void throws string
```

Tells the input method whether the program edits text (ON) and where its caret is (X, Y, W, H).

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

### `Window.cursor`

```gizlang
cursor(name: string): void throws string
```

Shows the pointer over the window as the CSS cursor NAME ("default", "pointer", "text", ...); another name shows
the arrow.

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

### `Window.close`

```gizlang
close(): void
```

Closes the window; it is not used after.

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

### `Window.waker`

```gizlang
waker(): () => void
```

A function another task may call to end the window's wait at once (next gives none): how a host learns that
work it waits for, such as a page's document, is done, without polling.

Effects: fail, read, write, alloc.

## Constants

### `CLOSE`

```gizlang
const CLOSE = 1
```

The kinds of input.

### `RESIZE`

```gizlang
const RESIZE = 2
```

The window has a new size (width, height): the next canvas() has it.

### `MOVE`

```gizlang
const MOVE = 3
```

The pointer moved to (x, y).

### `PRESS`

```gizlang
const PRESS = 4
```

A button was pressed at (x, y).

### `RELEASE`

```gizlang
const RELEASE = 5
```

A button was released at (x, y).

### `WHEEL`

```gizlang
const WHEEL = 6
```

A turn of the wheel: dy pixels down (negative: up), dx pixels right.

### `KEY`

```gizlang
const KEY = 7
```

A key pressed (also each repeat of a held key): key is its code, text what it types ("" for none).

### `LEAVE`

```gizlang
const LEAVE = 8
```

The pointer left the window.

### `COMPOSE`

```gizlang
const COMPOSE = 9
```

The input method changed the text it is composing (text; "" when it ends without a commit).

### `COMMIT`

```gizlang
const COMMIT = 10
```

The input method typed text.

### `SHIFT`

```gizlang
const SHIFT = 1
```

The modifier bits of an input.

### `CONTROL`

```gizlang
const CONTROL = 2
```

The Control key is held.

### `ALT`

```gizlang
const ALT = 4
```

The Alt key is held.

### `BUTTON_LEFT`

```gizlang
const BUTTON_LEFT = 0x110
```

The pointer's buttons.

### `BUTTON_RIGHT`

```gizlang
const BUTTON_RIGHT = 0x111
```

The right button.

### `BUTTON_MIDDLE`

```gizlang
const BUTTON_MIDDLE = 0x112
```

The middle button (the wheel).

### `BUTTON_BACK`

```gizlang
const BUTTON_BACK = 0x113
```

The side button that goes back.

### `BUTTON_FORWARD`

```gizlang
const BUTTON_FORWARD = 0x114
```

The side button that goes forward.

### `KEY_ESCAPE`

```gizlang
const KEY_ESCAPE = 1
```

The codes of the keys a program acts on (Linux input codes, the same on every backend).

### `KEY_BACKSPACE`

```gizlang
const KEY_BACKSPACE = 14
```

The backspace key.

### `KEY_TAB`

```gizlang
const KEY_TAB = 15
```

The tab key.

### `KEY_ENTER`

```gizlang
const KEY_ENTER = 28
```

The enter key.

### `KEY_SPACE`

```gizlang
const KEY_SPACE = 57
```

The space key.

### `KEY_F5`

```gizlang
const KEY_F5 = 63
```

The f5 key.

### `KEY_HOME`

```gizlang
const KEY_HOME = 102
```

The home key.

### `KEY_UP`

```gizlang
const KEY_UP = 103
```

The up key.

### `KEY_PAGE_UP`

```gizlang
const KEY_PAGE_UP = 104
```

The page up key.

### `KEY_LEFT`

```gizlang
const KEY_LEFT = 105
```

The left key.

### `KEY_RIGHT`

```gizlang
const KEY_RIGHT = 106
```

The right key.

### `KEY_END`

```gizlang
const KEY_END = 107
```

The end key.

### `KEY_DOWN`

```gizlang
const KEY_DOWN = 108
```

The down key.

### `KEY_PAGE_DOWN`

```gizlang
const KEY_PAGE_DOWN = 109
```

The page down key.

### `KEY_DELETE`

```gizlang
const KEY_DELETE = 111
```

The delete key.

### `LAYOUTS`

```gizlang
const LAYOUTS: Vec<Layout> = [{ name: "us", keys: "1234567890-=  qwertyuiop[]  asdfghjkl;'` \\zxcvbnm,./", shifted: "!@#$%^&*()_+  QWERTYUIOP{}  ASDFGHJKL:\"~ |ZXCVBNM<>?" }, { name: "de", keys: "1234567890ß´  qwertzuiopü+  asdfghjklöä^ #yxcvbnm,.-", shifted: "!\"§$%&/()=?`  QWERTZUIOPÜ*  ASDFGHJKLÖÄ° 'YXCVBNM;:_" }, { name: "fr", keys: "&é\"'(-è_çà)=  azertyuiop^$  qsdfghjklmù² *wxcvbn,;:!", shifted: "1234567890°+  AZERTYUIOP¨£  QSDFGHJKLM%  µWXCVBN?./§" }, { name: "es", keys: "1234567890'¡  qwertyuiop`+  asdfghjklñ´º çzxcvbnm,.-", shifted: "!\"·$%&/()=?¿  QWERTYUIOP^*  ASDFGHJKLÑ¨ª ÇZXCVBNM;:_" }]
```

The layouts a window types by: the one its desktop's keymap names (xkb_symbols "pc+de+..."), else US.

