Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-slate

bm-ext MIT

Slate for php-baremetal: a retained-mode 2D scene graph and compositor for display panels, with a software graphics layer. Platform-neutral.

IDE stubs @ 1.3.0

The PHP declarations of the functions, classes and constants this package adds, with their docblocks, so PhpStorm and Intelephense can complete and type-check your firmware code.

You don't need to download them: on every composer install and composer update, conductor copies them into vendor/php-baremetal/ide-stubs/, which IDEs index without configuration. They are never loaded at runtime.

php ide/ext-slate.stub
<?php
// php-baremetal/ext-slate 1.3.0 — IDE helper, not loaded at runtime.

namespace Baremetal\Slate {
    /**
     * Draws scenes on a display panel and keeps them up to date: only what changed is composed again, band by
     * band, at the panel's pace. One Slate runs at a time; it takes the panel from the display object (its
     * drawing methods throw until the Slate goes) and gives it back when it is destroyed.
     *
     * Changes to elements are collected while PHP runs and handed to the compositor when the script returns to
     * the event loop (after each listener, or after each loop()), when show() is called, and by commit(): the
     * changes of one listener appear together, in the same frame.
     */
    final class Slate
    {
        /**
         * How many scenes left keep their caches (cached groups, shadows, blurs) for a return to them; 0: a scene
         * left drops them, as in 1.1. Past it, the oldest scene left drops them at once (also when it is lowered).
         * The caches stay in Slate's cache budget in PSRAM: when the shown scene needs room there, the scenes left
         * drop theirs first, oldest first.
         *
         * @throws \ValueError When negative ("keepScenes must be 0 or more"); the old value stays.
         */
        public int $keepScenes = 2;

        /**
         * A limit in KB for the caches of the scenes left; past it the oldest drops them at once (0: none is kept).
         * null: only Slate's cache budget limits them.
         *
         * @throws \ValueError When negative ("keptBudget must be 0 or more"); the old value stays.
         */
        public ?int $keptBudget = null;

        /**
         * The theme of the controls: a Theme with the default tokens until theme() sets another one. Read it to draw
         * the rest of the screen with the same colours. Not built without slate-controls.
         */
        public readonly Theme $theme;

        /**
         * Takes the panel of $display and starts the compositor; with $touch, Slate routes its touch events to
         * the elements of the scene shown (see Touch) and the rest to Scene::onTouch().
         *
         * @param \Baremetal\Output\Display $display A display whose driver has the band path.
         * @param \Baremetal\Input\Touch|null $touch The touch device of the same screen, or null.
         * @throws \LogicException When another Slate runs, the panel has no band path ("Slate: <Class> has no band
         *     path") or another renderer holds it.
         * @throws \RuntimeException When the compositor cannot start (memory for its buffers, or its task).
         */
        public function __construct(\Baremetal\Output\Display $display, ?\Baremetal\Input\Touch $touch = null) {}

        /**
         * A Slate on the board's own display (and touch screen, when the board has one): among the loaded driver
         * classes, the one display driver (and touch driver) with a static onboard() method is used.
         *
         * @throws \LogicException When the board has no display block, or no driver or several drivers with
         *     onboard() are loaded: build it with new Slate($display, $touch) then.
         */
        public static function onboard(): Slate {}

        /**
         * Shows a scene. build() runs the first time the scene is shown.
         *
         * Without $t the change is instant: onLeave() of the scene shown until now, then onEnter() of the new one.
         *
         * With $t the new scene slides or fades in: its onEnter() runs at once (its elements are ready and its
         * tweens start), and at the end onLeave() of the old scene runs and TransitionDone is raised. Meanwhile
         * scene() is the new scene, both scenes' tweens run, and the touch reaches neither. From no scene shown
         * (the first show()) the new scene comes in over the black background, with no TransitionDone.
         *
         * show() of the scene shown (also the one a transition goes to) does nothing. show() during a transition
         * ends it first: onLeave() of the scene it leaves runs now (its TransitionDone follows), then the new
         * change starts from the scene it went to, whole.
         *
         * The change is sent to the compositor at once.
         *
         * @throws \RuntimeException When the compositor has failed (the panel stopped answering) or is out of
         *     memory.
         */
        public function show(Scene $s, ?Transition $t = null): void {}

        /**
         * The scene shown now (during a transition: the scene it goes to), or null before the first show().
         */
        public function scene(): ?Scene {}

        /**
         * Sends the changes made so far to the compositor now. Needed only by a script that never returns to an
         * event loop (a script without listeners or loop()).
         *
         * @throws \RuntimeException When the compositor has failed.
         */
        public function commit(): void {}

        /**
         * Sets the theme of the controls, before the first show(). A control reads the theme when it is made: set the
         * theme first, right after new Slate(). Not built without slate-controls.
         *
         * @throws \Error After the first show() ("the theme is set before the first show()").
         */
        public function theme(Theme $theme): static {}

        /**
         * Shows a toast: a pill above everything (the scene, its dialogs, a transition: it does not move with the
         * scenes), 48 px high with a radius of 24, surface with a 1 px border in borderStrong and a shadow (when
         * shadows are built), an accent dot of 8 px and $text in the theme's font and text colour; centred, its bottom
         * edge at 1/6 of the screen's height from the bottom. It rises 14 px while it fades in (300 ms), stays $ms,
         * fades out in 300 ms, then goes. A new toast replaces the one shown at once. It takes no touch. The theme is
         * read at the call. Keep it short: the pill is at most the screen's width - 64 and a longer text is cut. Not
         * built without slate-controls.
         *
         * @param int $ms How long it stays, between the fade in and the fade out, in ms (at least 500).
         * @throws \ValueError When $ms is less than 500 ("Baremetal\Slate\Slate::toast(): ms must be at least 500").
         */
        public function toast(string $text, int $ms = 2500): static {}
    }

    /**
     * A screen of the application. Extend it: add the components in build(), react in onEnter(), onLeave(),
     * onTouch() and in your own methods and listeners. A plain Scene works too: (new Scene())->add(...).
     */
    class Scene
    {
        /**
         * Whether the scene's caches stay when it is left, for a quick return (within Slate::$keepScenes and
         * Slate::$keptBudget). Set it to false in a scene shown once (a splash): its caches go when it is left.
         */
        protected bool $keepCache = true;

        /**
         * Adds elements on top of the scene's elements (the last one added is drawn on top).
         *
         * @throws \LogicException When an element already belongs to a group or a scene.
         */
        public function add(Element ...$e): static {}

        /**
         * Takes elements out of the scene; they stay usable and can be added again.
         */
        public function remove(Element ...$e): static {}

        /**
         * Opens a dialog above the scene: above all its elements and the dialogs open already. The scrim fades in to
         * black at 88 % and the panel rises 14 px while it fades in, element by element, in 300 ms (its shadow is built
         * first, before the animation starts). The dialog stays with the scene: when
         * another scene is shown it stays open, and shows again when the scene comes back. While dialogs are open,
         * add() keeps them on top of what it adds; remove() of an open dialog closes it at once (onClose() and
         * closed() still run). The touch under way ends: the element or Scroll that holds the finger gets Cancel, a
         * touch of the scene reaches onTouch() no more. Not built without slate-controls.
         *
         * @throws \Error When the dialog is open (in this scene or another one, also while it closes) or belongs to
         *     a group ("Baremetal\Slate\Dialog is already open", with the class of a subclass).
         */
        public function open(Dialog $d): static {}

        /**
         * Builds the scene's components; called once, before the scene is shown the first time.
         */
        protected function build(): void {}

        /**
         * Called each time the scene is shown (with a transition: when it starts).
         */
        public function onEnter(): void {}

        /**
         * Called when another scene replaces this one (with a transition: when it ends, or when a show() during it
         * ends it).
         */
        public function onLeave(): void {}

        /**
         * Called with the raw touch events (Pressed, Moved, Released, Gesture) of the Slate's touch device while this
         * scene is shown, for the touches whose Pressed hit no touchable element (the background; a Scroll is
         * touchable by default; a scene without touchable elements gets them all), the Gesture of such a touch
         * included (also when it comes after the Released). Not during a transition.
         */
        public function onTouch(\Baremetal\Input\TouchEvent $e): void {}
    }

    /**
     * The base of the elements. Properties are read and written as usual (not by reference); a write of a wrong
     * value throws \ValueError naming the property and its limit, and the old value stays.
     *
     * Colors: 0xRRGGBB is opaque, 0xAARRGGBB with AA from 01 to FF translucent; 0x00RRGGBB is opaque too, so a
     * transparent fill or border is null. A component of your own extends Group, not Element.
     */
    abstract class Element
    {
        /** Horizontal position, relative to the parent group (pixels; fractions are drawn anti-aliased). */
        public int|float $x;

        /** Vertical position, relative to the parent group. */
        public int|float $y;

        /** false hides the element (and, for a group, its children). */
        public bool $visible;

        /** 0 (transparent) to 1 (opaque); a group's opacity applies to the group as a whole. */
        public float $opacity;

