{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

FontVariation

public static class FontVariation


Set font variation settings.

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

Summary

Nested types

public sealed interface FontVariation.Setting

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

public final class FontVariation.Settings

A collection of settings to apply to a single font.

Public fields

static @NonNull FontVariation

Public methods

final @NonNull FontVariation.Setting
Setting(@NonNull String name, float value)

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

final @NonNull FontVariation.Settings
Settings(
    @NonNull FontWeight weight,
    @NonNull FontStyle style,
    @NonNull FontVariation.Setting settings
)

Variation settings to configure a font with FontWeight and FontStyle

final @NonNull FontVariation.Setting
grade(int value)

Change visual weight of text without text reflow.

final @NonNull FontVariation.Setting
italic(float value)

Italic or upright, equivalent to FontStyle

final @NonNull FontVariation.Setting

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

final @NonNull FontVariation.Setting
slant(float value)

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

final @NonNull FontVariation.Setting
weight(int value)

Weight, equivalent to FontWeight

final @NonNull FontVariation.Setting
width(float value)

Width of the type.

Public fields

INSTANCE

public static @NonNull FontVariation INSTANCE

Public methods

Setting

public final @NonNull FontVariation.Setting Setting(@NonNull String name, float value)

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
@NonNull String name

axis name, must be 4 characters

float value

value for axis, not validated and directly passed to font

Settings

public final @NonNull FontVariation.Settings Settings(
    @NonNull FontWeight weight,
    @NonNull FontStyle style,
    @NonNull FontVariation.Setting settings
)

Variation settings to configure a font with FontWeight and FontStyle

Parameters
@NonNull FontWeight weight

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

@NonNull FontStyle style

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

@NonNull FontVariation.Setting settings

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

Returns
@NonNull FontVariation.Settings

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

grade

public final @NonNull FontVariation.Setting grade(int value)

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
int value

grade, in -1000..1000

italic

public final @NonNull FontVariation.Setting italic(float value)

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
float value

0.0f, 1.0f

opticalSizing

public final @NonNull FontVariation.Setting opticalSizing(@NonNull TextUnit textSize)

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
@NonNull TextUnit textSize

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

slant

public final @NonNull FontVariation.Setting slant(float value)

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
float value

-90f to 90f, represents an angle

weight

public final @NonNull FontVariation.Setting weight(int value)

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
int value

weight, in 1..1000

width

public final @NonNull FontVariation.Setting width(float value)

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
float value

0.0f represents the width