Styles and states
Material's components have a look for each state (hovered, pressed, focused,
disabled...). Your own widgets can have the same. Under styles.<name> you
write a look, and for each property either one value or a value per state.
ThemeStates follows the mouse, focus and taps for you and hands the right
values to your widget.
spring:
flutter:
theme:
styles:
neon-chip:
padding: [12, 6]
radius: $shape.small
border:
default: $colors.outline
hovered: $colors.primary
selected: $colors.primary
fill:
default: transparent
selected: { color: $colors.primary, alpha: 12% }
text:
default: $colors.on-surface-variant
hovered: $colors.primary
disabled: { color: $colors.on-surface, alpha: 38% }
transition: 120ms ease-out
Properties
| Property | Type | Values | Default | What it does |
|---|---|---|---|---|
styles.<name> |
map | any name | none | One style. The name is read in any spelling: neon-chip, neonChip and neon_chip are the same |
styles.<name>.<property> |
value, or map of states | the value kinds below | none | One property of the style. Any property name is allowed; your widget decides what it reads |
styles.<name>.<property>.<state> |
value | default, hovered, focused, pressed, dragged, selected, scrolled-under, disabled, error |
none | The value of the property in that state |
styles.<name>.transition |
text | <duration> [<curve>] |
no animation | How long the values take to change when the state changes, and along which curve |
Value kinds
A value is typed by what it looks like, with the same rules as tokens:
| Kind | Written as | In Dart (StyleValues) |
|---|---|---|
| color | #FF40A0, deepPurple, $colors.primary, { color: $colors.primary, alpha: 12% } |
values.color('fill') |
| number | 14, 1.5 |
values.number('radius') |
| insets | a YAML list [12, 6], or 12, 6 |
values.insets('padding') |
| duration | 250ms, 1.5s, 2m, 1h, 0.5d |
values.duration('delay') |
| text | anything else | values.text('label') |
Insets are [all], [horizontal, vertical] or [left, top, right, bottom].
A list of three numbers, or of five or more, is an error. A number can be used
where insets are read and means the same on all sides.
A property that is a map must hold states only. A map with another key stops the start and lists the states.
One value, or a value per state
spring:
flutter:
theme:
styles:
field:
radius: 8 # the same in every state
border: # a value per state
default: $colors.outline
focused: $colors.primary
error: $colors.error
- A property with states must have a
default: the value when no other state applies. - Every state of a property has the same kind. A number next to insets is widened to insets. Mixing a color and a number is an error.
- A property you wrote for one state only is not an error as long as it has
a
default.
The transition
transition: <duration> [<curve>] animates the change between states. The
duration is a number with a unit (120ms, 0.2s, 1h) and may also be a
bare number of milliseconds. The curve is any named curve or four
numbers. Without a curve the change is
linear. Without transition the values change at once.
spring:
flutter:
theme:
styles:
tag:
fill: { default: transparent, hovered: '#33FFFFFF' }
transition: $motion.durations.fast ease-out
Colors, numbers, insets and durations blend smoothly between states. Text
switches halfway through the transition. Padding never goes negative, even
with a curve that overshoots (ease-out-back, elastic-out).
States
| State | When a widget is in it |
|---|---|
default |
None of the others applies, or the others have no value for this property |
hovered |
A mouse pointer is over it |
focused |
It has keyboard focus |
pressed |
The primary mouse button or a finger is down on it |
dragged |
It is being dragged |
selected |
It is selected (your selected argument) |
scrolled-under |
Content scrolls under it |
disabled |
It cannot be used (onPressed is null) |
error |
It is in error (your error argument) |
A widget can be in several states at once. For each property the strongest state that has a value wins, strongest first:
disablederrorpresseddraggedhoveredfocusedselectedscrolled-underdefault
So a selected chip that is hovered shows its hovered value if it has one,
else its selected value, else its default. Each property is decided on
its own; a property without a disabled value in a disabled widget falls
through to the next state that has one.
ThemeStates sets hovered, focused, pressed, disabled, selected
and error. dragged and scrolled-under are never set by it; they are for
code that calls StateStyle.resolve with its own set of states.
ThemeStates
ThemeStates is the widget that does the work.
ThemeStates(
style: context.theme.styles.neonChip,
selected: selected,
onPressed: onPressed, // null: the chip is disabled
builder: (context, s) => Container(
padding: s.padding, // EdgeInsets
decoration: BoxDecoration(
color: s.fill, // Color
borderRadius: BorderRadius.circular(s.radius),
border: Border.all(color: s.border),
),
child: Text(label, style: TextStyle(color: s.text)),
),
)
| Argument | Type | Default | What it does |
|---|---|---|---|
style |
ThemeStyle |
required | The style: context.theme.styles.<name> (generated) or a StateStyle |
builder |
function | required | Builds the child from the values of the current state |
selected |
bool | false |
Whether the widget is selected |
error |
bool | false |
Whether the widget is in error |
onPressed |
callback | none | Called on a tap, a click, Enter or Space. null disables the widget |
focusNode |
FocusNode |
its own | The focus node to use |
autofocus |
bool | false |
Take focus when first shown |
mouseCursor |
MouseCursor |
click (basic when disabled) | The cursor over the widget |
showFocusAlways |
bool | false |
Show focused whatever way the focus came (a tap or click too), not only with the keyboard. Turn it on for a text input, whose frame must light up when the user taps it. Buttons leave it off, as Flutter does |
It follows the mouse, focus and pressing, handles Enter and Space, sets the
cursor, and blends the values over transition. When the device asks for
less motion (MediaQuery.disableAnimations) the values change at once.
The generated classes
With the generator, a styles.<name> becomes the class AppStyle<Name> and
its values the class AppStyle<Name>Values, so a style called text or
button never hides Flutter's TextStyle or ButtonStyle. The values class
has a typed getter per property (Color fill, double radius,
EdgeInsets padding, Duration delay, String label). A property must
have one kind in every theme and every state; otherwise the build fails and
names both places.
context.theme.styles.neonChip; // AppStyleNeonChip, a ThemeStyle<AppStyleNeonChipValues>
Without the generator, read a style by name:
final style = SpringTheme.of(context).styles['neonchip']!; // StateStyle
final values = style.resolve({WidgetState.hovered});
values.color('fill');
Per-state values in components
The component themes of a Material app (read by
spring_boot_starter_flutter_material) take the same maps of states, with
the same states and the same order, for what Flutter models per state: the
fill of a button, the side of an outlined button, the fill of a checkbox.
How they are written and which properties take states is in
component themes.
Markdown and code: styles.code
MarkdownView (and the navigation's RouteContentView, which shows a
route's Markdown) takes its look from the theme: the headings from
headline-* and title-*, the text from body-large, links from
colors.primary. Code, inline and in fenced blocks, uses the code text
style (typography.code) and the colors of the style styles.code:
spring:
flutter:
theme:
typography:
code: { font-family: JetBrains Mono, size: 13 }
styles:
code:
background: $colors.surface-container-low
text: $colors.on-surface
keyword: '#C678DD' # final, class, true
string: '#98C379' # 'text', "text"
comment: '#5C6370' # // and #
number: '#D19A66' # 42, 1.5
key: '#E06C75' # YAML and .properties keys
annotation: '#61AFEF' # @Service
variable: '#E5C07B' # $colors.primary, ${PORT}, &anchor
type: '#56B6C2' # String, Basket, int
punctuation: '#ABB2BF' # { } [ ] , : -
| Property | Default | Colors |
|---|---|---|
background |
$colors.surface-container-highest |
The block's fill and inline code's background |
text |
the code text style's color |
Everything not listed below |
keyword |
$colors.primary |
Keywords, true / false / null |
string |
$colors.tertiary |
Strings, and YAML and .properties values without quotes (ease-out) |
comment |
$colors.outline |
Comments |
number |
$colors.secondary |
Numbers, with a unit too (120ms, 1.5s, 35%) |
key |
$colors.primary |
Keys of YAML, .properties and JSON; options of a shell command (--port) |
annotation |
$colors.secondary |
Annotations, YAML tags (!include) |
variable |
$colors.on-tertiary-container |
References and placeholders: $colors.primary, ${PORT}, a shell's $HOME, YAML anchors and aliases (&base, *base) |
type |
$colors.on-secondary-container |
Dart types: String, Basket, int |
punctuation |
$colors.on-surface-variant |
Brackets, braces, commas, colons, a list's dash |
inline-text |
the code text style's color |
Inline code (`@Bean()`) |
inline-background |
background |
Inline code's background |
header |
background |
The header of a block with a title |
title |
$colors.on-surface-variant |
A block's title and its copy button |
The block itself takes four more properties:
| Property | Default | Meaning |
|---|---|---|
padding |
12 |
Insets inside the block: 16, [16, 12] |
radius |
6 |
Corner radius |
border |
none | Border color |
border-width |
1 |
Border width, when border is set |
copy |
true |
A button that copies the block's text: in the header of a block with a title=, in the corner of the others; false for none |
Every property is optional; without styles.code the code follows the
color scheme, so it fits every theme already. A theme of themes.<name>
overrides only the colors it writes, like any other key.
A fenced block names its language after the backticks (```dart). The
starter knows no language by itself: what the code is made of comes from
the theme's syntax.<language> (next section). A block in a language no
theme has is shown in the text color.
The languages of code: syntax
syntax.<language> splits code into the pieces styles.code colors. A
language is a list of rules, each a regular expression and the kind of
what it matches, tried in order at each position of the code; the first
that matches makes a piece:
spring:
flutter:
theme:
syntax:
java:
aliases: [jav] # other names in a fenced block
keywords: [class, public, return, new, 'true', 'false', 'null']
types: '^[A-Z][A-Za-z0-9_]*[a-z]' # a word that is a type name
rules:
- { match: '//[^\n]*|/\*[\s\S]*?\*/', kind: comment }
- { match: '"(?:\\.|[^"\\\n])*"', kind: string }
- { match: '@[A-Za-z_][\w.]*', kind: annotation }
- { match: '\b\d+(?:\.\d+)?\b', kind: number }
- { match: '[A-Za-z_$][\w$]*', kind: word }
- { match: '[{}()\[\];,]', kind: punctuation }
| Property | Meaning |
|---|---|
rules |
Required. Each { match, kind }. match is a regular expression, taken as written (no $ reference); ^ and $ are a line's start and end. kind is comment, string, annotation, number, key, keyword, type, variable, punctuation, plain, or word |
keywords |
The words a word rule colors as keyword. Quote 'true', 'false' and 'null', which YAML reads as values |
types |
A regular expression: a word of a word rule that matches it is a type |
aliases |
Other names of the language in a fenced block (yml for yaml) |
What no rule matches is plain text. An invalid rule (an unknown kind, a regular expression that does not compile, a language without rules) stops the start and names the property.
Languages from a URL
You rarely write a language yourself. The repository
farum-azula/themes has Dart,
Java, YAML, properties, shell and JSON in one file; download it for every
theme of the app with source on spring.flutter.theme itself (see
a theme from a URL):
spring:
flutter:
theme:
source: github:farum-azula/themes/themes/[email protected]
themes:
neon:
syntax:
java: { ... } # a theme may still replace one language
The downloaded values are shared by every theme and lie under your own
files: a syntax.<language> you write wins.
MarkdownView(text, onLink: (href) => launchUrl(Uri.parse(href)));
MarkdownView.resource('resources:content/docs/beans.md');
const MarkdownView.code('server:\n port: 8080', language: 'yaml'); // one block
A fenced block with a title after its language gets a header with the
title and a button that copies the code:
```dart title="lib/orders.dart"
@Service()
class OrderService { ... }
```
Links take styles.link.color ($colors.primary by default).
Headings take the sizes of the typography (# is headline-large, ##
headline-medium, ### headline-small, then title-large,
title-medium, title-small) and the color of styles.heading:
color for every level, h1 ... h6 for one level. Without it they are
in the text's color.
styles:
heading:
color: $colors.primary # every heading
h1: $colors.on-surface # but # in the text's color
A table's column is as wide as its text, up to styles.table.cell-width
(280 by default), where the text wraps. A table wider than the view
scrolls sideways instead of squeezing its columns, so it reads on a phone.
A table narrower than the view widens its columns to the view's width, so
it lines up with the text around it; fill: false keeps it as wide as its
text.
styles:
table:
cell-width: 240
fill: true # the default
Callouts
GitHub's callouts are boxes in their kind's color, with the kind's name as a title:
> [!WARNING]
> A missing bean stops the start.
The kinds are note, tip, important, warning and caution; their
colors are styles.callout.<kind> (by default primary, tertiary,
secondary, error, error), and the titles the messages
markdown.alert.<kind> (Note, Tip, ... without them), so a
messages_ja.properties translates them:
styles:
callout:
note: $colors.secondary
warning: '#FF5C7A'
The page's headings
MarkdownOutline gets the headings of the page a MarkdownView (or the
navigation's RouteContentView) shows, each with GitHub's anchor
(## Bean methods is #bean-methods), for an "On this page" list;
show(id) scrolls to one. A link to #id in the page scrolls by itself,
and an address with an anchor (/docs/beans#scopes) opens at its heading.
final outline = MarkdownOutline();
RouteContentView(outline: outline);
ListenableBuilder(
listenable: outline,
builder: (context, _) => Column(children: [
for (final heading in outline.headings.where((h) => h.level == 2))
TextButton(
onPressed: () => outline.show(heading.id),
child: Text(heading.text),
),
]),
);
Languages of resources
MarkdownView.resource('resources:content/beans.md') shows
beans.ja.md instead when the app's language is Japanese and the file
exists, and changes with the language.
MarkdownView.code shows a single block of code exactly as a fenced block
of a Markdown page, so every code sample of an app shares one look. The
text can be selected; outside a MaterialApp (a CupertinoApp, a
WidgetsApp) the selection has no menu.
See also
- Tokens and references: how values are typed and referenced
- Motion and animations: curves and durations
- Shape, spacing and elevation
- Component themes: values per state in Material's components
- Typography: the
codetext style