        /**
         * Whether the element takes touches: the finger on its area (its box on the screen, for a group with its
         * children, grown by $hitPad, cut by the clip of its ancestors) gives it Press, Move, Release, Tap, Hold and
         * Cancel (the methods onPress()..onCancel() and the callbacks of on()). An element with a callback takes
         * touches also while this is false. Declare it `public bool $touchable = true;` in a component of your own.
         */
        public bool $touchable = false;

        /**
         * Pixels added to the touch area on every side, 0 to 64 (a small target made easier to hit). A default
         * of a subclass out of range is not checked: the nearest limit is used.
         *
         * @throws \ValueError When out of range ("Baremetal\Slate\<Class>::$hitPad must be between 0 and 64").
         */
        public int $hitPad = 0;

        /**
         * Milliseconds the finger stays down (within 8 px) before Hold, 0 to 10000; 0: never a Hold. A default
         * of a subclass out of range is not checked: the nearest limit is used.
         *
         * @throws \ValueError When out of range ("Baremetal\Slate\<Class>::$holdMs must be between 0 and 10000").
         */
        public int $holdMs = 500;

        /**
         * Sets several properties at once, by name: $el->set(x: 10, opacity: 0.5).
         *
         * @throws \ValueError When a value is out of range.
         * @throws \Error When a name is not a property.
         */
        public function set(mixed ...$props): static {}

        /**
         * Animates properties from their values on the screen to the ones given, in the compositor, at the
         * panel's pace: ['x' => 200, 'opacity' => 0.5]. The properties read their final values at once. All of them
         * share the time and the curve, and make one Tween; TweenDone follows when it ends by itself. A new
         * animate() of a property that is already moving takes it over from where it is.
         *
         * Animatable: x, y and opacity of every element; Group (and a Control of your own) w, h, blur; Slate's
         * controls blur; RoundRect w, h, radius, border, fill,
         * borderColor; Circle r, border, fill, borderColor; Arc r, from, to, width, color; Line x1, y1, width,
         * color; Text color. Colours move channel by channel; gradients and null (no fill, no border) are not
         * animated.
         *
         * Like every tween of an element that is not shown, the tween of an element Slate has not drawn yet (made
         * in build(), or before add()) waits, and starts when the element is shown. A tween of an element with
         * $visible = false, or inside a group with $visible = false, waits too (its time stopped, its TweenDone and
         * the tweens chained after it too) and goes on from where it was when the element is visible again; only
         * $visible counts (a fade-in from $opacity 0 runs).
         *
         * @param array<string, int|float|null> $props Property => final value, as a write of the property takes it.
         * @param int $ms One run, in milliseconds (at least 1).
         * @param int $delay Milliseconds before the first run.
         * @param int $repeat Runs after the first; -1: forever (never done).
         * @param bool $yoyo The repeats go back and forth (an odd repeat ends where it started).
         * @throws \ValueError When a property is not animatable ("Baremetal\Slate\<Class>::$<name> cannot be
         *     animated"), is a gradient or null now or as the target ("... cannot be animated: it is a gradient",
         *     "... cannot be animated: it is null"), a value is
         *     out of range, $props is empty, ms < 1 ("ms must be at least 1"), delay < 0 or repeat < -1 ("repeat must
         *     be -1 or more"). Nothing changes then.
         */
        public function animate(array $props, int $ms = 300, Ease $ease = Ease::OutCubic, int $delay = 0,
                                int $repeat = 0, bool $yoyo = false): Tween {}

        /**
         * From now on, every write of these properties slides to its value in $ms instead of jumping (from where
         * the property is on the screen). ease([]) makes them jump again. No TweenDone for these moves.
         *
         * @param list<string> $props Names of animatable properties (see animate()).
         * @throws \ValueError When a property is not animatable, or ms < 1.
         */
        public function ease(array $props, int $ms = 300, Ease $ease = Ease::OutCubic): static {}

        /**
         * Sets the callback of one kind of touch (one per kind: a new one replaces the old one). The element takes
         * touches while it has a callback, also with $touchable false. With a method and a callback, the method runs
         * first.
         *
         * @param \Closure(Touch): void $fn
         */
        public function on(TouchType $type, \Closure $fn): static {}

        /**
         * Removes the callback of one kind of touch (nothing when there is none).
         */
        public function off(TouchType $type): static {}

        /**
         * The finger came down on the element: from now on the touch is the element's (it captures it). Overriding
         * these methods does not make the element take touches: set $touchable (or a callback with on()) as well.
         */
        public function onPress(Touch $t): void {}

        /** The finger moved, anywhere on the screen. */
        public function onMove(Touch $t): void {}

        /** The finger came up, anywhere on the screen. */
        public function onRelease(Touch $t): void {}

        /**
         * After onRelease(), when the finger stayed within 8 px of the press, no Hold came and it came up on the area
         * (decided at the release: removing the element in onRelease() does not stop it).
         */
        public function onTap(Touch $t): void {}

        /** The finger stayed down $holdMs milliseconds without moving past 8 px (once; no Tap after it). */
        public function onHold(Touch $t): void {}

        /**
         * The touch ended without Release or Tap: the element (or an ancestor) was removed or hidden, the element
         * stopped taking touches, another scene was shown or a transition started.
         */
        public function onCancel(Touch $t): void {}
    }

    /**
     * The kinds of a touch on an element.
     */
    enum TouchType
    {
        case Press;
        case Move;
        case Release;
        case Tap;
        case Hold;
        case Cancel;
    }

    /**
     * A touch on an element, given to its methods onPress()..onCancel() and to its callbacks.
     */
    final class Touch
    {
        public readonly TouchType $type;

        /** The element that has the touch. */
        public readonly Element $element;

        /** The finger on the screen, in pixels. */
        public readonly int $x;

        public readonly int $y;

        /** The finger from the element's (x, y) on the screen (with the positions of the Scrolls it is in). */
        public readonly int $localX;

        public readonly int $localY;

        /**
         * When, as \Baremetal\Event::$time: nanoseconds on the base of hrtime(true), an int where PHP integers are
         * 64-bit, a float where they are 32-bit. The $time of the touch event; for Hold the press time plus $holdMs;
         * for Cancel the time of the last event.
         */
        public readonly int|float $time;

        /** Made by Slate only. */
        private function __construct() {}
    }

    /**
     * @internal Slate's own: a timer of Slate came due (the Hold of a touch, the end of a control's animation). Slate
     * handles it; it has no use for a listener.
     */
    final class HoldDue extends \Baremetal\Event
    {
    }

    /**
     * A group of elements, whose positions are relative to the group's (x, y). With clip, the children are cut to
     * the box (0, 0, w, h); with cache, the group is kept as an image and redrawn only when something inside it
     * changes; blur (in pixels, as CSS blur) and shadow make it cached as well. Extend it to build a component of
     * your own.
     */
    class Group extends Element
    {
        /** The clip box's width (for clip). */
        public int|float $w;

        /** The clip box's height (for clip). */
        public int|float $h;

        /** Cut the children to the box (0, 0, w, h); needs w and h greater than 0. */
        public bool $clip;

        /** Keep the group as an image (in PSRAM) and redraw it only when its content changes. */
        public bool $cache;

        /** Blur of the group, in pixels (how far the softness reaches); 0: none. */
        public int $blur;

        /** A drop shadow of the group's content, or null. */
        public ?Shadow $shadow;

        /**
         * @throws \ValueError When a value is out of range, clip without a box, or blur > 0 when the blur effect
         *     is not built in.
         */
        public function __construct(int|float $x = 0, int|float $y = 0, int|float $w = 0, int|float $h = 0,
                                    float $opacity = 1.0, bool $clip = false, bool $cache = false, int $blur = 0,
                                    ?Shadow $shadow = null) {}

        /**
         * Adds elements on top of the group's children.
         *
         * @throws \LogicException When an element already belongs to a group, or would contain itself.
         */
        public function add(Element ...$e): static {}

        /**
         * Takes elements out of the group; they stay usable.
         */
        public function remove(Element ...$e): static {}
    }

    /**
     * A view (0, 0, w, h), always clipped, over its children, the content: they are placed in content coordinates
     * and drawn shifted by the scroll position. The finger drags the content (the scroll takes the touches by itself:
     * $touchable is true; touch() routes them by hand), a release flings it on with inertia, past an edge it
     * stretches and springs back, and it can snap to steps; bars show the position while it moves. The compositor
     * runs all of it at the pace of the panel; PHP is told when a motion ends (ScrollEnded). Extend it to build a
     * list of your own.
     *
     * $w and $h (inherited) are the view, 1..32767; $clip is always true (writing false throws \ValueError
     * "Baremetal\Slate\Scroll::$clip is always true"); $cache keeps the whole content as one image.
     */
    class Scroll extends Group
    {
        /**
         * The scroll takes the touches that hit it (its view, where no touchable child is on top) and, past 8 px on
         * an axis it can move, the ones of its touchable children (they get Cancel); a press while it moves stops it
         * (the element under the finger gets nothing). Nested scrolls: the innermost that can move that way. Those
         * touches no longer reach Scene::onTouch(). false: it takes none (route them by hand with touch()).
         */
        public bool $touchable = true;

