summaryrefslogtreecommitdiff
path: root/docs/typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ')
-rw-r--r--docs/typ/reference.typ95
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>`,