Font#
A font for displaying text.
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:
family (
str
) – The font family.weight (
str
) – The font weight.style (
str
) – The font style.variant (
str
) – The font variant.
- 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.