        /** The content's width, 0..32767; 0: the box of the children from (0, 0), kept up to date. */
        public int $contentW;

        /** The content's height, 0..32767; 0: the box of the children from (0, 0), kept up to date. */
        public int $contentH;

        /** The axes the content moves on. */
        public ScrollAxis $axis;

        /** Past an edge the content stretches and springs back; false: it stops at the edge. */
        public bool $bounce;

        /**
         * Snap step on x in pixels (the content comes to rest on a multiple of it, or on the end),
         * 0..32767; 0: none.
         */
        public int $snapX;

        /** Snap step on y in pixels, 0..32767; 0: none. */
        public int $snapY;

        /**
         * At most this many snap steps per release, counted in the direction of the fling from the snap point at or
         * behind the release position (never back against the fling; under 20 px/s the nearest point), 0..32767;
         * 0: no limit. Per axis, only on an axis with a snap step: 1 makes a carousel move one card per fling,
         * however fast. Not animatable.
         */
        public int $snapMax;

        /** Bars that show the position while the content moves, then fade. */
        public bool $indicators;

        /**
         * The position on x: read, the one last drawn (after a write, the value written until it is drawn); written,
         * the content jumps there (kept within the limits, no error) and any motion stops.
         */
        public int|float $scrollX;

        /** The position on y (as $scrollX). */
        public int|float $scrollY;

        /**
         * @throws \ValueError When a value is out of range ("Baremetal\Slate\Scroll::$w must be between 1 and
         *     32767", "...::$snapY must be between 0 and 32767", ...).
         */
        public function __construct(int|float $x = 0, int|float $y = 0, int|float $w = 1, int|float $h = 1,
                                    ScrollAxis $axis = ScrollAxis::Both, bool $bounce = true, int $snapX = 0,
                                    int $snapY = 0, int $snapMax = 0, bool $indicators = true, int $contentW = 0,
                                    int $contentH = 0, float $opacity = 1.0, bool $cache = false) {}

        /**
         * Gives the scroll a touch event by hand (usually from Scene::onTouch(), for a scroll with $touchable false,
         * or for a touch that hit nothing). While the scroll has a touch of its own ($touchable), touch() does
         * nothing and returns false: no touch is fed twice. True when the touch belongs to the scroll:
         * a Moved past 8 px from the press (on the axis allowed; with Both, the distance) and the ones after it, the
         * Released that ends a drag (the content flings on); and a catch: a Pressed inside the view while the content
         * moves (it stops there), with every Moved and the Released of that touch (never a tap; a drag may still
         * start from it). False for a Pressed outside the view, a Pressed at rest, a Moved under 8 px and a Released
         * without a drag (a tap), a Gesture, and for a scroll that is not in the scene shown. The view is the part on
         * the screen (cut by the scrolls and clipping groups it is in). A touch that is the scroll's stays so to its
         * end, also when a write of the position, scrollTo(), a new set-up or leaving the screen ends its drag (from
         * then on nothing is sent for it).
         *
         * @throws \TypeError When $e is not a TouchEvent.
         */
        public function touch(\Baremetal\Input\TouchEvent $e): bool {}

        /**
         * Moves the content to ($x, $y), kept within the limits, in $ms milliseconds along $ease; the Tween ends with
         * its TweenDone and the scroll's ScrollEnded. $ms 0 (or a scroll not drawn yet): it jumps there, the Tween is
         * done at once. A press, a write of $scrollX/$scrollY or a change of $axis, $bounce or the snap steps stops
         * it (no TweenDone).
         *
         * @throws \ValueError When $x or $y is not finite ("Baremetal\Slate\Scroll::$scrollX must be a finite
         *     number"), $ms < 0 ("ms must be 0 or more") or past 2147483647.
         */
        public function scrollTo(int|float $x, int|float $y, int $ms = 300, Ease $ease = Ease::OutCubic): Tween {}
    }

    /**
     * The axes a Scroll moves on.
     */
    enum ScrollAxis
    {
        case Both;
        case Vertical;
        case Horizontal;
    }

    /**
     * The content of a Scroll came to rest after a release (inertia, snap, spring) or at the end of a scrollTo()
     * (which also gives its TweenDone). Once per motion; never while the finger holds the content.
     */
    final class ScrollEnded extends \Baremetal\Event
    {
        /** The scroll. */
        public readonly Scroll $scroll;

        /** Its position, in whole pixels. */
        public readonly int $x;

        public readonly int $y;
    }

    /**
     * A rectangle with rounded corners (radius 0: square corners), filled and optionally bordered.
     */
    final class RoundRect extends Element
    {
        public int|float $w;
        public int|float $h;

        /** Corner radius, at most half the shorter side. */
        public int|float $radius;

        /** 0xRRGGBB, 0xAARRGGBB, a gradient, or null (no fill). */
        public int|float|Gradient|null $fill;

        /** Border width, drawn inside the outline; 0: none. */
        public int|float $border;

        /** Border color, or null (no border). */
        public int|float|null $borderColor;

        /** A drop shadow, or null. */
        public ?Shadow $shadow;

        public function __construct(int|float $x, int|float $y, int|float $w, int|float $h, int|float $radius = 0,
                                    int|float|Gradient|null $fill = null, int|float $border = 0,
                                    int|float|null $borderColor = null, ?Shadow $shadow = null) {}
    }

    /**
     * A disc; $x and $y are its centre (the constructor's $cx and $cy).
     */
    final class Circle extends Element
    {
        public int|float $r;

        /** 0xRRGGBB, 0xAARRGGBB, a gradient, or null (no fill). */
        public int|float|Gradient|null $fill;

        public int|float $border;
        public int|float|null $borderColor;
        public ?Shadow $shadow;

        public function __construct(int|float $cx, int|float $cy, int|float $r, int|float|Gradient|null $fill = null,
                                    int|float $border = 0, int|float|null $borderColor = null,
                                    ?Shadow $shadow = null) {}
    }

    /**
     * A stroke along a circle, from $from to $to degrees (0 = 3 o'clock, clockwise); $x and $y are its centre.
     * For progress bars and gauges.
     */
    final class Arc extends Element
    {
        public int|float $r;
        public int|float $from;
        public int|float $to;

        /** Stroke width. */
        public int|float $width;

        /** 0xRRGGBB, 0xAARRGGBB or a gradient. */
        public int|float|Gradient $color;

        public Caps $caps;

        public function __construct(int|float $cx, int|float $cy, int|float $r, int|float $from, int|float $to,
                                    int|float $width, int|float|Gradient $color, Caps $caps = Caps::Round) {}
    }

    /**
     * A segment from ($x, $y) (the constructor's $x0, $y0) to ($x1, $y1), relative to the parent.
     */
    final class Line extends Element
    {
        public int|float $x1;
        public int|float $y1;
        public int|float $width;

        /** 0xRRGGBB or 0xAARRGGBB. */
        public int|float $color;

        public Caps $caps;

        public function __construct(int|float $x0, int|float $y0, int|float $x1, int|float $y1, int|float $width = 1,
                                    int|float $color = 0xFFFFFF, Caps $caps = Caps::Butt) {}
    }

    /**
     * One line of text in a font of the firmware; ($x, $y) is the top of the line, at its left end, centre or
     * right end depending on $align.
     */
    final class Text extends Element
    {
        public string $text;

        /** The name of a font of the firmware (extra.baremetal.fonts). */
        public string $font;

        /** 0xRRGGBB or 0xAARRGGBB. */
        public int|float $color;

        public Align $align;

        /** Cut the text to this many pixels (no ellipsis); 0: no limit. */
        public int $maxWidth;

        /**
         * @throws \ValueError When the font is not in the firmware.
         */
        public function __construct(int|float $x, int|float $y, string $text, string $font = 'default',
                                    int|float $color = 0xFFFFFF, Align $align = Align::Left, int $maxWidth = 0) {}
    }

    /**
     * Pixels of your own: draw with the primitives below (colors 0xRRGGBB), then call dirty() to show what
     * changed.
     */
    final class Canvas extends Element
    {
        /** Width in pixels (1 to 1024); a new size clears the canvas. */
        public int $w;

        /** Height in pixels (1 to 1024). */
        public int $h;

        public function __construct(int|float $x, int|float $y, int $w, int $h) {}

        /** Fills the canvas with one color. */
        public function clear(int $color = 0): void {}

        public function pixel(int $x, int $y, int $color): void {}

        public function line(int $x0, int $y0, int $x1, int $y1, int $color): void {}

        public function rect(int $x, int $y, int $w, int $h, int $color): void {}

        public function fillRect(int $x, int $y, int $w, int $h, int $color): void {}

        public function circle(int $cx, int $cy, int $r, int $color): void {}

