Theme background
A theme can have a background: a base color, an image, something painted over the image (a color or a gradient), and a slow movement of the image. The app paints it behind every screen. A theme switch or a new image cross-fades. One screen (a login screen, say) can have its own background.
spring:
flutter:
theme:
animations:
background-drift:
duration: 40s
curve: ease-in-out
repeat: reverse
background:
color: $colors.surface-container-lowest
image:
source: https://cdn.example.com/neon/background.jpg
fallback: assets/images/background.jpg
refresh: 1d
fit: cover
alignment: center
opacity: 0.9
blur: 4
overlay:
color: '#330A0C12'
gradient:
type: linear
begin: top
end: bottom
colors: [transparent, '#CC0A0C12']
stops: [0, 1]
animation: background-drift
effect: drift
transition: 400ms ease-out
screens:
login:
image:
source: assets/images/login.jpg
blur: 0
overlay:
color: '#66000000'
Properties
A theme has no background unless it has at least one key under background.
Any other key stops the start and lists the valid ones.
The background
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
background.color |
color | any color | the theme's surface |
The base layer under everything else. It also shows while the image loads |
background.image |
map | the image keys below | none | A picture painted over the color |
background.overlay |
map | color, gradient |
none | What is painted over the image |
background.animation |
text | the name of an animations.<name> |
none | The animation that moves the image |
background.effect |
enum | drift, zoom, pulse |
drift when animation is set |
How the image moves |
background.transition |
text | <duration> [<curve>], such as 400ms ease-out |
300ms ease-out |
The cross-fade when the background changes |
background.frame-rate |
number or every-frame |
over zero | 15 |
How many times a second the moving image is drawn again |
background.screens.<name> |
map | the keys above except screens |
none | A background for one screen. See per-screen backgrounds |
The image
background.image takes every key of an image (source,
refresh, source-sha256, headers, timeout, fallback, allow-http)
and four keys about how the picture fills the screen.
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
source |
text | an asset path, an https URL, an http URL with allow-http |
required | The picture. See images for the download, cache and refresh keys |
fit |
enum | cover, contain, fill, fit-width, fit-height, none, scale-down |
cover |
How the picture fills the screen |
alignment |
alignment | see below | center |
Which part of the picture stays in view |
opacity |
number | 0 to 1 |
1 |
How opaque the picture is. The color shows through the rest |
blur |
number | 0 or more |
0 |
How much the picture is blurred (a Gaussian blur of that radius in logical pixels). 0 is sharp |
Values of fit:
| Value | What it does |
|---|---|
cover |
Fills the screen and keeps the shape, cropping what does not fit |
contain |
Shows the whole picture inside the screen, keeping its shape, and leaves empty space |
fill |
Stretches the picture to the screen, changing its shape |
fit-width |
Makes the width match the screen; the height may be cropped or short |
fit-height |
Makes the height match the screen; the width may be cropped or short |
none |
Shows the picture at its own size |
scale-down |
Like contain, but never makes the picture bigger than its own size |
Values of alignment:
| Value | Position |
|---|---|
center |
Centre |
top or top-center |
Top edge, centre |
bottom or bottom-center |
Bottom edge, centre |
left or center-left |
Left edge, centre |
right or center-right |
Right edge, centre |
top-left, top-right, bottom-left, bottom-right |
The corners |
x, y |
Two numbers from -1 (left or top) to 1 (right or bottom); 0, 0 is the centre, 0, -0.5 is half way to the top |
fit and alignment matter when the picture and the screen have different
shapes. With cover, alignment: top keeps the top of the picture.
The overlay
An overlay is painted over the image, so text stays readable. It can have a
flat color, a gradient, or both (the gradient is on top).
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
overlay.color |
color | any color, with alpha | none | A flat color over the whole screen. Use a color with some transparency ('#330A0C12', { color: $colors.scrim, alpha: 30% }) |
overlay.gradient.type |
enum | linear, radial |
linear |
The kind of gradient |
overlay.gradient.begin |
alignment | same as alignment |
top (linear), center (radial) |
Where a linear gradient starts. For a radial gradient it is the centre |
overlay.gradient.end |
alignment | same as alignment |
bottom |
Where a linear gradient ends. A radial gradient does not use it: giving end with type: radial stops the start ("radial uses begin as its center") |
overlay.gradient.colors |
list of colors | at least two | required | The colors, from begin to end (or from the centre outwards) |
overlay.gradient.stops |
list of numbers | 0 to 1, as many as colors |
even spacing | Where each color sits along the gradient |
A radial gradient has a radius of 0.8 of the screen's shorter side.
colors and stops are YAML lists or one comma-separated value. A list of
fewer than two colors, or stops with a different length than colors, stops
the start.
spring:
flutter:
theme:
background:
color: '#0A0C12'
overlay:
gradient:
type: radial
begin: top-right
colors: ['#33FF40A0', transparent]
The painting order
From the back to the front: color, the image (blurred, with its opacity),
overlay.color, overlay.gradient. Only the image moves when there is an
animation; the color and the overlay stay still.
Animation and effect
animation names an entry of animations
of the same theme; a name that is not one stops the start and lists the
animations (an animation of this theme must exist). It gives the speed, the
curve and the repeat. effect says what the image does with the progress t
that goes from 0 to 1:
| Effect | What the image does |
|---|---|
drift |
The image is made 12% larger, so no edge shows, and slides slowly to and fro: up to 4% of the width across and 2% of the height up and down |
zoom |
The image grows from its normal size to 12% larger |
pulse |
The image fades a little in and out: between 70% and 100% of its opacity |
Notes:
effectneeds ananimationnext to it: without one the start fails and says so. Withanimationand noeffect, it isdrift.- Without an
image, there is nothing to move. - With
repeat: loopthe movement jumps back at the end of a run; withrepeat: reverseit goes there and back smoothly, which suits a background. A longduration(30 seconds or more) keeps it calm. - When the device asks for less motion, the image stands still.
The frame rate
A moving background is the whole screen: each time it moves, everything on the screen is drawn again. A drift of 40 seconds moves the image a pixel or two a second, so drawing it at every frame (60 or 120 a second) keeps the screen repainting while nothing else changes. On the web this takes the time scrolling needs and the battery.
frame-rate is how many times a second the image moves on: 15 by default,
which a slow drift cannot tell from every frame. Between two of its steps
the screen is not drawn for the background. every-frame moves it at every
frame of the screen, for a fast animation:
background:
animation: background-drift
effect: drift
frame-rate: 10 # or every-frame
The transition
transition is the cross-fade when the background changes: a theme switch,
a new image from the network, or a changed color. It is a duration and an
optional curve: 400ms ease-out,
1s, 250ms linear. The default is 300ms ease-out. When the device asks
for less motion, there is no fade.
A new network image is loaded first and fades in over the old one, so there is never an empty flash.
Per-screen backgrounds
background.screens.<name> changes the background for the screen with that
name. It uses the same keys, except screens.
spring:
flutter:
theme:
background:
color: $colors.surface
image: { source: assets/images/main.jpg, opacity: 0.8 }
screens:
login:
image: { source: assets/images/login.jpg }
settings:
image: { blur: 12 } # same picture as the theme's, blurred
overlay: { color: '#80000000' }
A screen starts from the theme's background and changes what it writes:
color,animation,effectandtransitionreplace the theme's.imagegoes over the theme's image key by key: a screen can write onlyblurand keep the theme's picture. A screen with no theme image must give asource; otherwise the start stops.overlayreplaces the theme's overlay as a whole. It is not merged.
Names are compared without case, - and _.
Show it
SpringApp (that is, SpringApplicationWidget) puts the background around
the app's navigator when the active theme has one, so every screen shows it.
To make that visible it also makes the Material scaffold (in a
MaterialApp, with spring_boot_starter_flutter_material) and the Cupertino page (in a CupertinoApp,
with spring_boot_starter_flutter_cupertino) background transparent for a theme with a background. A
Cupertino theme that sets cupertino.scaffold-background-color keeps its
color.
Three widgets give a screen control:
// The theme's background (this is what the app itself uses).
ThemeBackground(child: const HomePage());
// background.screens.login over the theme's own. A name the theme does not
// list throws a FlutterError in debug (it lists the screens the theme has,
// and the closest name); in release it shows just the child.
ThemeBackground.screen('login', child: const LoginForm());
// A plain surface-colored background that hides the theme's one.
ThemeBackground.none(child: const ReaderPage());
Read the values in Dart with context.theme.background. It is a
ThemeBackgroundData?, null in a theme without a background:
final bg = context.theme.background;
bg?.color; // Color?
bg?.screen('login'); // the login screen's resolved background
A theme without a background has opaque scaffolds again. If a theme switch adds or removes the background, the screens keep their state.
See also
- Images: every image key, the cache and the refresh
- Motion and animations:
animations.*and curves - Colors:
alphafor the overlay - Properties