diff options
Diffstat (limited to 'docs/typ')
| -rw-r--r-- | docs/typ/reference.typ | 95 |
1 files changed, 58 insertions, 37 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 4763f36c..22065cd1 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -984,9 +984,13 @@ Exec, a message, a new text pane, its selection) it is handed at load. `paint` is a valid one. In Zig, `src/kinds/addon.zig` (over the same header, and nothing of the core) makes the `pa_ops` from a struct of the functions a kind has (`export const pardes_addon = addon.ops(Snake);`), -with the pane's arena as a `std.mem.Allocator`, typed keys, a window to -`put` text in, a deadline for `tick`, a struct's bytes as its record, and -its own `zig test` (`zig build addon-test` runs them): +wrapping every function of the header and every call of `pa_api`: the +pane's arena and pardes's heap as `std.mem.Allocator`s, typed keys, clicks +and views, a window to `put` text in (column first, where the header's +`pa_put` is row first), a deadline for `tick`, a `prefix` written after +every tick, a struct's bytes as its record, and its own `zig test` (`zig +build addon-test` runs them); a Zig kind outside the tree runs `zig +translate-c src/kinds/pardes_addon.h` once for the header: `addons/snake/snake.zig` is a game in it. Pictures are an addon too, `addons/image/image.zig` (PNG, JPEG, GIF, BMP, PPM, PGM and TGA through stb_image, at most 1280 pixels a side), which `zig build image` @@ -999,26 +1003,35 @@ PDF on a terminal without graphics shows its page's text layer, the moving keys and the wheel a page a step; with them its pages, a fast scroll rendering only the rows each page shows until it rests, a touchpad's turn moving it by its fraction of a row, and the pointer a hand over a link. -The header is ABI 2.2: an addon built against another major is refused, -and an older one runs as it did (2.1 added at the ends of its records: -`heap`, `view`, `exec` and `select` in its `pa_api`, the rail's thumb in -`pa_paint`, its own `search`; 2.2 the core's ABI in `pa_api`, a wheel's -`amount` in `pa_mouse`, `glyphs` in `pa_view`, the `pointer` in -`pa_paint` and PA_FRAMED in tick's flags). +The header is ABI 3.0: an addon built against another major (a 2.x one) +is refused. A kind's state is one thing, stepped by `tick` however many +views (windows and terminals on the session) show it; what each view sees +of it is laid out by `view` and drawn by `paint`. -- `tick(state, now, flags)` returns the absolute time of its next step - (0: none) on a monotonic clock. It is called when that time comes and - once after `open`, a key or click it took, a word, a job's answer, a - `load`, and whenever `PA_FOCUSED` (its pane has the keyboard in some - view, its window focused) changes: a kind that returned 0 is woken by - the next thing that happens to it, and one that steps only while focused - asks for nothing otherwise. `paint` is called once a frame and changes - nothing (a Debug build checks the kind's memory across it). -- The tag of its pane is the prefix its last frame gave (else its kind's - name), then, when that frame placed a picture, the core's own - `petscii:on palette:commodore ascii:off` (#word("Petscii"), - #word("Palette") and #word("Ascii") are the core's words), then its - path. +- `tick(state, t)` steps the state at `t->now` on a monotonic clock, and + sets `t->next`, the absolute time of its next step (0: none), and + `t->prefix`, the start of its pane's tag. It is called when that time + comes and once after `open`, a key or click it took, a word, a job's + answer, a `load`, a `view`, and whenever `PA_FOCUSED` (its pane has the + keyboard in some view, its window focused) changes: a kind that set no + next step is woken by the next thing that happens to it, and one that + steps only while focused asks for nothing otherwise. +- `view(state, v)` is called when a view starts showing the pane, when its + facts change (its cells, a cell's pixels, the theme, whether it shows + pictures as glyph art) and when it stops (`v->cols` 0), `v->id` naming + the view; a kind lays out for it and asks for its rasters there. A key + and a click say the view they came from. `paint` is called once a frame + in each view, `win->view` the one, and changes nothing (a Debug build + checks the kind's memory across it); a picture over 32 MiB is dropped. +- Every call returns within 2 ms; what takes longer goes on a job. A Debug + pardes says a call over 16 ms once (`pdf: search took 118 ms, over 16 + ms`) and `--addon-test` fails on it. +- The tag of its pane is the prefix its last tick set (else its kind's + name), then, for a kind whose head says `PA_PICTURES` (image, PDF), the + core's own `petscii:on palette:commodore ascii:off` from its first frame, + the same in every view (`petscii:on` when #word("Petscii") says so or the + session's first view shows no pictures; #word("Petscii"), + #word("Palette") and #word("Ascii") are the core's words), then its path. - Its jobs run on the host's workers, allocating from what the job is handed (the last allocation the answer); one asked before an #word("Addon") `reload` answers into nothing, and the old library stays @@ -1044,35 +1057,43 @@ and an older one runs as it did (2.1 added at the ends of its records: kind opens a pane of it from anywhere, its argument the path; any other elsewhere is refused. A Look of a file whose extension an addon claims opens a pane of its kind. -- A pane of an addon's kind takes every key but #key("Esc") when its kind - takes keys, as a raw terminal does (#key("Esc") too, first, for a kind - of 2.1: not taken, it leaves), and its clicks when it takes the mouse, +- A pane of an addon's kind takes every key when its kind takes keys, as + a raw terminal does (#key("Esc") first: not taken, it leaves), and its + clicks when it takes the mouse, a press's drag and release wherever they go, and a motion off its body - when the pointer leaves it. `tick` is called again when its view (its - window, a cell's pixels, the theme) changes. A `/` in it asks its kind's - `search`, a `+Search` of its rows; a Look of `file:<place>` (`:<place>` + when the pointer leaves it. A `/` in it asks its kind's `search`, which + returns at once, a `+Search` of the rows it hands `found` (then or later, + from a job); a kind may `cancel` a job whose answer it no longer wants. + A Look of `file:<place>` (`:<place>` in it) is its kind's `address`, a miss said `<path>` and what the kind said (`has no page 99`), one from a list its kind made (`text`) handed with the list's name first (`+PdfSections 3:2`). Its #file("body") is the kind's text, if it has any; its #file("ctl") read ends with the kind's own fields. - A dump keeps each such pane: its kind, version, path and place, and the - kind's own record (a PDF's: its file's bytes, its fit, tint and page). + kind's own record, its small state of at most 1 MiB (a PDF's: its fit, + tint and page; a picture has none), never the file: a Restore reads the + file at its path as a Look does, then hands the kind the record. Restored without its addon, the pane waits in its place saying `addon <name> <version> is not loaded: Addon load <path>`; the addon loaded, it - opens there. One with no record opens from its file, at its place, its - words given again; a PDF pane of a dump made before the PDF addon comes - back so. A pane whose file changes on disk opens again from it, its - record kept for its `load` (a PDF stays on its page). + opens there. Restored without its file, it waits saying `<path> is not + here`, its record kept, and opens at the next Look or watch of the path. + One with no record opens from its file, at its place, its words given + again; a PDF pane of a dump made before the PDF addon comes back so. A + pane whose file changes on disk opens again from it, its record kept for + its `load` (a PDF stays on its page). - An addon runs in pardes's process. A load is marked on disk while it runs; a start that finds the mark of one that never finished skips that library, listed so, until #word("Addon") `load` asks for it again. A crash inside one says `in addon <file>, <call>` in the crash record. - `pardes --addon-test <lib> <script>` runs a script of keys, clicks, words and ticks (its clock starts at 1 s), `focus` and `blur`, `size C - R` (the session's terminal), `dump` (the pane's record, loaded into a - fresh pane), `body` and `ctl` against a pane of its kind and prints the - pane after each, with `window CxR` (the cells it paints) at the start - and after `size`: an addon's test, compared with `diff`. `settle` ticks + R` (the session's terminal), `graphics on|off`, `view N on|off` (into + view N, a second client's, with pictures or not; `size`, `focus` and + `graphics` are the current view's), `dump` (the pane's record, loaded + into a fresh pane), `body` and `ctl` against a pane of its kind and + prints the pane after each, as the current view sees it, with `window + CxR` (the cells it paints) at the start and after `size`: an addon's + test, compared with `diff`. `settle` ticks until the kind asks for no step, and fails for one that asks while idle. `key` sends the rest of its line, its ends trimmed and a space within sent as one, a character a key; `<space>`, `<enter>`, `<tab>`, `<bs>`, |