        public function fillCircle(int $cx, int $cy, int $r, int $color): void {}

        /**
         * One line of text, ($x, $y) the top of the line; $bg null keeps what is under the text.
         *
         * @return int The width of the text in pixels.
         */
        public function text(int $x, int $y, string $s, int $color, ?int $bg = null, string $font = 'default'): int {}

        /**
         * Sends what was drawn since the last dirty() to the screen (at the next frame).
         */
        public function dirty(): void {}
    }

    /**
     * An image from a file: a .sli (converted by phpbm from the project's PNG assets: the fast path) or a .png
     * decoded on the board (needs png in slate-images). The image is loaded in the background as soon as the
     * Image is made or $src changes; until then the element draws nothing. Images are shared by path: Images of
     * the same file use one copy, loaded once; it stays in memory while an Image or a Preload holds it.
     *
     * $w, $h and $loaded change when ImageLoaded is delivered (or in wait()). A file that cannot be loaded raises
     * ImageFailed and the element stays empty.
     */
    final class Image extends Element
    {
        /**
         * The file: an absolute path ending in .sli or .png (in any case), e.g. '/app/assets/ui/bg.sli' for an
         * asset in flash or '/sdcard/assets/photos/beans.sli' for one on the microSD card. A new path loads that
         * image (at once when it is in memory already).
         */
        public string $src;

        /** The image's width in pixels; 0 until it is loaded (or when it failed). */
        public readonly int $w;

        /** The image's height in pixels; 0 until it is loaded (or when it failed). */
        public readonly int $h;

        /** true once the image is loaded. */
        public readonly bool $loaded;

        /**
         * @throws \RuntimeException When there is no memory even for the image's record ("Slate: no memory for the
         *     image <path>"), or when the table of ext-events' idle hooks is full ("Slate: cannot load images: the
         *     table of ext-events' idle hooks is full").
         * @throws \Exception In the web-server runtime (from ext-events: images raise events).
         * @throws \ValueError When $src is not an absolute path ("Baremetal\Slate\Image::$src must be an absolute
         *     path"), does not end in .sli or .png ("Baremetal\Slate\Image::$src must end in .sli or .png"), is a
         *     .png while png is not built ("png is not built in: add it to slate-images in composer.json"), or
         *     $opacity is out of 0..1.
         */
        public function __construct(int|float $x, int|float $y, string $src, float $opacity = 1.0) {}

        /**
         * Waits until the image is loaded, at most $timeout_ms milliseconds; no other event is delivered
         * meanwhile. $w, $h and $loaded are updated.
         *
         * @return bool true when the image is loaded; false on timeout or when it failed.
         * @throws \ValueError When $timeout_ms is negative.
         */
        public function wait(int $timeout_ms = 5000): bool {}
    }

    /**
     * Images loaded ahead of time: the next page's images, so that its Image elements are ready at once.
     */
    final class Images
    {
        private function __construct() {}

        /**
         * Starts loading every path (the ones in memory already are counted at once) and keeps the images in
         * memory while the returned Preload lives. PreloadProgress follows each image loaded, PreloadDone the
         * last one finished (also when every image was in memory already): exactly one per Preload.
         *
         * @param list<string> $paths Absolute paths ending in .sli or .png.
         * @throws \ValueError When a path is not absolute, does not end in .sli or .png, or is a .png while png is
         *     not built.
         * @throws \TypeError When an entry is not a string.
         * @throws \RuntimeException When there is no memory even for an image's record, or when the table of
         *     ext-events' idle hooks is full ("Slate: cannot load images: the table of ext-events' idle hooks is
         *     full").
         * @throws \Exception In the web-server runtime (from ext-events: images raise events).
         */
        public static function preload(array $paths): Preload {}
    }

    /**
     * The images of Images::preload(), held in memory while this object lives. Its properties change when the
     * events are delivered (or in wait()).
     */
    final class Preload
    {
        /** The images loaded so far. */
        public readonly int $loaded;

        /** The number of paths. */
        public readonly int $total;

        /** true when every image is loaded or failed. */
        public readonly bool $done;

        private function __construct() {}

        /**
         * Waits until no image is still loading, at most $timeout_ms milliseconds; no other event is delivered
         * meanwhile.
         *
         * @return bool true when every image is loaded; false on timeout or when one failed.
         * @throws \ValueError When $timeout_ms is negative.
         */
        public function wait(int $timeout_ms = 5000): bool {}
    }

    /**
     * An image finished loading (once per file, however many Image elements show it).
     */
    final class ImageLoaded extends \Baremetal\Event
    {
        /** The path, as given to Image or Images::preload(). */
        public readonly string $path;

        public readonly int $w;
        public readonly int $h;
    }

    /**
     * An image could not be loaded; the elements that show it stay empty. A later Image or $src of the same path
     * tries again.
     */
    final class ImageFailed extends \Baremetal\Event
    {
        public readonly string $path;
        public readonly ImageError $error;

        /** What went wrong, in words. */
        public readonly string $message;
    }

    /**
     * One more image of a Preload is loaded.
     */
    final class PreloadProgress extends \Baremetal\Event
    {
        /** Images of the Preload loaded so far. */
        public readonly int $loaded;

        public readonly int $total;
    }

    /**
     * Every image of a Preload is loaded or failed.
     */
    final class PreloadDone extends \Baremetal\Event
    {
        /** @var list<string> The paths that could not be loaded (empty when all were). */
        public readonly array $failed;
    }

    /**
     * An animation of Element::animate() or Tween::then(). The element is held while it runs.
     */
    final class Tween
    {
        /**
         * true once it ended by itself (after all its repeats); set when its TweenDone is delivered, or by wait().
         * Never for repeat -1; not after stop(), unless it ended in the very frame the stop reached the compositor.
         */
        public readonly bool $done;

        private function __construct() {}

        /**
         * Stops it, and the tweens chained after it with then(), without TweenDone. The properties stay where they
         * are on the screen (they still read the final values: write them to move them); with $toEnd they go to
         * their final values.
         *
         * @throws \RuntimeException When the compositor failed.
         */
        public function stop(bool $toEnd = false): void {}

        /**
         * Waits until it ends, at most $timeout_ms milliseconds; the pending changes are handed to the compositor
         * first, no event is delivered meanwhile. Returns false at once for a stopped tween and for repeat -1.
         *
         * @return bool true when it ended by itself.
         * @throws \ValueError When $timeout_ms is negative.
         */
        public function wait(int $timeout_ms = 5000): bool {}

        /**
         * A tween of $e that starts when this one ends (after the ones already chained after it), from the values
         * on the screen then; at once when this one has ended or stopped. stop() of the first stops the chain.
         *
         * @param array<string, int|float|null> $props As for Element::animate().
         * @throws \ValueError As Element::animate().
         */
        public function then(Element $e, array $props, int $ms = 300, Ease $ease = Ease::OutCubic): Tween {}
    }

    /**
     * A tween ended by itself (once per Tween; never for repeat -1; not after stop(), unless it ended in the very
     * frame the stop reached the compositor).
     */
    final class TweenDone extends \Baremetal\Event
    {
        public readonly Tween $tween;
    }

    /**
     * The easing curves of animations (the standard Penner curves). OutBack goes past the end and comes back,
     * OutBounce bounces at the end, OutElastic oscillates around it.
     */
    enum Ease
    {
        case Linear;
        case InQuad;
        case OutQuad;
        case InOutQuad;
        case InCubic;
        case OutCubic;
        case InOutCubic;
        case OutBack;
        case OutBounce;
        case OutElastic;
    }

    /**
     * How Slate::show() changes the scene: the old and the new one are composed together, band by band, for $ms
     * milliseconds along the $ease curve.
     */
    final class Transition
    {
        private function __construct() {}

        /**
         * The new scene appears over the old one, its opacity from 0 to 1.
         *
         * @throws \ValueError When $ms is below 1 (ms must be at least 1) or above 2147483647.
         */
        public static function fade(int $ms = 300, Ease $ease = Ease::OutCubic): Transition {}

        /**
         * The new scene comes in from the side opposite to $d and pushes the old one out towards $d.
         *
         * @throws \ValueError As fade().
         */
        public static function push(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic): Transition {}

        /**
         * The new scene slides in towards $d over the old one, which stays still.
         *
         * @throws \ValueError As fade().
         */
        public static function cover(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic): Transition {}

        /**
         * The old scene slides away towards $d and uncovers the new one, which stays still.
         *
         * @throws \ValueError As fade().
         */
        public static function uncover(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic): Transition {}
    }

    /**
     * The direction a transition moves in.
     */
    enum Direction
    {
        case Left;
        case Right;
        case Up;
        case Down;
    }

    /**
     * A transition of Slate::show() ended (also when a show() during it ended it): onLeave() of $from has run.
     * None for a transition from no scene (the first show()).
     */
    final class TransitionDone extends \Baremetal\Event
    {
        /** The scene left. */
        public readonly Scene $from;

