ext-slate · PHP API
Scenes and pages
A Slate shows one Scene at a time, at once or with a transition; a page of the application is a class that extends Scene, with its components in build() and its actions in methods and listeners.
Slate
Slate::__construct(Display $display, ?Touch $touch = null)
Takes the panel of $display (a Baremetal\Output\Display whose driver has the band path) and starts the
compositor. With $touch (a Baremetal\Input\Touch), Slate turns on its events and forwards them to the scene
shown at the time. From now on the drawing methods of the display throw \LogicException; width(),
height(), backlight(), sleep(), wake() and refreshRate() keep working. When the panel has a TE pin, the
frames start at its pulses. Between sleep() and wake() no new frame starts (a frame already under way at sleep() finishes; the changes wait for wake()); when the
driver re-initialises the panel on wake() (St77916 does), Slate sends the whole screen again.
Slate::onboard(): Slate
Returns Slate.
A Slate on the board's own screen. When the board has a display block, Slate looks among the loaded classes
for the display driver that declares a static onboard() (for example St77916 of esp32-display-st77916) and
calls it; when the board also has a touch block and one touch driver with onboard() is loaded (for example
Cst816s of touch-cst816s), its device becomes the touch of the Slate. No display block, no display driver, or
several drivers of the same kind with onboard(): \LogicException, and the Slate is built by hand with
new Slate($display, $touch).
Slate::show(Scene $s, ?Transition $t = null): void
Returns void.
Shows $s. Without $t the switch is immediate: onLeave() of the scene shown until now, build() the first
time $s is shown, then onEnter(). With $t the new scene slides or fades in (see
Transitions). Either way the change is handed to the compositor at once, with what onEnter()
changed. Showing the scene already shown does nothing more than hand over the pending changes. If build()
throws, the scene is emptied and built again by the next show(), and the scene shown until now stays on screen.
Slate::scene(): ?Scene
Returns ?Scene.
The scene shown now, null before the first show(). During a transition, the scene it goes to.
Slate::commit(): void
Returns void.
Hands the changes made so far to the compositor now. The event loop does it by itself after each listener
(event-driven) and after each loop() (init-loop); commit() is for a script that never returns to a loop.
The compositor composes the frame in its own task, while the script goes on: when the program ends, the Slate
stops, so a script that only draws must keep running (a loop, or the event-driven runtime) for the frame to
reach the panel.
One Slate at a time: a second new Slate() or Slate::onboard(), on the same panel or another, throws
\LogicException (Slate: a Slate already drives <Class>; only one Slate can run at a time). unset($slate)
(or the end of the program) stops the compositor and gives the panel back; the next flush() of the display
sends its whole framebuffer.
Scene
Scene::add(Element ...$e): static
Returns static.
Adds elements on top of the scene's elements: the last one added is drawn on top.
Scene::remove(Element ...$e): static
Returns static.
Takes elements out; they stay usable and can be added again, here or elsewhere.
Scene::open(Dialog $d): static
Returns static.
Opens a dialog above the scene: above all its elements and the dialogs open already, with
its opening animation (300 ms). A dialog belongs to its scene: when another scene is shown it stays open, and it
shows again when the scene comes back; closed while the scene is not shown, it goes at once (and still calls
onClose()). While dialogs are open, add() keeps them on top of what it adds, and remove() of an open dialog
closes it at once; a dialog still closing when another scene is shown ends at once. open() ends the touch under
way (see Controls, Dialog). add() of a Dialog throws \Error. open() of a dialog that is open already, here or in another scene, throws \Error
(Baremetal\Slate\Dialog is already open). Not built without slate-controls.
| Method | Called |
|---|---|
protected build(): void |
Once, by the first show() of the scene, before onEnter(): add the components here. |
onEnter(): void |
Each time the scene is shown; with a transition, when it starts. |
onLeave(): void |
When another scene replaces it; with a transition, when it ends. |
onTouch(TouchEvent $e): void |
For each Pressed, Moved, Released and Gesture of the Slate's touch device while the scene is shown, for the touches that no element takes (see Touch). |
All four are empty in Scene. A scene can also be built without a class:
$about = (new Scene())->add(
new Text(180, 170, 'php-baremetal', align: Align::Center),
);
$slate->show($about);
A page
A page is a class: its components are properties built in build(), its actions are methods, and listeners
change it.
<?php
use Baremetal\Input\{TouchEvent, Gesture, GestureType};
use Baremetal\Slate\{Slate, Scene, RoundRect, Text, Align};
final class Home extends Scene
{
public Text $temp;
protected function build(): void
{
$this->add(
new RoundRect(20, 20, 320, 120, radius: 16, fill: 0x202830),
$this->temp = new Text(180, 60, '-- °C', align: Align::Center),
);
}
public function setTemperature(float $c): void
{
$this->temp->text = sprintf('%.1f °C', $c);
}
public function onTouch(TouchEvent $e): void
{
global $slate, $settings;
if ($e instanceof Gesture && $e->type === GestureType::SwipeLeft) {
$slate->show($settings);
}
}
}
final class Settings extends Scene
{
protected function build(): void
{
$this->add(new Text(180, 170, 'Settings', align: Align::Center));
}
}
$slate = Slate::onboard();
$home = new Home();
$settings = new Settings();
$slate->show($home);
Transitions
<?php
use Baremetal\Events;
use Baremetal\Slate\{Transition, Direction, TransitionDone, Ease};
$slate->show($menu, Transition::push(Direction::Left)); // forward
$slate->show($home, Transition::push(Direction::Right)); // back
$slate->show($panel, Transition::cover(Direction::Up, ms: 250)); // a panel slides up over the page
$slate->show($home, Transition::uncover(Direction::Down)); // and slides away again
$slate->show($splash, Transition::fade(ms: 400, ease: Ease::InOutCubic));
$slate->show($home); // at once
Events::listen(TransitionDone::class, function (TransitionDone $e) {
echo get_class($e->from), ' -> ', get_class($e->to), "\n";
});
Transition::fade(int $ms = 300, Ease $ease = Ease::OutCubic): Transition
Returns Transition.
The new scene appears over the old one, its opacity going from 0 to 1.
Transition::push(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic): Transition
Returns Transition.
The new scene comes in from the side opposite to $d and pushes the old one out towards $d:
Direction::Left is the usual "forward", Direction::Right "back".
Transition::cover(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic): Transition
Returns Transition.
The new scene slides in towards $d over the old one, which stays still.
Transition::uncover(Direction $d, int $ms = 300, Ease $ease = Ease::OutCubic): Transition
Returns Transition.
The old scene slides away towards $d and uncovers the new one, which stays still.
Direction is an enum: Left, Right, Up, Down, the direction of the movement. $ease is one of the
easing curves of the animations. A Transition is a value: keep one and pass it to as many
show() calls as you like. $ms below 1 throws \ValueError ms must be at least 1, above 2147483647
ms must be at most 2147483647.
What happens, in order:
show($b, $t):build()of$bthe first time, thenonEnter()of$bat once: its elements are ready and its tweens start with the transition.scene()is$bfrom now on.- For
$msmilliseconds the compositor composes both scenes together, band by band, at the pace of the panel. The tweens of both scenes run. The touch of the Slate reaches neither scene: a touch during a transition is lost. - At the end:
onLeave()of the old scene, then the eventTransitionDonewith$from(the old scene) and$to(the new one), a final class that extendsBaremetal\Event, delivered after the return to the event loop. The old scene's tweens wait, as for any scene that is not shown.
show()of the scene shown, or of the one a transition goes to, does nothing.show()during a transition ends it first:onLeave()of the scene it leaves runs at once, itsTransitionDonefollows; then the new change starts from the scene the first one went to, whole. Going back to the scene being left is fine:onLeave()runs for it, thenonEnter()again.- The first
show()with a transition (no scene shown before) brings the scene in over the black background. Nothing is left, so noTransitionDonecomes. - In
init-loop, which delivers no events, there is noTransitionDone, and theonLeave()of the old scene runs at the nextshow()orcommit()after the end: a$slate->commit()inloop()runs it promptly. The same happens inevent-drivenwhen the event pool of ext-events is full. - When the Slate stops during a transition (
unset($slate)), neitheronLeave()norTransitionDonecomes. - When memory is too short for the transition's layers, the change is a cut (at once), still followed by
onLeave()andTransitionDone.
Thrown by show() with a transition |
When |
|---|---|
\RuntimeException Slate: cannot run a transition: the table of ext-events' idle hooks is full |
Other extensions took the four idle hooks ext-events keeps (Slate uses one, shared by all its parts). |
\RuntimeException Slate: cannot run a transition: the table of ext-events' watches is full |
Other extensions took the eight watches ext-events keeps (Slate uses up to six: four for the touch, one for HoldDue (the Hold of a touch and the ends of the controls' animations), one for TransitionDone). |
\RuntimeException Slate: out of memory for the transition |
No memory for the few bytes that carry its end. Nothing changed. |
A frame during a transition costs about as much as the two scenes together, and the whole screen is sent at each refresh while the scenes move. The cached groups of both scenes are used and move with their scene. See Performance.
Returning to a scene
A scene left keeps its caches (cached groups, shadows, blurs) while there is room, so showing it again, with or without a transition, draws it from those images at once instead of building them again.
$slate->keepScenes = 2; // scenes left that keep their caches (default 2; 0: none)
$slate->keptBudget = null; // a limit in KB for those caches (default null: only the cache budget)
final class Splash extends Scene
{
protected bool $keepCache = false; // shown once: its caches go when it is left
}
| Property | Type | Default | Meaning |
|---|---|---|---|
Slate::$keepScenes |
int |
2 |
How many scenes left keep their caches. Past it, the scene left first drops them. 0: every scene left drops its caches, as in 1.1. |
Slate::$keptBudget |
?int |
null |
A limit in KB for the caches of the scenes left; past it, the scene left first drops them. null: no limit of its own (only the cache budget); 0: nothing is kept. |
Scene::$keepCache |
bool (protected) |
true |
false: the scene drops its caches when it is left. Read when the scene is left. |
- The kept caches stay where they are: in Slate's cache budget, in external RAM (PSRAM). They take no internal RAM and no memory beyond that budget.
- When the scene shown, or the underlay, needs room in the budget, the scenes left drop their caches first, the one left first before the others: a kept cache never takes room from the scene on the screen.
- Images are not part of the budget, but when an image cannot be loaded for lack of memory, the scenes left drop
their caches and the image is loaded once more; only then does it fail with
no-memory. - Lowering
$keepScenesor$keptBudgetdrops the extra caches at once. - A scene whose caches were dropped builds them again at its first frame, as before.
| Thrown by a write | When |
|---|---|
\ValueError keepScenes must be 0 or more |
A negative $keepScenes; the old value stays. |
\ValueError keptBudget must be 0 or more |
A negative $keptBudget; the old value stays. |
Like the elements' properties, they cannot be taken by reference or unset (\Error).
Touch
Slate routes the touch events of its Touch when the event is delivered: a Pressed on an element that takes
touches ($touchable, or a callback of on()) makes the whole touch that element's (onPress()..onCancel(),
see Touch); a Scroll takes touches by default (see Scroll); the touches whose Pressed hits no such element go to onTouch() of the scene shown, as
the raw TouchEvents (Pressed, Moved, Released, Gesture). A Gesture the touch controller reports after
the Released belongs to that touch: the scene gets it only when the touch was the scene's (a swipe that drags a
slider or a carousel is not a page change). A scene without touchable elements gets every event. The other scenes get nothing. The events come from the event bus of ext-events, so they arrive in the
event-driven runtime (in init-loop source events are not delivered). Listeners of the same classes
registered with Events::listen() still get them all, after Slate. During a transition neither the elements nor
the scenes get them (the listeners still do).
show() of another scene (and the start of a transition) ends a touch an element holds: the element gets
onCancel() before onLeave() of the scene left (a Scroll that holds one stops its drag without speed).
Lifetime
- A group (or a scene) keeps its children alive; the Slate keeps the scene it shows, the display and the touch device.
- A component of your own extends
Group:newof a class that extendsElementdirectly throws\LogicException(<Class>: extend Baremetal\Slate\Group to build a custom element). - Slate properties cannot be taken by reference (
$r = &$el->x, a by-reference argument):\ErrorCannot take a reference to <Class>::$x. Every write goes through validation and reaches the compositor. - An element belongs to one parent at a time: adding it to a second one throws
\LogicException(... already belongs to a group: remove() it from there first). - An element dropped by PHP (no reference left) is removed from the compositor too.
- Elements can be built before the Slate exists; nothing reaches the compositor until their scene is shown.
After
unset($slate)a new Slate shows the same scenes again.
Related
- Elements API
- Animations API
- Touch API
- Slate Overview
- ext-input Extension