ext-slate · PHP API
Effects and build options
Gradients, drop shadows and group blur, each built only when the slate-effects option lists it; slate-images chooses the image formats decoded on the board; slate-controls builds the theme and the controls; slate-debug builds the profiler.
Gradients
LinearGradient::__construct(array $stops, float $angle = 0.0)
RadialGradient::__construct(array $stops, float $cx = 0.5, float $cy = 0.5, float $r = 0.5)
A gradient fills $fill of a RoundRect or a Circle, or $color of an Arc. $stops holds 2 to 16 stops
[position, color] or [position, color, alpha], positions from 0 to 1 (Slate sorts them), colors 0xRRGGBB
(opaque) or 0xAARRGGBB. The third value, from 0.0 (transparent) to 1.0 (opaque), replaces the color's alpha:
it is the way to write a fully transparent stop, [1.0, 0xFFFFFF, 0.0]. Colors are interpolated
premultiplied, so a fade to transparent keeps its hue, and dithered, so a slow ramp does not band.
Both are immutable (readonly properties $stops, $angle, $cx, $cy, $r) and extend the abstract
Gradient; one gradient can fill several elements.
LinearGradient: across the element's box,$anglein degrees, 0 left to right, 90 top to bottom.RadialGradient: centre ($cx,$cy) and radius$ras fractions of the box (an ellipse on a box that is not square).
For an Arc the box is the one of its whole circle, so the gradient does not move when the arc grows.
$card = new RoundRect(20, 20, 320, 120, radius: 16,
fill: new LinearGradient([[0.0, 0x202830], [1.0, 0x405060]], angle: 90));
$ring = new Arc(180, 180, 100, -90, 180, 12,
new LinearGradient([[0.0, 0x40E0A0], [1.0, 0xE0A040]]));
$glow = new Circle(180, 180, 80,
fill: new RadialGradient([[0.0, 0x80FFFFFF], [1.0, 0xFFFFFF, 0.0]])); // white glow fading out
Shadows
Shadow::__construct(int $dx, int $dy, int $blur, int|float $color)
A drop shadow for $shadow of a RoundRect, a Circle or a Group: offset ($dx, $dy) in pixels, $blur
in pixels and a color, usually translucent (0x80000000). A shape's shadow follows its outline (like CSS
box-shadow); a group's shadow follows the content it draws (like CSS drop-shadow). An element with a shadow
is drawn through a cache (see Performance).
Blur
$blur of a Group, in pixels: the group is composed apart, blurred and kept in a cache. Use it for a frosted
panel behind a dialog, or to soften what is behind a popup.
How blur is measured
$blur of Shadow and Group means what it means in CSS: how far the softness reaches, in pixels. Slate blurs
with three passes of a box blur of radius r = round(blur / 3) (at least 1 when blur is greater than 0), so
the softness reaches about 3r pixels past the shape and looks like a gaussian blur of about r + 0.5 pixels.
The range is 0 to 765.
Build options
Set in extra.baremetal.options of the project:
| Option | Values | Default |
|---|---|---|
slate-effects |
a list of gradients, shadows, blur |
all three |
slate-images |
a list of png |
png |
slate-controls |
true or false |
true |
slate-debug |
true or false |
false |
An effect that is not in slate-effects is not compiled into the firmware (it saves its code), and the PHP
that would use it throws \ValueError:
| Effect left out | What throws | Message |
|---|---|---|
gradients |
new LinearGradient(...), new RadialGradient(...) |
gradients is not built in: add it to slate-effects in composer.json |
shadows |
new Shadow(...) |
shadows is not built in: add it to slate-effects in composer.json |
blur |
$group->blur = 6 (any value above 0) |
blur is not built in: add it to slate-effects in composer.json |
slate-images lists the image formats decoded on the board. .sli images are always supported: they are what
phpbm makes of the project's PNG assets (see Images). With png (the default) a .png path is
decoded on the board too; without it the PNG decoder is not compiled (about 15 to 20 KB of firmware saved), and a
.png path throws \ValueError png is not built in: add it to slate-images in composer.json (in new Image,
a write of $src and Images::preload()). A project whose images are all assets can leave it out:
"slate-images": [].
slate-controls builds the theme and the controls. With false they are not
compiled, and their classes are absent: Theme, Size, Variant, Shape, ChoiceStyle, Control, Button,
Toggle, Slider, Choice, SettingRow, Dialog, ProgressRing, ProgressBar, Spinner, StepList,
Slate::theme(), Slate::$theme, Slate::toast() and Scene::open() do not exist. A project that draws only
with the elements saves their code: about 54 KB of firmware on the esp32 SDK (see
Performance). The rest of Slate works the same.
slate-debug builds the profiler: the frames per second on screen and a line of timings per second on the
console (see Debug). Without it the profiler is not compiled.
{
"extra": {
"baremetal": {
"options": {
"slate-effects": ["gradients", "shadows"],
"slate-debug": true
}
}
}
}
An empty list ("slate-effects": []) builds none of them.
Related
- Elements API
- Images API
- Performance API
- Debug API