        /** The scene shown. */
        public readonly Scene $to;
    }

    /**
     * Why an image could not be loaded.
     */
    enum ImageError: string
    {
        /** No such file. */
        case NotFound = 'not-found';

        /** The file could not be read. */
        case Unreadable = 'unreadable';

        /** Not a valid .sli or PNG: a damaged or truncated file, or another format under that name. */
        case BadFormat = 'bad-format';

        /** A valid PNG that is not decoded on the board (16 bits per channel, interlaced): convert it with phpbm. */
        case Unsupported = 'unsupported';

        /** Not enough memory for the image. */
        case NoMemory = 'no-memory';
    }

    /**
     * The ends of an Arc or a Line.
     */
    enum Caps: string
    {
        /** Square ends, at the end points. */
        case Butt = 'butt';

        /** Rounded ends, half a disc past the end points. */
        case Round = 'round';
    }

    /**
     * What a Text's x is: its left end, its centre or its right end.
     */
    enum Align: string
    {
        case Left = 'left';
        case Center = 'center';
        case Right = 'right';
    }

    /**
     * A gradient fill: LinearGradient or RadialGradient. Needs the gradients effect (slate-effects).
     */
    abstract class Gradient
    {
        /** The stops as given: [[position 0..1, color], ...] or [[position, color, alpha 0..1], ...]. */
        public readonly array $stops;
    }

    /**
     * A linear gradient across the element's box.
     */
    final class LinearGradient extends Gradient
    {
        /** Direction in degrees: 0 left to right, 90 top to bottom. */
        public readonly float $angle;

        /**
         * @param array $stops 2 to 16 stops [position 0..1, color 0xRRGGBB or 0xAARRGGBB] or [position, color,
         *     alpha 0.0..1.0] (the alpha replaces the color's: [1.0, 0xFFFFFF, 0.0] is transparent).
         * @throws \ValueError When the gradients effect is not built in, or a stop is wrong.
         */
        public function __construct(array $stops, float $angle = 0.0) {}
    }

    /**
     * A radial gradient: centre ($cx, $cy) and radius $r as fractions of the element's box.
     */
    final class RadialGradient extends Gradient
    {
        public readonly float $cx;
        public readonly float $cy;
        public readonly float $r;

        /**
         * @param array $stops 2 to 16 stops [position 0..1, color 0xRRGGBB or 0xAARRGGBB] or [position, color,
         *     alpha 0.0..1.0] (the alpha replaces the color's: [1.0, 0xFFFFFF, 0.0] is transparent).
         * @throws \ValueError When the gradients effect is not built in, or a value is wrong.
         */
        public function __construct(array $stops, float $cx = 0.5, float $cy = 0.5, float $r = 0.5) {}
    }

    /**
     * A drop shadow: offset ($dx, $dy), blur in pixels (how far the softness reaches, as in CSS) and color
     * (usually translucent, e.g. 0x80000000). Needs the shadows effect (slate-effects).
     */
    final class Shadow
    {
        public readonly int $dx;
        public readonly int $dy;
        public readonly int $blur;
        public readonly int|float $color;

        /**
         * @throws \ValueError When the shadows effect is not built in, or a value is out of range.
         */
        public function __construct(int $dx, int $dy, int $blur, int|float $color) {}
    }

    /**
     * The look of the controls: colours, the radius of Shape::Rounded, the heights of the three sizes and the fonts.
     * Pass the tokens by name; the ones left out keep the default (a neutral dark theme):
     * new Theme(accent: 0xFFB347, radius: 14, font: 'dejavu-sans-16').
     *
     * Colours are 0xRRGGBB. Fonts are names of the firmware's fonts (extra.baremetal.fonts), as Text::$font:
     * 'default', the font-dejavu package's 'dejavu-sans-12', 'dejavu-sans-16', 'dejavu-sans-24', and the fonts the
     * project bakes. Not built without slate-controls.
     */
    final class Theme
    {
        /** The scene's background (Slate does not paint the scene: use it for a full-screen RoundRect). */
        public readonly int $bg;

        /** Panels: a dialog, a toast, raised rows. */
        public readonly int $surface;

        /** A Secondary button, a chip not chosen. */
        public readonly int $raised;

        /** Recesses: the track of a segmented control, the empty part of a slider. */
        public readonly int $well;

        /** Borders and dividers. */
        public readonly int $border;

        /** The border of a Secondary button. */
        public readonly int $borderStrong;

        /** The main text. */
        public readonly int $text;

        /** Secondary text, Ghost buttons, subtitles. */
        public readonly int $textMuted;

        /** Dimmed text. */
        public readonly int $textDim;

        /** The accent: a Primary button, an Outline button. */
        public readonly int $accent;

        /** Text on the accent and on danger. */
        public readonly int $onAccent;

        /** A Danger button. */
        public readonly int $danger;

        /** An informative colour, for the application's own use. */
        public readonly int $info;

        /** Done steps. */
        public readonly int $success;

        /** The radius of Shape::Rounded, 0..64. */
        public readonly int $radius;

        /** The height of Size::Small, 24..128. */
        public readonly int $small;

        /** The height of Size::Medium, 24..128. */
        public readonly int $medium;

        /** The height of Size::Large, 24..128. */
        public readonly int $large;

        /** The text of the controls. */
        public readonly string $font;

        /** Subtitles and small labels. */
        public readonly string $fontSmall;

        /** Titles (a dialog's). */
        public readonly string $fontTitle;

        /** Values (a setting row's, a slider's). */
        public readonly string $fontMono;

        /** A large number (the centre of a progress ring). */
        public readonly string $fontDisplay;

        /**
         * @throws \ValueError For the first token out of range: a colour outside 0..0xFFFFFF
         *     ("Baremetal\Slate\Theme::$<token> must be a color, 0xRRGGBB"), $radius outside 0..64
         *     ("Baremetal\Slate\Theme::$radius must be between 0 and 64"), a height outside 24..128
         *     ("Baremetal\Slate\Theme::$<small|medium|large> must be between 24 and 128"), a font the firmware does not
         *     have ("Baremetal\Slate\Theme::$<font...> must be a font of the firmware: unknown font '<name>'
         *     (available: <names>)").
         */
        public function __construct(int $bg = 0x0F1115, int $surface = 0x161A20, int $raised = 0x1C2129,
                                    int $well = 0x111419, int $border = 0x262C35, int $borderStrong = 0x343B46,
                                    int $text = 0xE8EAED, int $textMuted = 0xA0A7B2, int $textDim = 0x5C6370,
                                    int $accent = 0x4C8DFF, int $onAccent = 0xFFFFFF, int $danger = 0xFF5D5D,
                                    int $info = 0x5CC8FF, int $success = 0x4ADE80, int $radius = 12, int $small = 40,
                                    int $medium = 48, int $large = 56, string $font = 'default',
                                    string $fontSmall = 'default', string $fontTitle = 'default',
                                    string $fontMono = 'default', string $fontDisplay = 'default') {}
    }

    /**
     * The size of a control: its height comes from the theme ($small, $medium, $large).
     */
    enum Size
    {
        case Small;
        case Medium;
        case Large;
    }

    /**
     * The colours of a Button.
     */
    enum Variant
    {
        /** Fill accent, text onAccent. */
        case Primary;

        /** Fill raised, a 1 px border borderStrong, text text. */
        case Secondary;

        /** No fill, text textMuted. */
        case Ghost;

        /** Fill danger, text onAccent. */
        case Danger;

        /** No fill, a 1 px border accent at 60 %, text accent. */
        case Outline;
    }

    /**
     * The corners of a control: Pill rounds them by half the height, Rounded by the theme's $radius.
     */
    enum Shape
    {
        case Pill;
        case Rounded;
    }

    /**
     * How a Choice shows its options.
     */
    enum ChoiceStyle
    {
        case Segmented;
        case Chips;
        case List;
        case Nav;
    }

    /**
     * The base of the controls. A control is one PHP object; its parts (a background, a text, an icon...) live in
     * the compositor without a PHP object each, and the control takes the touch as a whole (its area is the union of
     * its parts). It needs a running Slate when it is made, and reads the Slate's theme then.
     *
     * $enabled false draws the control at 0.4 times its $opacity (which keeps the value written) and stops it taking
     * new touches; a touch under way gets Cancel.
     *
     * Slate's controls show a pressed look from Press to Release or Cancel (their fill 12 % toward white, in 80 ms);
     * they notify onChange() and the callback of changed() for the user's gestures only: a change made by the code
     * (a write of a property) is drawn but not notified.
     *
     * A control of your own extends Control directly, builds its parts with add() (RoundRect, Text, Image...), draws
     * them with $this->theme, calls notify() for the user's gestures and overrides pressed() for its pressed look:
     *
     *     final class Beans extends Control {
     *         public function __construct(int $x, int $y) {
     *             parent::__construct($x, $y);
     *             // add() the parts, with $this->theme's colours
     *         }
     *         public function onTap(Touch $t): void { $this->notify(intdiv($t->localX, 16) + 1); }
     *         protected function pressed(bool $down): void { $this->opacity = $down ? 0.8 : 1.0; }
     *     }
     *
     * Not built without slate-controls.
     */
    abstract class Control extends Group
    {
        /** A control takes touches by default. */
        public bool $touchable = true;

