FontVariation

public object FontVariation

Set font variation settings.

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

Properties

Empty

public val Empty: Settings = Settings(emptyList())

An empty Settings instance.

Functions

Setting

public fun Setting(name: String, value: Float): 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

italic

public fun italic(value: Float): 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

opticalSizing

public fun opticalSizing(textSize: TextUnit): 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

slant

public fun slant(value: Float): 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

width

public fun width(value: Float): 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

weight

public fun weight(value: Int): 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

grade

public fun grade(value: Int): 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

Settings

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

Variation settings to configure a font with FontWeight and FontStyle

Parameters

Return

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

Members

Settings

public class Settings internal constructor(
        /** All settings, unique by [FontVariation.Setting.axisName] */
        public val settings: List<Setting>
    )

A collection of settings to apply to a single font.

Settings must be unique on Setting.axisName

Functions

merge

public fun merge(other: Settings?): Settings

Merges the given other settings into this Settings instance.

If there are duplicate axes, settings in other will override settings in this instance.

Parameters

merge

public fun merge(vararg overrides: Setting): Settings

Merges the given overrides into this Settings instance.

If there are duplicate axes, settings in overrides will override settings in this instance. Note that overrides itself must not contain duplicate axes.

Parameters

Throws: IllegalArgumentException

if overrides contains duplicate axes.

Setting

public sealed interface Setting

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

Properties

needsDensity

public val needsDensity: Boolean

True if this setting requires density to resolve

When false, may toVariationValue may be called with null or any Density

axisName

public val axisName: String

The font variation axis, such as 'wdth' or 'ital'

Functions

toVariationValue

public fun toVariationValue(density: Density?): Float

Convert a value to a final value for use as a font variation setting.

If needsDensity is false, density may be null

Parameters