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.
import * as Window from "gizlang/window";Types
Input
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:i64x:f64y:f64button:i64key:i64text:stringdx:f64dy:f64width:i64height:i64modifiers:i64
Layout
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:stringkeys:stringshifted:string
Window
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
function layout(name: string): LayoutThe layout NAME, or US for any other name.
Effects: fail, alloc.
keyText
function keyText(code: i64, shift: bool, caps: bool, on: Layout = LAYOUTS[0]): stringThe text the key CODE types on LAYOUT, with SHIFT (and CAPS for letters); "" when it types none.
Effects: fail, alloc.
constructor
constructor()A window with no backend yet: open gives it one.
Effects: fail, write, alloc.
constructor
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
function open(environment: (name: string) => Option<string>, title: string, app: string, width: i64, height: i64): Window throws stringOpens 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
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
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
next(ms: i64): Option<Input> throws stringWaits 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
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
present(damage: Vec<i64>): void throws stringShows 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
title(text: string): void throws stringNames the window TEXT in the desktop's title bar and task list.
Effects: fail, read, write, io, alloc.
Window.copy
copy(text: string): void throws stringPuts TEXT on the desktop's clipboard.
Effects: fail, read, write, io, alloc.
Window.paste
paste(): string throws stringThe text on the desktop's clipboard ("" when none).
Effects: fail, read, write, io, alloc.
Window.typing
typing(on: bool, x: i64, y: i64, w: i64, h: i64): void throws stringTells 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
cursor(name: string): void throws stringShows 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
close(): voidCloses the window; it is not used after.
Effects: fail, read, write, io, alloc.
Window.waker
waker(): () => voidA 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
const CLOSE = 1The kinds of input.
RESIZE
const RESIZE = 2The window has a new size (width, height): the next canvas() has it.
MOVE
const MOVE = 3The pointer moved to (x, y).
PRESS
const PRESS = 4A button was pressed at (x, y).
RELEASE
const RELEASE = 5A button was released at (x, y).
WHEEL
const WHEEL = 6A turn of the wheel: dy pixels down (negative: up), dx pixels right.
KEY
const KEY = 7A key pressed (also each repeat of a held key): key is its code, text what it types ("" for none).
LEAVE
const LEAVE = 8The pointer left the window.
COMPOSE
const COMPOSE = 9The input method changed the text it is composing (text; "" when it ends without a commit).
COMMIT
const COMMIT = 10The input method typed text.
SHIFT
const SHIFT = 1The modifier bits of an input.
CONTROL
const CONTROL = 2The Control key is held.
ALT
const ALT = 4The Alt key is held.
BUTTON_LEFT
const BUTTON_LEFT = 0x110The pointer's buttons.
BUTTON_RIGHT
const BUTTON_RIGHT = 0x111The right button.
BUTTON_MIDDLE
const BUTTON_MIDDLE = 0x112The middle button (the wheel).
BUTTON_BACK
const BUTTON_BACK = 0x113The side button that goes back.
BUTTON_FORWARD
const BUTTON_FORWARD = 0x114The side button that goes forward.
KEY_ESCAPE
const KEY_ESCAPE = 1The codes of the keys a program acts on (Linux input codes, the same on every backend).
KEY_BACKSPACE
const KEY_BACKSPACE = 14The backspace key.
KEY_TAB
const KEY_TAB = 15The tab key.
KEY_ENTER
const KEY_ENTER = 28The enter key.
KEY_SPACE
const KEY_SPACE = 57The space key.
KEY_F5
const KEY_F5 = 63The f5 key.
KEY_HOME
const KEY_HOME = 102The home key.
KEY_UP
const KEY_UP = 103The up key.
KEY_PAGE_UP
const KEY_PAGE_UP = 104The page up key.
KEY_LEFT
const KEY_LEFT = 105The left key.
KEY_RIGHT
const KEY_RIGHT = 106The right key.
KEY_END
const KEY_END = 107The end key.
KEY_DOWN
const KEY_DOWN = 108The down key.
KEY_PAGE_DOWN
const KEY_PAGE_DOWN = 109The page down key.
KEY_DELETE
const KEY_DELETE = 111The delete key.
LAYOUTS
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.