        /** false: drawn at 0.4 times $opacity, no new touch (a touch under way gets Cancel). */
        public bool $enabled = true;

        /** The running Slate's theme when the control was made. */
        protected readonly Theme $theme;

        /**
         * @throws \Error Without a running Slate ("<Class> needs a running Slate: create the Slate before its
         *     controls").
         */
        public function __construct(int|float $x = 0, int|float $y = 0) {}

        /**
         * The value changed by the user's gesture (empty here: override it). Runs before the callback of changed().
         */
        public function onChange(mixed $value): void {}

        /**
         * The callback of the user's changes (one: a new one replaces it; null removes it). It runs after onChange().
         *
         * @param (\Closure(mixed): void)|null $fn
         */
        public function changed(?\Closure $fn): static {}

        /**
         * Notifies a change made by the user: onChange($value), then the callback of changed(). An exception stops
         * there.
         */
        protected function notify(mixed $value): void {}

        /**
         * true at Press, false at Release and Cancel (also when $enabled turns false during the touch). Empty here:
         * a control of your own overrides it for its pressed look.
         */
        protected function pressed(bool $down): void {}

        /**
         * Adds parts to a control of your own (a class that extends Control directly).
         *
         * @throws \Error On Slate's controls ("<Class>: a control builds its own parts").
         * @throws \LogicException When an element already belongs to a group, or would contain itself.
         */
        public function add(Element ...$e): static {}

        /**
         * Takes parts out of a control of your own.
         *
         * @throws \Error On Slate's controls ("<Class>: a control builds its own parts").
         */
        public function remove(Element ...$e): static {}
    }

    /**
     * A push button: a text, an optional icon on its left, the colours of its variant. Its action is onTap() (or
     * on(TouchType::Tap, ...)); it notifies no onChange().
     *
     * $w and $h (inherited) read the size laid out: $h from the theme ($size), $w the one given or, with w 0, the text
     * plus a padding on each side (16, 20, 24 px for Small, Medium, Large) plus 20 + 8 px for the icon. No text and an
     * icon: a square. Writing $w or $h throws \Error ("Cannot modify Baremetal\Slate\Button::$w: the size of a control
     * comes from its constructor and the theme").
     *
     * The icon is an image file (as Image::$src), 20 x 20 px, drawn monochrome in the text colour: only its alpha
     * counts. It loads as an Image does; an icon that does not load stays empty (ImageFailed with its path).
     */
    class Button extends Control
    {
        /** The text; a write lays the button out again (with w 0, its width). */
        public string $text;

        /** The colours. */
        public Variant $variant;

        /** The fill, 0xRRGGBB, in place of the variant's; null: the variant's. */
        public ?int $fill = null;

        /** The colour of the text and of the icon, 0xRRGGBB; null: the variant's. */
        public ?int $color = null;

        /**
         * @param int $w The width; 0: from the content.
         * @param string|null $icon An absolute path ending in .sli or .png, e.g. '/app/assets/icons/back.sli'.
         * @throws \Error Without a running Slate ("Baremetal\Slate\Button needs a running Slate: create the Slate
         *     before its controls").
         * @throws \ValueError When $w is outside 0..32767 ("Baremetal\Slate\Button::$w must be between 0 and
         *     32767"), $icon is not an absolute path ending in .sli or .png ("Baremetal\Slate\Button::$icon must be
         *     an absolute path ending in .sli or .png") or is a .png while png is not built ("png is not built in:
         *     add it to slate-images in composer.json"); a write of $fill or $color outside 0..0xFFFFFF
         *     ("Baremetal\Slate\Button::$fill must be a color, 0xRRGGBB").
         */
        public function __construct(int|float $x, int|float $y, string $text, Variant $variant = Variant::Secondary,
                                    Size $size = Size::Medium, int $w = 0, Shape $shape = Shape::Rounded,
                                    ?string $icon = null) {}

        /** The pressed look (call it from an override to keep it). */
        protected function pressed(bool $down): void {}
    }

    /**
     * An on/off switch: a track and a round knob. Small 52 x 30 with a knob of 24, Medium 62 x 36 / 28, Large 72 x 42
     * / 34, the knob 4 px from the ends. On: the track accent, the knob bg; off: the track borderStrong, the knob
     * textMuted; pressed: the track 12 % toward white. A tap inverts $on (knob and colours slide in 250 ms), then
     * onChange(bool $on) and the callback of changed() run. $w and $h (inherited) read the size and cannot be written.
     */
    class Toggle extends Control
    {
        /** The state; a write from the code slides the toggle over, without onChange(). */
        public bool $on = false;

        /** 8 by default: the toggle takes a touch up to 8 px around its track. */
        public int $hitPad = 8;

        /**
         * @throws \Error Without a running Slate ("Baremetal\Slate\Toggle needs a running Slate: create the Slate
         *     before its controls").
         */
        public function __construct(int|float $x, int|float $y, bool $on = false, Size $size = Size::Medium) {}

        /** The pressed look (call it from an override to keep it). */
        protected function pressed(bool $down): void {}
    }

    /**
     * A value picked along a track: an area as high as the size ($small, $medium, $large of the theme) and $w wide, a
     * track 8 px high (well) filled up to the value (accent, or $fill), a knob of 24, 30 or 34 px (Small, Medium,
     * Large) in text with a border of 5 px (accent, or $fill). The knob's centre runs from knob / 2 to $w - knob / 2;
     * w 0 is allowed (no track, only the knob). $w and $h (inherited) read the size and cannot be written.
     *
     * The touch: a press moves the knob under the finger (on the step), then it follows the finger, also outside the
     * area. onChange($value) runs only once the finger is past 8 px from the press and the touch is still the
     * slider's, or at the release; at most once per frame of the compositor (a value held back goes out at a later
     * move after a frame, or at the release) and only when the value changed. At the release: the value not notified
     * yet, then onCommit($value) and the callback of committed(), always (also with the value of before the press).
     *
     * In a vertical Scroll: a horizontal drag stays the slider's; a vertical one goes to the Scroll at 8 px. The
     * slider then gets Cancel and goes back to the value of before the press, with no onChange() and no onCommit().
     * Another Cancel ($enabled false, another scene shown) does the same before any onChange() of the touch; after
     * the drag has notified, the value stays: a value held back goes out, then onCommit() and committed() run, as at
     * a release. A $value written by the code during the touch takes the place of the value of before the press.
     *
     * $value (and what onChange() and onCommit() receive) is an int when $min, $max and $step are all int, a float
     * otherwise. A write of $value, $min, $max or $step brings $value into the range and onto the step (the last step
     * at or below $max), without onChange().
     */
    class Slider extends Control
    {
        /** The value. */
        public int|float $value;

        /** The lower end of the range, less than $max. */
        public int|float $min;

        /** The upper end of the range. */
        public int|float $max;

        /** The step: the values are $min + k * $step. Greater than 0. */
        public int|float $step;

        /** The colour of the fill and of the knob's border, 0xRRGGBB; null: accent. */
        public ?int $fill = null;

        /**
         * @param int $w The length of the area; 0: only the knob.
         * @throws \Error Without a running Slate ("Baremetal\Slate\Slider needs a running Slate: create the Slate
         *     before its controls").
         * @throws \ValueError When $w is outside 0..32767 ("Baremetal\Slate\Slider::$w must be between 0 and
         *     32767"), $min, $max, $value or $step is not finite ("Baremetal\Slate\Slider::$value must be a finite
         *     number"), $min is not less than $max ("Baremetal\Slate\Slider::$min must be less than $max") or
         *     $step is 0 or less ("Baremetal\Slate\Slider::$step must be greater than 0"); the same on a write
         *     (the old value stays), and a write of $fill outside 0..0xFFFFFF ("Baremetal\Slate\Slider::$fill must
         *     be a color, 0xRRGGBB").
         */
        public function __construct(int|float $x, int|float $y, int $w, int|float $min = 0, int|float $max = 100,
                                    int|float $value = 0, int|float $step = 1, Size $size = Size::Medium) {}

        /** The value at the release of a touch (always, also when it did not change). Empty: override it. */
        public function onCommit(int|float $value): void {}

        /**
         * The callback of the release (one; a new one replaces it, null removes it). It runs after onCommit(), with
         * the value.
         */
        public function committed(?\Closure $fn): static {}
    }

