GizStack
View .mdOpen in ChatGPTOpen in Claude

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.