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
// 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) {}
}
}