FontVariation


Set font variation settings.

To learn more about the font variation settings, see the list supported by fonts.google.com.

Summary

Nested types

Represents a single point in a variation, such as 0.7 or 100

A collection of settings to apply to a single font.

Public functions

FontVariation.Setting
Setting(name: String, value: Float)

Create a font variation setting for any axis supported by a font.

Cmn
FontVariation.Settings
Settings(
    weight: FontWeight,
    style: FontStyle,
    vararg settings: FontVariation.Setting
)

Variation settings to configure a font with FontWeight and FontStyle

Cmn
FontVariation.Setting
grade(value: Int)

Change visual weight of text without text reflow.

Cmn
FontVariation.Setting
italic(value: Float)

Italic or upright, equivalent to FontStyle

Cmn
FontVariation.Setting

Optical size is how "big" a font appears to the eye.

Cmn
FontVariation.Setting
slant(value: Float)

Adjust the style from upright to slanted, also known to typographers as an 'oblique' style.

Cmn
FontVariation.Setting
weight(value: Int)

Weight, equivalent to FontWeight

Cmn
FontVariation.Setting
width(value: Float)

Width of the type.

Cmn

Public functions

Setting

fun Setting(name: String, value: Float): FontVariation.Setting

Create a font variation setting for any axis supported by a font.

val setting = FontVariation.Setting('wght', 400f);

You should typically not use this in app-code directly, instead define a method for each setting supported by your app/font.

If you had a setting fzzt that set a variation setting called fizzable between 1 and 11, define a function like this:

fun FontVariation.fizzable(fiz: Int): FontVariation.Setting {
require(fiz in 1..11) { "'fzzt' must be in 1..11" }
return Setting("fzzt", fiz.toFloat())
Parameters
name: String

axis name, must be 4 characters

value: Float

value for axis, not validated and directly passed to font

Settings

fun Settings(
    weight: FontWeight,
    style: FontStyle,
    vararg settings: FontVariation.Setting
): FontVariation.Settings

Variation settings to configure a font with FontWeight and FontStyle

Parameters
weight: FontWeight

to set 'wght' with weight\(FontWeight.weight)

style: FontStyle

to set 'ital' with italic\(FontStyle.value)

vararg settings: FontVariation.Setting

other settings to apply, must not contain 'wght' or 'ital'

Returns
FontVariation.Settings

settings that configure FontWeight and FontStyle on a font that supports 'wght' and 'ital'

grade

fun grade(value: Int): FontVariation.Setting

Change visual weight of text without text reflow.

Finesse the style from lighter to bolder in typographic color, without any changes overall width, line breaks or page layout. Negative grade makes the style lighter, while positive grade makes it bolder. The units are the same as in the Weight axis.

Visual appearance of text with weight and grade set is similar to text with

weight = (weight + grade)
Parameters
value: Int

grade, in -1000..1000

italic

fun italic(value: Float): FontVariation.Setting

Italic or upright, equivalent to FontStyle

'ital', 0.0f is upright, and 1.0f is italic.

A platform may provide automatic setting of ital on font load. When supported, ital is automatically applied based on FontStyle if platform and the loaded font support 'ital'.

Automatic mapping is done via Settings\(FontWeight, FontStyle\)

To override this behavior provide an explicit FontVariation.italic to a Font that supports variation settings.

Parameters
value: Float

0.0f, 1.0f

opticalSizing

fun opticalSizing(textSize: TextUnit): FontVariation.Setting

Optical size is how "big" a font appears to the eye.

It should be set by a ratio from a font size.

Adapt the style to specific text sizes. At smaller sizes, letters typically become optimized for more legibility. At larger sizes, optimized for headlines, with more extreme weights and widths.

A Platform may choose to support automatic optical sizing. When present, this will set the optical size based on the font size.

To override this behavior provide an explicit FontVariation.opticalSizing to a Font that supports variation settings.

Parameters
textSize: TextUnit

font-size at the expected display, must be in sp

slant

fun slant(value: Float): FontVariation.Setting

Adjust the style from upright to slanted, also known to typographers as an 'oblique' style.

Rarely, slant can work in the other direction, called a 'backslanted' or 'reverse oblique' style.

'slnt', values as an angle, 0f is upright.

Parameters
value: Float

-90f to 90f, represents an angle

weight

fun weight(value: Int): FontVariation.Setting

Weight, equivalent to FontWeight

Setting weight always causes visual text reflow, to make text "bolder" or "thinner" without reflow see grade

Adjust the style from lighter to bolder in typographic color, by varying stroke weights, spacing and kerning, and other aspects of the type. This typically changes overall width, and so may be used in conjunction with Width and Grade axes.

This is equivalent to FontWeight, and platforms may support automatically setting 'wghts' from FontWeight during font load.

Setting this does not change FontWeight. If an explicit value and FontWeight disagree, the weight specified by wght will be shown if the font supports it.

Automatic mapping is done via Settings\(FontWeight, FontStyle\)

Parameters
value: Int

weight, in 1..1000

width

fun width(value: Float): FontVariation.Setting

Width of the type.

Adjust the style from narrower to wider, by varying the proportions of counters, strokes, spacing and kerning, and other aspects of the type. This typically changes the typographic color in a subtle way, and so may be used in conjunction with Width and Grade axes.

'wdth', such as 10f

Parameters
value: Float

0.0f represents the width