ext-slate · PHP API
Controls
Ready-made controls drawn with the theme: one PHP object each, its parts in the compositor. Control is their base, and the base of a control of your own: $enabled, the pressed look, onChange() and changed(). Rows of settings, dialogs, toasts, progress and steps.
A control is an element that the user works with or looks at: a button, a toggle, a slider, a choice, a row of
settings, a dialog, a progress ring or bar, a spinner, a list of steps. For PHP it is
one object: its parts (a background, a text, an icon) live in the compositor as elements without a PHP object
each, so a screen of controls costs little memory and the compositor redraws only the part that changed. A control
draws itself with the theme, takes the touch as a whole (its area is the union of its parts) and goes
in a scene, a group or a Scroll like any element. The 06-display/slate-controls example shows them all on a
360 x 360 round panel; what they cost is in Performance.
<?php
use Baremetal\Slate\{Slate, Scene, Button, Variant, Size, Shape, Touch, TouchType};
$slate = Slate::onboard(); // the Slate (and its theme) first: a control needs it when it is made
$start = new Button(40, 200, 'Start', Variant::Primary, Size::Large, w: 280, shape: Shape::Pill);
$start->on(TouchType::Tap, fn (Touch $t) => brew());
$cancel = new Button(40, 270, 'Cancel', Variant::Ghost, w: 280);
$slate->show((new Scene())->add($start, $cancel));
Control
abstract class Control extends Group. What every control has:
| Member | Meaning |
|---|---|
public bool $touchable = true |
A control takes touches by default. |
public bool $enabled = true |
false: the control is drawn at 0.4 times its $opacity (which keeps the value written) and takes no new touch; a touch under way gets Cancel. Writing $enabled sends the control's opacity again, which stops a tween of $opacity running on it (an animate() or repeat of the opacity ends where it is). |
protected readonly Theme $theme |
The running Slate's theme when the control was made. |
public function onChange(mixed $value): void {} |
The value changed by the user's gesture. Empty: override it. |
public function changed(?\Closure $fn): static |
The callback of the user's changes (one; a new one replaces it, null removes it). It runs after onChange(). |
protected function notify(mixed $value): void |
Calls onChange($value), then the callback of changed(). |
protected function pressed(bool $down): void {} |
true at Press, false at Release and Cancel, also when $enabled turns false during the touch. |
Control::__construct(int|float $x = 0, int|float $y = 0)
A control needs a running Slate when it is made (new Slate() first), and reads the Slate's theme then.
- The pressed look. Slate's controls show it from
PresstoReleaseorCancel: their fill goes 12 % toward white in 80 ms, and back (a fill that is not opaque gets thetextcolour at 6 % laid over it). Nothing scales. - Notifications are for the user's gestures only. A change made by the code (a write of a property) is drawn,
but
onChange()and the callback ofchanged()do not run. Of a gesture, the control's behaviour comes first, then its method (onTap()...), then its callback ofon(); an exception stops there, as in any touch handler (see Touch). add()andremove()belong to the controls of your own (classes that extendControldirectly): Slate's controls build their own parts and throw\Error.- Properties of Slate's controls in your subclass. A subclass of
Button(and the others) that declares a property of the control again (public string $text = 'x';) writes it as a plain PHP property: the control is not laid out or redrawn again. Use the inherited properties, and add your own under other names. - One constructor call. Calling
parent::__construct()(or a control's constructor) twice on the same object throws\Error:<Class> is already constructed. $wand$hof Slate's controls read the size laid out (the width given or computed, the height from the theme) and cannot be written. A control of your own keeps those ofGroup.- The touch methods and callbacks of Touch (
onTap(),on(TouchType::Tap, ...)...) work on every control.
Button
Button::__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)
A push button. Its action is onTap() or on(TouchType::Tap, ...); it notifies no onChange(). Button is not
final: a class of your own may extend it.
| Variant | Fill | Border | Text and icon |
|---|---|---|---|
Variant::Primary |
accent |
none | onAccent |
Variant::Secondary (default) |
raised |
1 px borderStrong |
text |
Variant::Ghost |
none | none | textMuted |
Variant::Danger |
danger |
none | onAccent |
Variant::Outline |
none | 1 px accent at 60 % |
accent |
Pressed, the fill goes 12 % toward white; Ghost and Outline, which have no fill, show the text colour at 6 %.
- Size. The height comes from the theme:
Size::Small,Size::Medium(default) andSize::Largeare its$small,$mediumand$large(40, 48 and 56 px by default). Withw: 0the width is the text plus a padding on each side (16, 20 and 24 px for the three sizes), plus 20 + 8 px with an icon; with a width the content is centred. No text and an icon: a square, as wide as it is high. - Shape.
Shape::Rounded(default) rounds the corners by the theme's$radius;Shape::Pillby half the height. - Icon.
$iconis an image file, asImage::$src(an absolute path ending in.slior.png, such as'/app/assets/icons/back.sli'), 20 × 20 px, drawn left of the text. Icons are monochrome: only their alpha counts, and they take the colour of the text. An icon loads as anImagedoes; one that does not load stays empty (withImageFailed, its path in$path), and the button is drawn without it.
| Property | Type | Meaning |
|---|---|---|
$text |
string |
The text; a write lays the button out again (with w: 0, its width too). |
$variant |
Variant |
The colours. |
$fill |
?int |
The fill, 0xRRGGBB, in place of the variant's; null (default): the variant's. |
$color |
?int |
The colour of the text and of the icon, 0xRRGGBB; null (default): the variant's. |
A write sends only what changed; a new $variant or $fill shows at once, without the 80 ms of the pressed look.
$back = new Button(16, 16, '', Variant::Ghost, Size::Small, icon: '/app/assets/icons/back.sli');
$back->on(TouchType::Tap, fn () => $slate->show($home));
$next = new Button(200, 300, 'Next', Variant::Primary);
$next->enabled = false; // drawn at 40 %, takes no touch
// ... later
$next->enabled = true;
Toggle
Toggle::__construct(int|float $x, int|float $y, bool $on = false, Size $size = Size::Medium)
An on/off switch: a track with a round knob. A tap inverts $on: the knob and the colours slide in 250 ms, then
onChange(bool $on) and the callback of changed() run. Toggle is not final.
<?php
use Baremetal\Slate\{Slate, Scene, Toggle};
$slate = Slate::onboard();
$wifi = new Toggle(260, 40, on: true);
$wifi->changed(fn (bool $on) => $on ? wifi_up() : wifi_down());
$slate->show((new Scene())->add($wifi));
| Size | Track | Knob |
|---|---|---|
Size::Small |
52 × 30 | 24 |
Size::Medium (default) |
62 × 36 | 28 |
Size::Large |
72 × 42 | 34 |
The knob sits 4 px from the ends of the track. On: the track is accent and the knob bg; off: the track is
borderStrong and the knob textMuted. Pressed, the track goes 12 % toward white (in the same 250 ms).
| Property | Type | Meaning |
|---|---|---|
$on |
bool |
The state. A write from your code slides the toggle over, with no onChange(). |
$hitPad |
int |
8 by default (Element's is 0): the toggle takes a touch up to 8 px around its track. |
Slider
Slider::__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)
A value picked along a track. The area is as high as the size (the theme's $small, $medium, $large) and $w
wide; in it, a track 8 px high (well) filled up to the value (accent), and a knob of 24, 30 or 34 px (Small,
Medium, Large) in text with a border of 5 px in accent. The knob's centre runs from half a knob from the left end
to half a knob from the right end. w: 0 is allowed: the track has no length and only the knob shows. Slider is
not final.
A press moves the knob under the finger, on the step; the knob then follows the finger, also outside the area (the touch stays the slider's until the release).
- When
onChange()runs. Not at the press, and not while the finger stays within 8 px of it: the knob moves, but the touch may still turn out to be a scroll. Once the finger is past 8 px and the touch is still the slider's,onChange($value)runs when the value changed, at most once per frame (frames the compositor drew): a value held back goes out at a later move after a frame, or at the release. At the release, a value not notified yet goes out first (a tap on the track notifies there), thenonCommit($value)and the callback ofcommitted(): always, also when the value is the one of before the press. Save to flash or send to the network inonCommit(), not inonChange(). - In a vertical
Scroll. The slider keeps a horizontal drag. A vertical one goes to theScrollat 8 px (the axis of the larger movement there, as for any element in aScroll): the slider getsCanceland goes back to the value it had before the press, with noonChange()and noonCommit(). - Another
Cancel($enabledset tofalse, another scene shown): before anyonChange()of the touch it does the same (back to the value of before the press, no notification). After the drag has notified, the value stays: a value held back goes out, thenonCommit()and the callback ofcommitted()run, as at a release. A$valuewritten by your code during the touch takes the place of the value of before the press. - Int or float.
$value(and whatonChange()andonCommit()receive) is anintwhen$min,$maxand$stepare allint, afloatotherwise.
<?php
use Baremetal\Slate\{Slate, Scene, Slider};
final class Brightness extends Slider
{
public function onChange(mixed $value): void { backlight($value); } // while dragging
public function onCommit(int|float $value): void { save_brightness($value); } // at the release
}
$slate = Slate::onboard();
$slate->show((new Scene())->add(new Brightness(20, 100, 320, min: 10, max: 100, value: 60, step: 5)));
| Member | Type | Meaning |
|---|---|---|
$value |
int|float |
The value. |
$min, $max |
int|float |
The range; $min must be less than $max. |
$step |
int|float |
The step: the values are $min + k * $step, up to the last one at or below $max, rounded to the decimals of $step and $min (step 0.1 gives 0.3, not 0.30000000000000004). |
$fill |
?int |
The colour of the fill and of the knob's border, 0xRRGGBB; null (default): accent. |
onCommit(int|float $value): void |
method | The value at the release. Empty: override it. |
committed(?\Closure $fn): static |
method | The callback of the release (one; null removes it). It runs after onCommit(). |
A write of $value, $min, $max or $step from your code brings $value into the range and onto the step and
moves the knob at once, with no onChange().
Choice
Choice::__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 = [])
One item (or, with multi: true, several) picked among $labels, in one of four styles. A tap on an item selects
it: its colours slide in 200 ms, then onChange() and the callback of changed() run. Choice is not final.
<?php
use Baremetal\Slate\{Slate, Scene, Choice, Size};
$slate = Slate::onboard();
$temp = new Choice(40, 60, ['Low', 'Mid', 'High'], 1, size: Size::Small);
$temp->changed(fn (int $i) => set_temperature($i));
$slate->show((new Scene())->add($temp));
<?php
use Baremetal\Slate\{Slate, Scene, Choice, ChoiceStyle, Size};
$slate = Slate::onboard();
$days = new Choice(50, 120, ['M', 'T', 'W', 'T', 'F', 'S', 'S'], [0, 2, 4], ChoiceStyle::Chips, w: 260,
size: Size::Small, multi: true);
$days->changed(fn (array $on) => save_days($on)); // the sorted indexes, e.g. [0, 2, 4, 5]
$slate->show((new Scene())->add($days));
<?php
use Baremetal\Slate\{Slate, Scene, Choice, ChoiceStyle};
$slate = Slate::onboard();
$lang = new Choice(60, 80, ['English', 'Italiano', 'Deutsch', 'Français'], style: ChoiceStyle::List, w: 240);
$lang->changed(fn (int $i) => set_language($i));
$slate->show((new Scene())->add($lang));
<?php
use Baremetal\Slate\{Slate, Scene, Choice, ChoiceStyle, Size};
$slate = Slate::onboard();
$nav = new Choice(60, 270, ['Settings', 'Buttons', 'Brew'], style: ChoiceStyle::Nav, w: 240, size: Size::Large, icons: [
'/app/assets/icons/settings.sli', '/app/assets/icons/buttons.sli', '/app/assets/icons/brew.sli',
]);
$nav->changed(fn (int $i) => show_page($i)); // 0 Settings, 1 Buttons, 2 Brew
$slate->show((new Scene())->add($nav));
Every item is as high as the size ($small, $medium, $large of the theme). The paddings are 16, 20 and 24 px for
Small, Medium and Large.
| Style | Layout | Selected | The others |
|---|---|---|---|
ChoiceStyle::Segmented (default) |
A well container (1 px border, radius the theme's + 4) with a padding of 4 and equal segments inside it (h - 8 high, the theme's radius). w: 0: each segment as wide as the widest label plus 2 paddings; w > 0: the segments share w - 8. |
accent, text onAccent |
transparent, text textMuted |
ChoiceStyle::Chips |
Pills 8 px apart, each as wide as its label plus 2 paddings. w: 0: one row; w > 0: a chip that does not fit goes to the next row (rows 8 px apart). |
accent, text onAccent |
raised, 1 px border, text textMuted |
ChoiceStyle::List |
Rows w wide (required), one under the other, the label on the left. |
accent at 12 %, 1 px accent at 35 %, text accent |
transparent, text textMuted |
ChoiceStyle::Nav |
w (required) in equal parts: an icon (24 × 24, required) above the label in fontSmall. |
text accent and a bar 3 px high at the top of the part (inset 32 % each side) that slides to it |
text textDim |
- Icons:
$iconsis empty or holds one path per label (asImage::$src). They are monochrome: drawn in the colour of the item's text, which slides with it. InSegmented,ChipsandListan icon (20 × 20) goes left of the label and widens the item by 28 px. - Pressed: the item under the finger, from the press to the release, in 80 ms as on the other controls (a
change of the selection takes 200 ms). An opaque fill goes 12 % toward white; a fill that is not opaque gets the
text colour at 6 % laid over it (a transparent item shows the text colour at 6 %, the selected
Listrow keeps its tint). A tap counts on the item that the press hit. InSegmented,ListandNava touch outside the items (the well's padding, or the area of a larger$hitPad) goes to the nearest item; the gaps between chips take no item. - Nav height: the icon (24 px), a gap of 2 and the
fontSmallline are centred in the size's height, at least 5 px below the top (under the bar).Size::SmallandSize::Mediumare tight for a bottom navigation: useSize::Large, or a theme whoselargeis taller (around 70 px). - One item (default):
$selectedis the index; a tap on another item selects it and callsonChange(int); a tap on the selected item does nothing. multi: true:$selectedis the sorted list of the selected indexes (anintgiven becomes a list of one,[]selects none); each tap turns an item on or off and callsonChange(array)with the new list. Without$selecteda multi choice starts with item 0 on (the default0is[0]): pass[]to start with none. In aNavthe bar marks the first selected part; with none selected it hides.
| Property | Type | Meaning |
|---|---|---|
$selected |
int|array |
The selected index, or the sorted list with multi. A write from your code slides the colours, with no onChange(); one outside the labels throws and the old value stays. |
The labels, the icons, the style, the width and the size are fixed when the choice is made. The content is not
clipped to $w: a chip wider than w sits alone in its row and is wider than $w, a label wider than its segment
or its Nav part runs over its neighbours; keep the labels short or the width larger. A control has at most 127
parts: a Choice holds up to 41 items with icons (63 without), more throw \Error Baremetal\Slate\Choice: too many parts.
SettingRow
SettingRow::__construct(int|float $x, int|float $y, int $w, string $label, string $sub = '', ?Element $control = null, string $value = '')
A row of a settings list, $w wide: a label on the left, an optional subtitle under it, an optional value on the
right and a control (a Toggle, a Slider, a Choice, a Button, any element) right-aligned, left of the value.
A 1 px divider in border closes it at the bottom. SettingRow is not final.
<?php
use Baremetal\Slate\{Slate, Scene, SettingRow, Toggle, Slider};
$slate = Slate::onboard();
$cup = new Toggle(0, 0, on: true);
$cup->changed(fn (bool $on) => set_double_cup($on));
$volume = new Slider(0, 0, 0, max: 10, value: 6); // w 0: the row stretches it
$level = new SettingRow(30, 152, 300, 'Volume', control: $volume, value: '6');
$volume->changed(function (int $v) use ($level) { $level->value = (string)$v; });
$slate->show((new Scene())->add(
new SettingRow(30, 80, 300, 'Double cup', 'Two cups at once', control: $cup),
$level,
));
- Layout: the label (
font,text) and the subtitle (fontSmall,textMuted, 2 px under the label) start at the row's left edge; the value (fontMono,textMuted) is right-aligned at$w; the control sits at the right, 12 px left of the value when there is one, centred in the height. The height is 60, 72 with a subtitle, and at least the control's height + 16. The texts are centred in it. - The control becomes a child of the row (it must not belong to a group yet): it gets its own touches and is
placed by the row, which writes its
$xand$y(again when a text changes). - A
Slidermade withw: 0is stretched: its track fills the space between the label (taken at most 40 % of$wwide) and the value, 12 px from each. - Touch: the row is not touchable by default (
$touchable = false): a touch outside the control reaches what is under the row (the scene). With$touchable = true, or a callback ofon(), the row takes the touch, with a pressed look (the text colour at 4 %, in 80 ms) andonTap().
| Property | Type | Meaning |
|---|---|---|
$label |
string |
The label. A write redraws it and places the control again. |
$sub |
string |
The subtitle; '': none (the row is 60 high). |
$value |
string |
The value at the right; '': none. A write redraws it and places the control again. |
$touchable |
bool |
false by default: only the control takes the touch. |
Dialog
Dialog::__construct(string $title = '', string $text = '', int $w = 460, bool $stack = false)
A modal dialog: a panel over a scrim that covers the screen. Scene::open() opens it above the scene,
close() closes it. Dialog is not final.
<?php
use Baremetal\Slate\{Slate, Scene, Dialog, Button, Variant, TouchType};
$slate = Slate::onboard();
$page = new Scene();
$slate->show($page);
$ask = new Dialog('Descale now?', "The machine runs for 20 minutes.\nKeep the drip tray in.");
$yes = new Button(0, 0, 'Descale', Variant::Primary);
$no = new Button(0, 0, 'Later', Variant::Ghost);
$yes->on(TouchType::Tap, function () use ($ask) { start_descaling(); $ask->close(); });
$no->on(TouchType::Tap, fn () => $ask->close());
$ask->buttons($no, $yes)->closed(fn () => refresh_status());
$page->open($ask);
- The scrim covers the screen in black at 88 % and takes every touch: nothing under it gets one, nor
Scene::onTouch(). With$dismissable = truea tap on the scrim (outside the panel) closes the dialog. While a dialog is open only the top one (the last opened) and what is in it take a new touch, from the momentopen()returns, also in the first frames of its opening, while the scrim is still clear: a quick second tap on the button that opened it does not reach that button. - The panel is
min($w, screen width - 32)wide, centred: radius 26,surface, a 1 px border inborderStrong, 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), the content and the buttons. Its height comes from what it holds and is cut to the screen height - 32. - The text breaks into lines at
"\n"only (there is no automatic wrapping): break long sentences yourself. Keep it to a few lines: the panel is cut to the screen height - 32 and the buttons come last, so a long text pushes them under the cut. - The content:
add()puts elements under the text, with coordinates from the content's top-left; it is as wide as the panel minus the paddings. A long content does not fit a short screen: put it in aScrollof your own (its view sets the height the panel gives it). - The buttons of
buttons(Button ...$b)go at the bottom, in one row of equal widths (the remainder to the first ones), or withstack: truein a column at full width; the dialog sets their width and their place. Their taps are theirs: callclose()from them. - Opening:
Scene::open($d)puts the dialog above the scene's elements and the dialogs open already; the scrim fades in and the panel rises 14 px while it fades in, in 300 ms. The panel fades element by element: each of its parts (background, shadow, texts, buttons) is drawn with its own opacity times the panel's, so halfway through the texts and buttons look washed out and what is under one part shows through it (the panel's background through a button); at the end it is exactly the panel at rest. (A panel faded as one image would be composed apart at every frame: about twice as slow.) The panel's shadow is built before the animation starts, so its first frame is not a long one and no step is skipped after it. Animations started in the same PHP turn right afteropen()(a button's pressed look, aSlate::toast()) start after that build too: 30 to 40 ms later at a dialog's first opening, not at all once its shadow is built. The touch under way ends: the element or theScrollthat holds the finger getsCancel(aSliderwith its own rules), a touch of the scene reachesScene::onTouch()no more. A dialog is open once:open()of an open dialog (in any scene; also while its closing animation runs) throws\Error. A dialog is shown only withopen():add()of aDialogto a scene or a group throws\Error. - Closing:
close()plays the opening backwards (300 ms), then the dialog leaves its scene, thenonClose()runs, then the callback ofclosed(). 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 getsCancel(the scrim still takes the touches until the dialog leaves).close()of a dialog that is not open (or is closing) does nothing. A dialog closing when the Slate stops leaves its scene withoutonClose()andclosed()(no PHP runs while the Slate stops). - Dialogs and scenes: a dialog stays with its scene. When another scene is shown it stays open (the touch under
way gets
Cancel, as for anyshow()) and shows again when its scene comes back. A dialog closed while its scene is not shown goes at once, without the animation; so does an open dialog taken out withScene::remove(), and a dialog still closing when another scene is shown (it ends at once, so it can open in the next scene). All still callonClose()andclosed(). While dialogs are open,Scene::add()keeps them on top of what it adds. A dialog open in a scene that is freed counts as closed (quietly) at its nextopen().
| Member | Type | Meaning |
|---|---|---|
$dismissable |
bool |
A tap on the scrim closes the dialog. false by default. |
buttons(Button ...$b): static |
method | The buttons, in order (they replace the ones given before); at most 100. |
add(Element ...$e): static, remove(Element ...$e): static |
method | The content; the panel is laid out again. |
close(): void |
method | Closes the dialog (see above). |
onClose(): void |
method | Called when the dialog has closed. Empty: override it. |
closed(?\Closure $fn): static |
method | The callback of the close (one; null removes it). It runs after onClose(). |
$w and $h read the screen's size. The title, the text, $w and $stack are fixed when the dialog is made.
$enabled = false on a dialog dims it to 40 % and nothing in it takes a touch, its scrim included (a dismissable
dialog no longer closes on a tap outside the panel), but it still keeps every touch from what is under it: leave
$enabled alone and disable its buttons instead. $visible = false on an open dialog hides it and it no longer
blocks: what is under it, and Scene::onTouch(), take touches again (the open dialog below it, if any, is now the
top one). close() of a hidden dialog, and $visible = false on a dialog that is closing, end the close at once,
without the animation, with onClose() and closed().
Toasts
Slate::toast(string $text, int $ms = 2500): static
Returns static.
A short message above everything: a pill 48 px high (radius 24, surface, a 1 px border in borderStrong, a
shadow when shadows are built) with an accent dot of 8 px and the text (font, text), centred, its bottom edge
at 1/6 of the screen's height from the bottom.
$slate->toast('Saved');
$slate->toast('Water tank empty', 5000);
- It rises 14 px while it fades in (300 ms), stays
$ms(at least 500), then fades out in 300 ms and goes. - Keep toasts short (about 20 characters at 16 px on a 360 px round screen): the pill is at most the screen's width
- 64, and a longer text is cut.
- It is above the scene, its dialogs and a transition (it does not move with the scenes), and takes no touch.
- A new toast replaces the one shown at once. The theme is read at the call.
Progress and status
Four controls that show a state and take no touch ($touchable = false by default: a touch reaches what is under
them; set it to true, or give a callback to on(), to make one touchable). A write from the code animates them;
none notifies. $w and $h read their size. add() and remove() throw, as for every control of Slate. None of
them is final.
<?php
use Baremetal\Slate\{Slate, Scene, ProgressRing, ProgressBar, Spinner, StepList};
$slate = Slate::onboard();
$ring = new ProgressRing(180, 96, 56, width: 12, percent: true);
$bar = new ProgressBar(60, 184, 240, h: 6);
$bar->glow = true;
$steps = new StepList(40, 206, 280, ['Heat the water', 'Grind']);
$slate->show((new Scene())->add($ring, $bar, $steps, new Spinner(330, 30)));
$ring->value = 0.4; // the arc slides in 200 ms, the percent shows 40
$bar->value = 0.4;
$steps->active = 1; // "Heat the water" is done (its circle pops), "Grind" is active
ProgressRing
ProgressRing::__construct(int|float $cx, int|float $cy, int $r, float $value = 0.0, int $width = 12, bool $percent = false)
A full track in well and an arc in accent 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): the ring reaches
$r + $width / 2 from the centre. $x and $y are the centre; the size is 2 $r + $width square. $clip has no
effect on a ProgressRing or a Spinner (nothing of theirs leaves their box); $cache works.
$value(0..1): a write slides the arc in 200 ms. A finite value outside 0..1 is brought into the range (a write of7.0reads back1.0);INFandNANthrow.$percent: the numberround($value x 100)(fontDisplay,text) and a%(font,accent), centred together in the ring.$spinning: indeterminate. An arc of 25 % turns for ever, a turn in 900 ms;$valueis kept but not drawn and the percent is hidden. Back tofalse, the arc shows the value again at once. The turn is an animation of Slate's own: noTweenDonereaches your code, and it runs only while the ring is shown.
| Property | Type | Meaning |
|---|---|---|
$value |
float |
The progress, 0..1. |
$spinning |
bool |
Indeterminate: a turning arc. false by default. |
$color |
?int |
The arc's colour, 0xRRGGBB; null: accent. |
ProgressBar
ProgressBar::__construct(int|float $x, int|float $y, int $w, float $value = 0.0, int $h = 4)
A track $w x $h in well and a fill in accent, $value x $w wide, both with the radius $h / 2. A write of
$value slides the fill in 200 ms (the same range rules as ProgressRing).
$glow: a glow around the fill, a shadow of the fill's colour (0, 0, blur 10). A firmware built without shadows (slate-effects, see Effects and build options) draws none: the bar looks the same without it.
| Property | Type | Meaning |
|---|---|---|
$value |
float |
The progress, 0..1. |
$glow |
bool |
The glow of the fill. false by default. |
$color |
?int |
The fill's colour, 0xRRGGBB; null: accent. |
Spinner
Spinner::__construct(int|float $cx, int|float $cy, int $r = 12)
A busy indicator: an arc of 25 %, 3 px wide with round ends, in accent, on the circle of radius $r around ($cx,
$cy), that turns for ever (a turn in 900 ms). $color (?int) changes its colour. It turns only while it is shown:
a spinner in a scene that is not shown, or with $visible = false on itself or on a group it is in, costs nothing
(it goes on from where it stopped when it is visible again), and while it turns only its own small area is drawn
again (no TweenDone either). $x and $y are the centre; the size is 2 $r + 3 square.
StepList
StepList::__construct(int|float $x, int|float $y, int $w, array $steps, int $active = 0)
The steps of a process, one row per text of $steps: rows of $w x 48, 8 px apart, radius 14, a circle of 24 px at
the left and the text (font) 48 px from the left edge.
- Done (before
$active): the circle insuccessat 15 % with a check insuccess; the text intextMuted. - Active (
$active): a small spinner in the circle and the row's border inaccent; the text intext. - To do: a 2 px ring in
borderStrong; the text intextDim.
A write of $active (0..count($steps)) moves on: the colours fade in 200 ms and the steps that become done pop
(their circle from 40 % to 108 % of its size in 260 ms, then back to 100 % in 140 ms). $active = count($steps): all
done, no spinner. $steps is read-only; a list holds at most 21 steps. The height is 56 count($steps) - 8.
| Property | Type | Meaning |
|---|---|---|
$active |
int |
The active step, 0..count($steps). |
$steps |
array |
The texts (read-only). |
A control of your own
A class that extends Control directly builds its parts with add() (any element: RoundRect, Text, Image,
Arc...) and gets $enabled, the theme, the notifications and the pressed hook. It calls notify() for the
user's gestures, and only for them.
<?php
use Baremetal\Slate\{Control, RoundRect, Touch};
final class Beans extends Control
{
public int $level = 0;
/** @var RoundRect[] */
private array $beans = [];
public function __construct(int $x, int $y)
{
parent::__construct($x, $y);
for ($i = 0; $i < 5; $i++) {
$this->beans[] = new RoundRect($i * 16, 0, 14, 20, radius: 4, fill: $this->theme->well);
}
$this->add(...$this->beans);
}
/** A tap on bean i sets the level to i + 1. */
public function onTap(Touch $t): void
{
$this->toLevel(intdiv($t->localX, 16) + 1);
$this->notify($this->level); // the user's gesture: onChange(), then changed()
}
/** From the code: drawn, not notified. */
public function toLevel(int $level): void
{
$this->level = $level;
foreach ($this->beans as $i => $bean) {
$bean->fill = $i < $level ? $this->theme->accent : $this->theme->well;
}
}
protected function pressed(bool $down): void
{
$this->opacity = $down ? 0.8 : 1.0;
}
}
$beans = new Beans(40, 120);
$beans->changed(fn (int $level) => $machine->strength($level));
A part that is hard to draw with shapes can be an image; the pressed look can be a second image over it, shown by
pressed():
<?php
use Baremetal\Slate\{Control, Image, Text, Align};
final class DrinkCard extends Control
{
private Image $down;
public function __construct(int $x, int $y, string $name, string $art, string $artPressed)
{
parent::__construct($x, $y);
$this->add(
new Image(0, 0, $art),
$this->down = new Image(0, 0, $artPressed),
new Text(75, 100, $name, color: $this->theme->text, align: Align::Center),
);
$this->down->visible = false;
}
protected function pressed(bool $down): void
{
$this->down->visible = $down;
}
}
Errors
| When | Throws | Message |
|---|---|---|
| A control made without a running Slate | \Error |
Baremetal\Slate\Button needs a running Slate: create the Slate before its controls (the class of the object) |
add() or remove() on Slate's controls |
\Error |
Baremetal\Slate\Button: a control builds its own parts |
A write of $w or $h of Slate's controls |
\Error |
Cannot modify Baremetal\Slate\Button::$w: the size of a control comes from its constructor and the theme |
Button: $w outside 0..32767 |
\ValueError |
Baremetal\Slate\Button::$w must be between 0 and 32767 |
Button: $icon not an absolute .sli or .png path |
\ValueError |
Baremetal\Slate\Button::$icon must be an absolute path ending in .sli or .png |
Button: a .png icon while png is not built |
\ValueError |
png is not built in: add it to slate-images in composer.json |
Button: $fill or $color outside 0..0xFFFFFF |
\ValueError |
Baremetal\Slate\Button::$fill must be a color, 0xRRGGBB |
Slider: $w outside 0..32767 |
\ValueError |
Baremetal\Slate\Slider::$w must be between 0 and 32767 |
Slider: $min, $max, $value or $step not finite (INF, NAN) |
\ValueError |
Baremetal\Slate\Slider::$value must be a finite number (the name given) |
Slider: $min not less than $max (constructor or write; the old value stays) |
\ValueError |
Baremetal\Slate\Slider::$min must be less than $max |
Slider: $step 0 or less |
\ValueError |
Baremetal\Slate\Slider::$step must be greater than 0 |
Slider: $fill outside 0..0xFFFFFF |
\ValueError |
Baremetal\Slate\Slider::$fill must be a color, 0xRRGGBB |
Choice: $labels empty or not all strings |
\ValueError |
Baremetal\Slate\Choice::$labels must be a non-empty list of strings |
Choice: $selected outside the labels (constructor or write; the old value stays) |
\ValueError |
Baremetal\Slate\Choice::$selected must be between 0 and 2 (with multi: ...::$selected must be a list of indexes between 0 and 2) |
Choice: $icons neither empty nor one per label |
\ValueError |
Baremetal\Slate\Choice::$icons must be empty or hold one path per label |
Choice: $w outside 0..32767 |
\ValueError |
Baremetal\Slate\Choice::$w must be between 0 and 32767 |
Choice: List or Nav with w: 0 |
\ValueError |
Baremetal\Slate\Choice: the List and Nav styles need w greater than 0 |
Choice: Nav without icons |
\ValueError |
Baremetal\Slate\Choice: the Nav style needs an icon per label |
Choice: more than 41 items with icons (63 without) |
\Error |
Baremetal\Slate\Choice: too many parts |
Choice: an icon not an absolute .sli or .png path |
\ValueError |
Baremetal\Slate\Choice::$icons must hold absolute paths ending in .sli or .png |
SettingRow: $w outside 1..32767 |
\ValueError |
Baremetal\Slate\SettingRow::$w must be between 1 and 32767 |
SettingRow: a $control that belongs to a group or a scene |
\LogicException |
Baremetal\Slate\Toggle already belongs to a group: remove() it from there first |
Dialog: $w outside 1..32767 |
\ValueError |
Baremetal\Slate\Dialog::$w must be between 1 and 32767 |
Dialog: $text with more than 100 lines |
\ValueError |
Baremetal\Slate\Dialog::$text must hold at most 100 lines |
Scene::open() of a dialog open already (in any scene, also while it closes) |
\Error |
Baremetal\Slate\Dialog is already open (the class of the object) |
add() of a Dialog to a scene or a group |
\Error |
Baremetal\Slate\Dialog is opened with Scene::open(), not added |
Dialog::buttons() with more than 100 buttons |
\ValueError |
Baremetal\Slate\Dialog::buttons(): at most 100 buttons |
ProgressRing: $r or $width outside 1..32767 |
\ValueError |
Baremetal\Slate\ProgressRing::$r must be between 1 and 32767 (the name given) |
ProgressBar: $w or $h outside 1..32767 |
\ValueError |
Baremetal\Slate\ProgressBar::$w must be between 1 and 32767 (the name given) |
ProgressRing, ProgressBar: $value not finite (INF, NAN; constructor or write) |
\ValueError |
Baremetal\Slate\ProgressRing::$value must be a finite number |
ProgressRing, ProgressBar, Spinner: $color outside 0..0xFFFFFF |
\ValueError |
Baremetal\Slate\Spinner::$color must be a color, 0xRRGGBB |
Spinner: $r outside 1..32767 |
\ValueError |
Baremetal\Slate\Spinner::$r must be between 1 and 32767 |
StepList: $w outside 1..32767 |
\ValueError |
Baremetal\Slate\StepList::$w must be between 1 and 32767 |
StepList: $steps empty, not a list or not all strings |
\ValueError |
Baremetal\Slate\StepList::$steps must be a non-empty list of strings |
StepList: more than 21 steps |
\ValueError |
Baremetal\Slate\StepList::$steps must hold at most 21 steps |
StepList: $active outside 0..count($steps) (constructor or write; the old value stays) |
\ValueError |
Baremetal\Slate\StepList::$active must be between 0 and 3 |
A write of StepList::$steps |
\Error |
Cannot modify readonly property Baremetal\Slate\StepList::$steps |
Slate::toast() with $ms less than 500 |
\ValueError |
Baremetal\Slate\Slate::toast(): ms must be at least 500 |
The controls are built with the slate-controls build option (default true): see
Effects and build options.