DesignLabelCheck class

Whether the words and the icon each control on a screen shows sit on the middle of its face, up and down, as they are drawn, and a chosen control's fill fills its cell.

It needs no list of controls. Every control on the screen (a button, a link, a toggle, a field, or anything with a tap action) that draws a face and holds one line of words, an icon, or both on one line is checked, so a control no DesignAlignmentMatrix row names (a split button, a gallery page's own) is checked too. The face is read as DesignKeylineCheck reads it: the largest box inside the control that paints, not its tap box or a shadow outside it. Left out: a control without a face (a text button), one whose words run to a second line or that holds two lines (a title and a subtitle), one holding a text entry (DesignTextEntryCheck checks those), a label inside a smaller face of its own within the control (a badge), and a label more than a quarter of its face's height from its middle, which is placed there, not centred (a tappable card's title).

A label is read by its capitals, never its ink's bounds, so its descenders ("Spending", "Light") do not count: its baseline where the engine draws it, and their height from the DesignCapCenter around it, else read from its capitals flat on the cap height (B, E, H; not V or Y, whose middles meet their arms below it), else the height its style shows on the screen (every line in one family, weight, slant and size takes the one height, read from its first line with a flat-topped capital, else a round one, else any), else the usual cap height (0.7 of its font size). A line of figures alone (a day, a count) is read by its figures likewise, which need not stand at the capitals' height. An icon is read by its ink, and so is a painted mark that starts the row of a control's words (what a custom paint holding no words draws before them: a way back's triangle), which is never placed, however far off: a button "Back": its painted mark, before its words, is 6 px above the middle of its face as drawn. Each middle is set against the face's (a face drawn as a rule along one side, a list row's foot, lays its content out inside the rule: its middle is that of the band inside it), but for a label beside a text entry of more than one line (a note field, a composer that grows), which stands on the entry's first line: it is set against the capitals of that line, read as a label's are. Words over or under a picture on the face (an icon tile's name under its image or painted glyph) are placed there, not centred, and are not read. The engine draws a line's baseline on a whole pixel, which moves it up to half a pixel from where it was laid out; the check holds what was laid out to tolerance and names both: a button "Share": the label "Share" is 0.5 px above the middle of its face as laid out, 1 px above as drawn. A line holding a widget (a shortcut's key) is read from its capitals' pixels, top and bottom, and held as drawn, the engine's rounding allowed.

A chosen control's ground fills the cell a person sees, not a marker behind its words. A control chosen (selected, toggled on or checked) among controls of its kind beside or over it, none of which shows a face of its own unchosen (a toggle group's cells in a trough, a drawer's destinations), has for its cell the slot the layout holding them gives it (a drawer's row, however tight its pressable). Its fill is the colour its words stand on (its own, or drawn over it from beside it in the slot), where that differs from what is round the cell, read out to where the colour ends (a gradient or a sheen followed, words and icons gone round). It may stand short of the cell's width or height by a quarter of the cell's height (a thumb's inset in its track), and a mark as wide as it is tall (a calendar day's round mark) is the cell the eye sees: a switch "Bold": its chosen fill is 61 by 20 px in its cell of 110 by 44; the chosen ground fills the cell, to 11 px short. Chips and cards, whose unchosen faces are their cells, and a tab's line or a navigation bar's mark beside its words, which no fill holds, are not read.

Before the check, a test loads every font family the look ships (each family in the package's FontManifest.json: a family left out is drawn in the test's own font, whose missing glyph stands on the baseline) and lets the screen's images decode, then draws the frame they land in (a check that meets a screen repainted since its last frame says so and stops):

await tester.runAsync(() => Future.wait([
  for (final e in find.byType(Image).evaluate())
    precacheImage((e.widget as Image).image, e),
]));
await tester.pump();

(A DecorationImage's image is decoded the same way.) Only what is painted is read: an IndexedStack's other children, an Offstage's while off stage, a fully transparent Opacity's, a Transform's scaled to nothing, a Visibility's kept state and a list's rows laid out past what it shows (its cache extent, a wheel's hidden items) are laid out but not on screen, and the rest of the screen is read without them. A control whose text is drawn in the test's own font (its letters solid boxes of the words' one colour; a gradient under real words is not that) fails the whole check once, with that reason, instead of with an offset for each.

A test pumps a screen (a gallery page, an app screen), then:

final report = await const DesignLabelCheck(look: 'Comic').check(
  tester.element(find.byType(SettingsScreen)),
  runAsync: tester.runAsync,
);
report.verify();

Run it under every density the look ships (standard and compact): a control can be centred under one and not the other. A split button whose trailing half keeps a 40 px minimum while compact density takes the leading half's content to 32 sits that label 4 px above its face's middle, and only under compact. checkDensities pumps the screen under each and names the density with each problem:

final report = await const DesignLabelCheck(look: 'Comic').checkDensities(
  densities: densities,
  screen: (context) => const SettingsScreen(),
  pump: tester.pumpWidget,
  runAsync: tester.runAsync,
);
report.verify();
Annotations

Constructors

DesignLabelCheck({required String look, double tolerance = 0.75, double? drawnTolerance, double pixelRatio = 3})
A check for look.
const

Properties

drawnTolerance → double?
How far, in device pixels at pixelRatio, a one-line label's capitals may be drawn from its face's middle; null (the default): not held.
final
hashCode → int
The hash code for this object.
no setterinherited
look → String
The look's name, for messages.
final
pixelRatio → double
The scale the screen is drawn at to read its pixels.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
tolerance → double
How far, in logical pixels, a label's or an icon's ink may sit from its face's middle as laid out (the engine's whole-pixel baseline aside).
final

Methods

check(BuildContext context, {Future<T?> runAsync<T>(Future<T> work())?}) → Future<DesignAlignmentReport>
Checks every control under context (on screen, under a repaint boundary as every route is). A test passes its tester's runAsync (reading pixels takes real time); null reads them directly.
checkDensities({required Map<String, DesignAlignmentTheme> densities, required WidgetBuilder screen, required Future<void> pump(Widget widget), required Future<T?> runAsync<T>(Future<T> work())}) → Future<DesignAlignmentReport>
Puts screen on screen under each of densities and checks it as check does, each problem led by the density's name: compact · a button "Share": the label "Share" is 4 px above ….
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited