Font#

A font for displaying text.

Availability (Key)#

macOS

GTK

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", style=Pack(font_family=SERIF, font_weight=BOLD))

Toga provides a number of built-in system fonts. Font sizes are specified in points; if unspecified, the size will fall back to the default font size for the widget being styled.

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", style=Pack(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., Context.write_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.context.write_text("Hello", font=my_font)

Notes#

  • macOS and iOS do not currently support registering user fonts.

  • 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#

class toga.Font(family, size, *, weight=NORMAL, style=NORMAL, variant=NORMAL)#

Constructs a reference to a font.

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

Parameters:
static register(family, path, *, weight=NORMAL, style=NORMAL, variant=NORMAL)#

Registers a file-based font.

Note: This is not currently supported on macOS or iOS.

Parameters:

  • family – The font family.

  • 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.

  • weight – The font weight.

  • style – The font style.

  • variant – The font variant.