    /**
     * One or more items picked among labels, in four styles (ChoiceStyle). Every item is as high as the size
     * ($small, $medium, $large of the theme); its colours (fill, border, text and icon) slide in 200 ms.
     *
     * - Segmented: a well container (fill well, a 1 px border in border, radius the theme's + 4) with a padding of 4
     *   and equal segments inside it (h - 8 high, the theme's radius). With w 0 each segment is as wide as the
     *   widest label plus 2 paddings (16, 20, 24 for Small, Medium, Large; + 28 with icons); with w > 0 the segments
     *   share w - 8 (the remainder to the first ones). Selected: accent and onAccent; the others transparent and
     *   textMuted.
     * - Chips: separate pills, 8 px apart, each as wide as its label plus 2 paddings (+ 28 with icons). With w 0 they
     *   stay on one row; with w > 0 a chip that does not fit goes to the next row (rows 8 px apart). Selected: accent
     *   and onAccent; the others raised, a 1 px border in border, textMuted.
     * - List: rows w wide (w is required), one under the other, the label on the left. Selected: accent at 12 % with
     *   a 1 px border of accent at 35 %, text accent; the others transparent and textMuted.
     * - Nav: w (required) split in equal parts, an icon (24 x 24, required: one per label) above a label in
     *   fontSmall, at least 5 px below the top. Selected: accent and an accent bar 3 px high at the top of the part
     *   (inset 32 % each side), which slides to the selected part; the others textDim. Small and Medium are tight for
     *   a bottom navigation: use Size::Large (or a theme with a taller $large).
     *
     * $icons: empty, or one path per label (as Image::$src, e.g. '/app/assets/icons/home.sli'). The icons are
     * monochrome: drawn in the item's text colour (20 x 20 left of the label for Segmented, Chips and List).
     *
     * The touch: the item under the finger takes the pressed look in 80 ms (an opaque fill 12 % toward white; a fill
     * that is not opaque gets the text colour at 6 % laid over it); a tap on it selects it. In Segmented, List and
     * Nav a touch outside the items (the well's padding, a larger $hitPad) goes to the nearest item. Without $multi, $selected is an int and a tap on another
     * item selects it and calls onChange(int $index), then the callback of changed(); a tap on the selected item does
     * nothing. With $multi, $selected is the sorted list of the selected indexes and each tap turns an item on or
     * off, then onChange(array $selected) runs. A write of $selected from the code slides the colours and calls no
     * onChange(). $w and $h (inherited) read the size and cannot be written.
     *
     * The content is not clipped to $w (a chip wider than w, a label wider than its segment or part). At most 41
     * items with icons, 63 without (127 parts per control).
     */
    class Choice extends Control
    {
        /**
         * The selected index (int) or, with $multi, the sorted list of the selected indexes (an int written to a
         * multi choice becomes a list of one). A write slides the colours, without onChange().
         * @var int|int[]
         */
        public int|array $selected;

        /**
         * @param string[] $labels The items' labels: a non-empty list of strings.
         * @param int|int[] $selected The selected index; with $multi a list of indexes (an int i is [i]).
         * @param int $w The width; 0: from the labels (Segmented, Chips). Required for List and Nav.
         * @param bool $multi Each tap turns an item on or off; $selected is a list. Without $selected item 0 starts
         *     on: pass [] to start with none.
         * @param string[] $icons Empty, or one absolute path ending in .sli or .png per label (required for Nav).
         * @throws \Error Without a running Slate ("Baremetal\Slate\Choice needs a running Slate: create the Slate
         *     before its controls"); more items than the parts allow ("Baremetal\Slate\Choice: too many parts").
         * @throws \ValueError When $labels is not a non-empty list of strings ("Baremetal\Slate\Choice::$labels
         *     must be a non-empty list of strings"); $selected is outside the labels ("Baremetal\Slate\Choice::
         *     $selected must be between 0 and <n-1>", with $multi "... must be a list of indexes between 0 and
         *     <n-1>"), also on a write (the old value stays); $icons is neither empty nor one per label
         *     ("Baremetal\Slate\Choice::$icons must be empty or hold one path per label"); $w is outside 0..32767
         *     ("Baremetal\Slate\Choice::$w must be between 0 and 32767"); List or Nav with w 0
         *     ("Baremetal\Slate\Choice: the List and Nav styles need w greater than 0"); Nav without icons
         *     ("Baremetal\Slate\Choice: the Nav style needs an icon per label"); an icon that is not an absolute
         *     path ending in .sli or .png ("Baremetal\Slate\Choice::$icons must hold absolute paths ending in .sli
         *     or .png") or a .png while png is not built ("png is not built in: add it to slate-images in
         *     composer.json").
         */
        public function __construct(int|float $x, int|float $y, array $labels, int|array $selected = 0,
                                    ChoiceStyle $style = ChoiceStyle::Segmented, int $w = 0,
                                    Size $size = Size::Medium, bool $multi = false, array $icons = []) {}

        /** The pressed look (call it from an override to keep it). */
        protected function pressed(bool $down): void {}
    }

    /**
     * A row of a settings list, $w wide: the label on the left (font, text) with $sub under it (fontSmall, textMuted),
     * $value right-aligned at the right edge (fontMono, textMuted), $control at the right (left of the value, 12 px
     * apart) and centred in the height, and a 1 px divider in border at the bottom. The height is 60 (72 with a
     * subtitle), at least the control's height + 16. The texts and the control are centred in it.
     *
     * The control is any element (a Toggle, a Button, a Slider, a Choice, an Image...): it becomes a child of the row
     * (it must not belong to a group), gets its own touches and is placed by the row (its $x and $y are written). A
     * Slider made with w 0 is stretched instead: its track fills the space between the label (at most 40 % of $w) and
     * the value, 12 px from each.
     *
     * The row itself is not touchable by default (a touch outside the control reaches what is under the row): with
     * $touchable = true, or a callback of on(), it takes the touch, with a pressed look (the text colour at 4 %) and
     * onTap(). $w and $h (inherited) read the size and cannot be written; add() and remove() throw.
     */
    class SettingRow extends Control
    {
        /** The label; a write redraws the row and places the control again. */
        public string $label;

        /** The subtitle under the label ('': none, the row 60 high); a write redraws the row. */
        public string $sub;

        /** The value shown at the right ('': none); a write redraws the row and places the control again. */
        public string $value;

        /** false by default: only the control takes the touch. */
        public bool $touchable = false;

        /**
         * @param int $w The width, 1..32767.
         * @param Element|null $control The control at the right (a child of the row), or null.
         * @throws \Error Without a running Slate ("Baremetal\Slate\SettingRow needs a running Slate: create the
         *     Slate before its controls").
         * @throws \ValueError When $w is outside 1..32767 ("Baremetal\Slate\SettingRow::$w must be between 1 and
         *     32767").
         * @throws \LogicException When $control already belongs to a group or a scene.
         */
        public function __construct(int|float $x, int|float $y, int $w, string $label, string $sub = '',
                                    ?Element $control = null, string $value = '') {}

        /** The pressed look (call it from an override to keep it). */
        protected function pressed(bool $down): void {}
    }

    /**
     * A modal dialog, opened above a scene with Scene::open() and closed with close(). A scrim covers the screen in
     * black at 88 % and takes every touch (nothing under it gets one, nor Scene::onTouch()). On it, a panel centred
     * on the screen, min($w, screen width - 32) wide: radius 26, surface, a 1 px border in borderStrong, a shadow
     * (0, 30, blur 30, black at 60 %; none when shadows are not built), a padding of 26. From the top, 12 px apart:
     * the title (fontTitle, text), the text (font, textMuted; one line per "\n", no automatic wrapping), the content
     * (the elements of add(), whose coordinates start at the content's top-left; as wide as the panel minus the
     * paddings) and the buttons of buttons() (one row of equal widths, or with $stack a column at full width; the
     * dialog gives each its width and place). The panel's height comes from what it holds and is cut to the screen
     * height - 32: put a long content in a Scroll of your own, and keep the text to a few lines (the buttons come
     * last and a long text pushes them under the cut). A dialog is shown only with Scene::open(): add() of a Dialog
     * to a scene or a group throws \Error ("Baremetal\Slate\Dialog is opened with Scene::open(), not added").
     *
     * Opening and closing animate in 300 ms (the scrim fades, the panel moves 14 px and fades, each of its parts with
     * the panel's opacity: halfway, texts and buttons look washed out); after the closing
     * animation the dialog leaves its scene, then onClose() and the callback of closed() run. A dialog whose scene is
     * not shown closes at once. $w and $h (inherited) read the screen's size and cannot be written.
     *
     * While dialogs are open only the top one (the last opened) and what is in it take a new touch, from the moment
     * Scene::open() returns (also in the first frames, while the scrim is still clear). While a dialog closes nothing
     * in it takes a touch (a finger held on its content gets Cancel); its scrim still does. $enabled = false dims it
     * and its scrim takes no touch (no dismiss), but it still blocks what is under it. With $visible = false an open
     * dialog blocks nothing (what is under it and Scene::onTouch() take touches; the open dialog below it is the top
     * one), and its close ends at once, without the animation.
     */
    class Dialog extends Control
    {
        /** A tap on the scrim (outside the panel) closes the dialog. */
        public bool $dismissable = false;

