sextile.viewdata.lettering¶
Setting a line of text in a mosaic font: where each letter goes.
The result is a bitmap, which blocks.block_runs turns into cells and Composition places on a frame. This module knows about letters and spacing and nothing about attributes: cells takes a string to mosaic patterns, and place and boxed add it to a Composition.
Three spacings, chosen with Spacing. FIXED gives every letter the face’s design width, which a column of figures wants. PROPORTIONAL gives each its own advance and is the default, since a row of 78 blocks does not hold ten letters at a fixed eight. KERNED closes a pair up further where their bitmaps allow – by no more than limit blocks, and never across a blank glyph, or a letter after a space would slide back and run the words together.
The lettering is trimmed on the right to the last block of ink, because a banner is centred on what it draws rather than on what it advanced past. The left is left alone: a leading bearing is the face’s own design.
- class sextile.viewdata.lettering.Spacing(*values)[source]¶
Bases:
EnumHow far apart the letters go.
- sextile.viewdata.lettering.boxed(composition, row, text, font, colour=Colour.WHITE, background=Colour.BLUE, *, where=Align.CENTRE, padding=1, rows=None, spacing=Spacing.PROPORTIONAL, gap=1, limit=1, trim=True)[source]¶
Set lettering in a coloured box fitted around it.
- Parameters:
composition (
Composition) – The composition to add the box and the letters to.row (
int|Align) – The top row of the box, or an alignment to centre it down the frame.text (
str) – The word to set.font (
Font) – The face to set it in.colour (
Colour) – The letters.background (
Colour) – The field they sit in.padding (
int) – Cells of colour either side of the letters.rows (
int|None) – How tall the box is, in rows. The height of the letters unless given.spacing (
Spacing) – How far apart the letters go.gap (
int) – Blocks that must stay clear between two letters when kerning.limit (
int) – The most a kerned pair may close up by.trim (
bool) – Whether to cut the face to its own ink rather than keeping its full height.
- Return type:
- Returns:
The box, so that a caller may place something else against it.
- Raises:
DoesNotFit – If rows is fewer than the letters need. A box shorter than its letters is a stripe behind them rather than a box, and is drawn as two things: a panel from Composition.panel and the letters from place, both centred, the composition working out that the row they share is coloured.
The Ceefax effect: a word in a field of colour, cyan on blue or red on yellow. The box is fitted here, where the letters can be measured, rather than by a caller counting them – it takes one cell on its left for the attribute that colours it, which is the sort of arithmetic a caller gets wrong. The letters are centred in it both ways, to the block.
- sextile.viewdata.lettering.cells_needed(text, font, *, spacing=Spacing.PROPORTIONAL, gap=1, limit=1, padding=0)[source]¶
Measure how many cells a line of lettering would take across.
- Parameters:
text (
str) – The line to measure. It is not set, only measured.font (
Font) – The face it would be set in.spacing (
Spacing) – How far apart the letters would go.gap (
int) – Blocks that must stay clear between two letters when kerning.limit (
int) – The most a kerned pair may close up by.padding (
int) – Cells of margin to count either side of the letters, for a caller sizing a box round them rather than the letters alone.
- Returns:
a line ending part way into a cell still occupies the whole of it.
- Return type:
The companion of rows_needed, and what a page needs to draw a stripe behind a word without drawing the word first: a panel of this width and the lettering, both centred, line up without either knowing about the other.
- sextile.viewdata.lettering.place(composition, row, text, font, colour=Colour.WHITE, *, column=None, within=None, spacing=Spacing.PROPORTIONAL, gap=1, limit=1, inverted=False, margin=0, trim=True, separated=False)[source]¶
Add text, set in font, to a composition with its top row at row.
row may be an alignment as well, which centres the letters down the panel they are going on – to the block, so a line that does not fill its rows sits in the middle of them rather than at the top.
Centred unless a column is given – within within, if it is going on a panel, so that a word in a coloured box is centred in the box. The composition works out where that leaves it, accounting for what the colour attribute costs and how far into a cell the ink may start; this module handles the letters.