Text
TrueType text (Inter is bundled), and bitmap text in the built-in 8x8 font.
Font
Font(font='Inter', size=14.0)A TrueType or OpenType font at one size, for anti-aliased text.
Font("Inter", 14) loads the bundled Inter at 14 points; the names "Inter", "Inter Medium" and "Inter SemiBold" are bundled, and any other string is a path to a .ttf or .otf file. Loading reads the font’s metrics only, so a font can be made anywhere, even before the App runs; its glyphs are rasterized the first time it draws in a window, at that window’s pixel ratio, and again if the ratio changes (a window moved to a Retina screen, or drawing into an Fbo, whose pixels are points).
Text is drawn in the current colour and follows the current matrix. On an untransformed matrix (translations only) each glyph lands on whole device pixels, crisp at 1x and 2x; rotated or scaled, it is filtered smoothly. All fonts share one glyph atlas per window and pixel ratio, so any text drawn in a row, in any fonts, sizes and weights, costs one draw call. Unlike a Texture, a font is not tied to a window: it rasterizes its glyphs again in each new window (a texture made in a closed window raises instead).
The font holds printable ASCII plus ° · × – — • … − and the no-break space (Inter has them all; another font may draw a box for a symbol it lacks); other characters draw as ?. Pairs are kerned as Pillow’s layout kerns them (with libraqm, the font’s kern feature).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| font | str | Path | A bundled font name or a font file path. | 'Inter' |
| size | float | Size in points (the em size), greater than 0. | 14.0 |
Attributes
| Name | Type | Description |
|---|---|---|
| path | The font file. | |
| size | float | The size in points (read-only). |
| line_height | float | The distance between baselines in points, at first the font’s ascent minus its descent (descent is negative); set it to space lines differently (settable). |
| ascent | float | How far the font rises above the baseline, in points (read-only). |
| descent | float | How far it goes below, negative (read-only). |
Raises
| Name | Type | Description |
|---|---|---|
| FileNotFoundError | font is neither a bundled name nor a file. |
|
| ValueError | size is not a positive finite number. |
|
| OSError | Pillow can’t read the file as a font. |
Methods
| Name | Description |
|---|---|
| text_bounds | Returns the box around the ink of text drawn at (x, y). |
| text_width | Returns how far text advances, in points. |
text_bounds
Font.text_bounds(text, x, y)Returns the box around the ink of text drawn at (x, y).
The box hugs the glyph outlines (to 1/16 point), as if drawn with kiln.text(s, x, y, font=f) on an untransformed matrix: y is the baseline, so the box’s top is above it. It is the same at every pixel ratio; the drawn ink may reach a device pixel past it, for the anti-aliased edge and the snap to whole pixels. Text with no ink (spaces, or nothing) gives an empty box at (x, y).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| text | object | The text, or any object to show with str(). |
required |
| x | float | Left of the pen, as for kiln.text. |
required |
| y | float | Baseline of the first line. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Rect | A Rect in points. |
text_width
Font.text_width(text)Returns how far text advances, in points.
The sum of the glyph advances and kerning, which is where the next character would go (Pillow’s getlength), not the ink’s width; for several lines, the widest. Use it to right-align or centre text.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| text | object | The text, or any object to show with str(). |
required |
Returns
| Name | Type | Description |
|---|---|---|
| float | The width in points. |
Rect
Rect()An axis-aligned rectangle: top-left corner and size.
A plain named tuple, so x, y, w, h = rect works; it has no methods (inside, intersects, …) yet.
Attributes
| Name | Type | Description |
|---|---|---|
| x | float | Left edge. |
| y | float | Top edge. |
| width | float | Width. |
| height | float | Height. |
text
text(s, /, x, y, *, font=None, scale=1.0, background=None)Draws text in the fill colour.
Text follows the current matrix and takes the fill colour; it is never outlined, and with fill(None) it is not drawn (a background box still is). "\n" starts a new line at the original x. Anything that is not a str is converted with str().
With font=None, the built-in 8x8 pixel font: y is the baseline of the first line, and each glyph’s 8x8 cell is the 8 rows just above it (y - 8 to y - 1), so capitals end at y - 2 and nothing, not even a descender, goes below y. The font is font8x8. (x, y) is truncated to whole points and the glyphs are sampled without smoothing, so they are crisp at scale 1, 2, 3… on an untransformed matrix. A glyph is 8 points wide and lines are 13.6 points apart (both times scale). "\t" moves to the next multiple of 8 columns; other control characters are skipped, and characters above 127 draw as ?.
With a kiln.Font, its glyphs: (x, y) is the pen on the baseline of the first line; "\t" advances by four spaces; on an untransformed matrix every glyph lands on whole device pixels. Text drawn in a row is one draw call, whatever its fonts. The font’s metrics (text_width, text_bounds, line_height) measure it. A scale other than 1 scales the glyphs as drawn, so they are no longer pixel-snapped: for crisp scaled text, load the font at size * scale.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| s | object | The text, or any object to show with str(). |
required |
| x | float | Left edge of the first column (the pen, for a Font). | required |
| y | float | Baseline of the first line. | required |
| font | Font | None | A kiln.Font, or None for the built-in 8x8 bitmap font. |
None |
| scale | float | Size multiplier (2 and 3 give the bitmap font crisp big pixels). | 1.0 |
| background | ColorLike | None | A colour to draw a box behind the text in: the text’s bounds plus 4 points of padding (times scale). |
None |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | scale is not a positive finite number. |