Font¶

A representation of a font.

Availability (Key)

macOS	Linux (GTK)	Linux (Qt)	Windows	iOS	Android	Web	Terminal
●	●	●	●	●	●

Usage¶

For most widget styling, you do not need to create instances of the Font class. Fonts are applied to widgets using style properties:

import toga
from toga.style.pack import pack, SERIF, BOLD

# Create a bold label in the system's serif font at default system size.
my_label = toga.Label("Hello World", font_family=SERIF, font_weight=BOLD)

Toga provides a number of built-in system fonts. Font sizes are specified in CSS points; the default size depends on the platform and the widget.

If you want to use a custom font, the font file must be provided as part of your app's resources, and registered before first use:

import toga

# Register the user font with name "Roboto"
toga.Font.register("Roboto", "resources/Roboto-Regular.ttf")

# Create a label with the new font.
my_label = toga.Label("Hello World", font_family="Roboto")

When registering a font, if an invalid value is provided for the style, variant or weight, NORMAL will be used.

When a font includes multiple weights, styles or variants, each one must be registered separately, even if they're stored in the same file:

import toga
from toga.style.pack import BOLD

# Register a regular and bold font, contained in separate font files
Font.register("Roboto", "resources/Roboto-Regular.ttf")
Font.register("Roboto", "resources/Roboto-Bold.ttf", weight=BOLD)

# Register a single font file that contains both a regular and bold weight
Font.register("Bahnschrift", "resources/Bahnschrift.ttf")
Font.register("Bahnschrift", "resources/Bahnschrift.ttf", weight=BOLD)

A small number of Toga APIs (e.g., Canvas.fill_text) do require the use of Font instance. In these cases, you can instantiate a Font using similar properties to the ones used for widget styling:

import toga
from toga.style.pack import BOLD

# Obtain a 14 point Serif bold font instance
my_font = toga.Font(SERIF, 14, weight=BOLD)

# Use the font to write on a canvas.
canvas = toga.Canvas()
canvas.fill_text("Hello", font=my_font)

When constructing your own Font instance, ensure that the font family you provide is valid; otherwise an UnknownFontError will be raised.

Notes¶

Some platforms allow the use of font weights and variants that aren't explicitly provided by altering the rendering of a normal font (e.g., using a thick pen to render a normal font to render a fake bold, or applying a skew to render a fake italic). Toga only guarantees that the font faces, variants and weights that are actually defined in a font file will be available for use.
Android and Windows do not support the oblique font style. If an oblique font is specified, Toga will attempt to use an italic style of the same font.
Android and Windows do not support the small caps font variant. If a Small Caps font is specified, Toga will use the normal variant of the same font.

Reference¶

toga.Font ¶

Font(
    family: str,
    size: int | str,
    *,
    weight: str = NORMAL,
    style: str = NORMAL,
    variant: str = NORMAL,
)

Bases: Font

Construct a reference to a font.

This class should be used when an API requires an explicit font reference (e.g. Canvas.fill_text). In all other cases, fonts in Toga are controlled using the style properties linked below.

PARAMETER	DESCRIPTION
`family`	The font family. TYPE: `str`
`size`	The font size. TYPE: `int \| str`
`weight`	The font weight. TYPE: `str` DEFAULT: `NORMAL`
`style`	The font style. TYPE: `str` DEFAULT: `NORMAL`
`variant`	The font variant. TYPE: `str` DEFAULT: `NORMAL`

RAISES	DESCRIPTION
`UnknownFontError`	If the font family requested corresponds to neither one of the built-in system fonts, nor a user-registered font, nor (depending on platform) a font installed on the system.
`ValueError`	If a user-registered font is used, but the file specified either doesn't exist or a font can't be successfully loaded from it.

register `staticmethod` ¶

register(
    family: str,
    path: str | Path,
    *,
    weight: str = NORMAL,
    style: str = NORMAL,
    variant: str = NORMAL,
) -> None

Register a file-based font.

PARAMETER	DESCRIPTION
`family`	The font family. TYPE: `str`
`path`	The path to the font file. This can be an absolute path, or a path relative to the module that defines your `App` class. TYPE: `str \| Path`
`weight`	The font weight. TYPE: `str` DEFAULT: `NORMAL`
`style`	The font style. TYPE: `str` DEFAULT: `NORMAL`
`variant`	The font variant. relative to the module that defines your :any:`App` class. TYPE: `str` DEFAULT: `NORMAL`

RAISES	DESCRIPTION
`ValueError`	When the registered family has the same name as the standard font families `"cursive"`, `"fantasy"`, `"message"`, `"monospace"`, `sans-serif"`, "serif", or "system".

toga.fonts.UnknownFontError ¶

Bases: Exception

Raised when an unknown font family is requested.