        /**
         * @param string $title The title ('': none).
         * @param string $text The text ('': none), lines separated by "\n" (at most 100).
         * @param int $w The panel's width, 1..32767 (cut to the screen width - 32).
         * @param bool $stack The buttons in a column at full width, instead of one row.
         * @throws \Error Without a running Slate ("Baremetal\Slate\Dialog needs a running Slate: create the Slate
         *     before its controls").
         * @throws \ValueError When $w is outside 1..32767 ("Baremetal\Slate\Dialog::$w must be between 1 and
         *     32767"), or $text has more than 100 lines.
         */
        public function __construct(string $title = '', string $text = '', int $w = 460, bool $stack = false) {}

        /**
         * The buttons at the bottom of the panel, in order (they replace the ones given before). The dialog sets
         * their width and their place; their taps are theirs (call close() from one).
         *
         * @throws \LogicException When a button already belongs to a group or a scene.
         * @throws \ValueError With more than 100 buttons ("Baremetal\Slate\Dialog::buttons(): at most 100 buttons").
         */
        public function buttons(Button ...$b): static {}

        /**
         * Adds elements to the content, under the text (coordinates from the content's top-left); the panel is laid
         * out again.
         *
         * @throws \LogicException When an element already belongs to a group or a scene.
         */
        public function add(Element ...$e): static {}

        /** Takes elements out of the content (or buttons out of the buttons); the panel is laid out again. */
        public function remove(Element ...$e): static {}

        /**
         * Closes the dialog: the closing animation, then the dialog leaves its scene, then onClose() and closed().
         * While it closes nothing in it takes a touch: a second tap on one of its buttons runs nothing and a finger
         * held on its content gets Cancel (the scrim still takes touches until it leaves). When its scene is not
         * shown, or its $visible is false, it goes at once, and so does a dialog still closing when another scene is
         * shown or when it is hidden. Nothing for a dialog that is not open (or is closing). A dialog closing when
         * the Slate stops leaves its scene without onClose() and closed().
         */
        public function close(): void {}

        /** Called when the dialog has closed (after the animation). Empty: override it. */
        public function onClose(): void {}

        /** The callback of the close (one; a new one replaces it, null removes it). It runs after onClose(). */
        public function closed(?\Closure $fn): static {}
    }

    /**
     * A ring that shows a progress: a full track in well and an arc in accent (or $color) with round ends, from the
     * top (-90 degrees) clockwise for $value x 360 degrees. The stroke is $width wide, centred on the circle of radius
     * $r around ($cx, $cy). A write of $value slides the arc in 200 ms.
     *
     * With $percent the number round($value x 100) (fontDisplay, text) and a "%" (font, accent) are centred in the
     * ring. With $spinning the ring is indeterminate: an arc of 25 % turns for ever (a turn in 900 ms, without
     * TweenDone; it runs only while the ring is shown), $value is kept but not drawn and the percent is hidden; back
     * to false, the arc shows the value again at once.
     *
     * $x and $y are the centre; $w and $h (inherited) read the size, 2 $r + $width, and cannot be written. $clip has
     * no effect on it ($cache works). Not touchable by default; add() and remove() throw.
     */
    class ProgressRing extends Control
    {
        /** The progress, 0..1 (a finite value outside is brought into the range); a write slides the arc. */
        public float $value;

        /** Indeterminate: a turning arc instead of the value. */
        public bool $spinning = false;

        /** The arc's colour, 0xRRGGBB (null: the theme's accent). */
        public ?int $color = null;

        /** false by default: a display, the touch reaches what is under it. */
        public bool $touchable = false;

        /**
         * @param int|float $cx The centre.
         * @param int $r The radius of the ring (the stroke's centre line), 1..32767.
         * @param float $value 0..1.
         * @param int $width The stroke's width, 1..32767.
         * @param bool $percent The percent in the middle.
         * @throws \Error Without a running Slate ("Baremetal\Slate\ProgressRing needs a running Slate: create the
         *     Slate before its controls").
         * @throws \ValueError When $r or $width is outside 1..32767 ("Baremetal\Slate\ProgressRing::$r must be between
         *     1 and 32767"), or $value is not finite ("Baremetal\Slate\ProgressRing::$value must be a finite
         *     number"; a write of $value too).
         */
        public function __construct(int|float $cx, int|float $cy, int $r, float $value = 0.0, int $width = 12,
                                    bool $percent = false) {}
    }

    /**
     * A bar that shows a progress: a track w x h in well and a fill in accent (or $color), $value x w wide, both with
     * the radius h / 2. A write of $value slides the fill in 200 ms. With $glow the fill has a shadow of its colour
     * (0, 0, blur 10); a firmware built without shadows draws none.
     *
     * $x and $y are the top-left; $w and $h (inherited) read the size and cannot be written. Not touchable by
     * default; add() and remove() throw.
     */
    class ProgressBar extends Control
    {
        /** The progress, 0..1 (a finite value outside is brought into the range); a write slides the fill. */
        public float $value;

        /** A glow around the fill (none when shadows are not built). */
        public bool $glow = false;

        /** The fill's colour, 0xRRGGBB (null: the theme's accent). */
        public ?int $color = null;

        /** false by default: a display, the touch reaches what is under it. */
        public bool $touchable = false;

        /**
         * @param int $w The width, 1..32767.
         * @param float $value 0..1.
         * @param int $h The height, 1..32767.
         * @throws \Error Without a running Slate ("Baremetal\Slate\ProgressBar needs a running Slate: create the
         *     Slate before its controls").
         * @throws \ValueError When $w or $h is outside 1..32767 ("Baremetal\Slate\ProgressBar::$w must be between 1
         *     and 32767"), or $value is not finite ("Baremetal\Slate\ProgressBar::$value must be a finite number"; a
         *     write of $value too).
         */
        public function __construct(int|float $x, int|float $y, int $w, float $value = 0.0, int $h = 4) {}
    }

    /**
     * A busy indicator: an arc of 25 %, 3 px wide with round ends, in accent (or $color), on the circle of radius $r
     * around ($cx, $cy), turning for ever (a turn in 900 ms, without TweenDone). It turns only while it is shown (its
     * scene shown, its $visible and its groups' true) and costs nothing when it is not; while it turns only its own
     * small area is drawn again.
     *
     * $x and $y are the centre; $w and $h (inherited) read the size, 2 $r + 3, and cannot be written. $clip has no
     * effect on it ($cache works). Not touchable by default; add() and remove() throw.
     */
    class Spinner extends Control
    {
        /** The arc's colour, 0xRRGGBB (null: the theme's accent). */
        public ?int $color = null;

        /** false by default: a display, the touch reaches what is under it. */
        public bool $touchable = false;

        /**
         * @param int $r The radius, 1..32767.
         * @throws \Error Without a running Slate ("Baremetal\Slate\Spinner needs a running Slate: create the Slate
         *     before its controls").
         * @throws \ValueError When $r is outside 1..32767 ("Baremetal\Slate\Spinner::$r must be between 1 and
         *     32767").
         */
        public function __construct(int|float $cx, int|float $cy, int $r = 12) {}
    }

    /**
     * The steps of a process, one row each (48 high, 8 apart, radius 14), with a circle of 24 px at the left and the
     * step's text (font) at x 48:
     *   - a step done (before $active): the circle in success at 15 % with a check in success, the text textMuted;
     *   - the active step ($active): a small spinner in the circle, the row's border in accent, the text text;
     *   - a step to do: a 2 px ring in borderStrong, the text textDim.
     * A write of $active moves on (the colours fade in 200 ms) and the steps that become done pop (their circle
     * from 40 % to 108 % and back to 100 % in 400 ms, without TweenDone); $active = count($steps): all done.
     *
     * $x and $y are the top-left; $w and $h (inherited) read the size (w x 56 count($steps) - 8) and cannot be
     * written. Not touchable by default; add() and remove() throw.
     */
    class StepList extends Control
    {
        /** The active step, 0..count($steps) (count($steps): all done). */
        public int $active;

        /** The texts of the steps. */
        public readonly array $steps;

        /** false by default: a display, the touch reaches what is under it. */
        public bool $touchable = false;

        /**
         * @param int $w The width, 1..32767.
         * @param string[] $steps The texts of the steps, a non-empty list (at most 21).
         * @param int $active 0..count($steps).
         * @throws \Error Without a running Slate ("Baremetal\Slate\StepList needs a running Slate: create the Slate
         *     before its controls").
         * @throws \ValueError When $w is outside 1..32767 ("Baremetal\Slate\StepList::$w must be between 1 and
         *     32767"), $steps is not a non-empty list of strings ("Baremetal\Slate\StepList::$steps must be a
         *     non-empty list of strings") or holds more than 21 ("... must hold at most 21 steps"), or $active is
         *     outside 0..count($steps) ("Baremetal\Slate\StepList::$active must be between 0 and <n>"; a write of
         *     $active too).
         */
        public function __construct(int|float $x, int|float $y, int $w, array $steps, int $active = 0) {}
    }
}
Download ext-slate.php