font(family, weight, size, italic=False, **options)

Sets the font, typographic features, and letter-spacing to be used by the text() command (or modifies selected attributes of the current font). The family and weight arguments are strings corresponding to the name of a font family installed on the system and a weight name. If the family lacks the specified weight, the closest match will be used instead. If included, the size argument should be a number representing the desired point size. All three positional arguments are optional since unspecified attributes will use the canvas’s current font() setting as a basis for selecting a new one.

You can retrieve a list of valid family names on your system using the fonts() command. To determine which weights & styles are provided by a given family, either create a Family object and inspect its properties, or take a look at the weights, widths, and variants properties of the current Font object (returned by calling font() with no arguments).

italic

A boolean (or 0/1) value specifying whether to use the italic style of the current font family. Note that the family must provide an italic as it won’t be algorithmically generated. If you’re dead-set on hacking in a fake italic, try drawing the text as an outline and applying a skew transform to it.

width

For families that provide a range of widths (e.g., ‘compressed’, ‘condensed’, or ‘extended’), the width argument allows you to select them by name.

variant

The vast majority of western typefaces use weight, width, and italicization as the ‘axes’ for selecting fonts. Occasionally you will run into a family with a more idioscyncratic organization (for example, see Chalet’s goofy/charming city-and-era naming scheme). Strings passed as the variant arg allow you to select these sorts of non-standard names.

face

A typeface consists of a ‘family’ of individual ‘fonts’ which relate to one another along axes like weight or width. Typically you will select fonts by specifiying a family and a combination of attributes. You can also hard-code your selection by passing a so-called ‘PostScript Name’ for a particular font weight & style and passing that as the face parameter. For instance, the following are equivalent:

font('avenir', 'heavy', italic=True)
font(face='Avenir-HeavyOblique')

To find the face name of a specific font, use the Show Font Info option in the Preview menu of Font Book.

tracking

Controls the letter-spacing of a run of text. The value is a positive or negative number in thousandths of an em and sets the amount of extra space added (or subtracted) between characters. The default value is zero, meaning no extra space will be added beyond what is specified in the font’s kerning tables. To disable kerning altogether, set the value to None.

If the selected font is an OpenType file with support for advanced typographical features, you may pass any of the following optional arguments to enable or disable them. Note that these settings will only affect the typesetting if the font was designed to support OpenType or ‘AAT’ features.

Argument values may be either a boolean or the intergers 0 and 1. Certain features also accept other integer values or the all keyword as noted below.

lig

sc

osf

tab

vpos

frac

ss

Context Manager

Returns

Tutorial

Example

fill(0.2)
font("Helvetica", 35)
text("hello", 10, 50)
with font("bold", 16, italic=True):
    text("cruel", 10, 69)
text("world", 10, 95)

layout(**options)

Sets the layout behavior used by text() for multi-line blocks of type. Parameters set through layout() apply to entire ‘paragraphs’ within the source text (as separated by "\n" characters in the string being drawn). Note that as with the font() command, any of these keyword arguments can be passed to the text() command directly to override the global state. You can also include layout() parameters when defining a stylesheet() tag, but their effect will only be seen when applied to the first character in a given paragraph.

align

Text can be aligned to the LEFT, RIGHT, or CENTER or spaced out to fill the entire width of the textblock via the JUSTIFY option. See the legacy align() command for examples of each.

indent

Controls the amount of indentation space for a paragraph. The value is a floating point number that specifies the indentation of the paragraph’s first line in em-units. If the value is negative, the paragraph’s first line will be flush with the margin and all subsequent lines in the paragraph will be indented by that measure.

hyphenate

Controls whether line-breaking operates on the level of words or syllables. If set to True, the layout engine will attempt to break lines even mid-word in order to create a nicer rag. Hyphenation is especially useful when drawing text with an alignment of JUSTIFY since word spacing can get comically loose without it. For more fine-grained control, pass a number between 0 and 1.0 to set how hyphen-happy the typesetter should be.

margin

Sets the internal margin within a TextFrame, effectively ‘squeezing’ the width of the Text object by a given number of canvas units. Passing a floating point value moves the left margin ‘inward’ by that distance. Passing a list or tuple of two floats will inset the left and right margins respectively. Make sure your combined margins are smaller than your Text’s width or glyph-salad will result.

spacing

Controls the amount of vertical space added before and after each paragraph (note that this is in addition to the current line-to-line leading). Passing a floating point value will add that many em-units of padding to the top of the paragraph. Passing a list of two floats will set the top- and bottom-padding respectively.

leading

Controls the spacing from baseline-to-baseline in multi-line text runs. The value is a floating point number representing the distance as a multiple of the current font size. The default leading is 1.2 (120% of the font size), but you may wish to increase this when typesetting a particularly wide measure.

The layout() command (and the Font object it returns) can both be used as part of a with statement. Changes to the layout-style will be applied at the beginning of the code block, then restored to the previous style at the end.

Returns a generator which yields one or more Text objects with a fixed position and size. The syntax is identical to that of the text() command, but rather than drawing to the canvas it returns the resulting Text objects for your script to plot() manually.

The paginate() command can be useful when drawing long passages of text that may not fit in a single text block (or on a single canvas frame). The objects it returns are standard Text objects but contain two additional ‘counter’ attributes that may be useful during layout:

txt.folio # the "page number" of the object (typically counting from one)
txt.pg    # the index of the object in the series (counting from zero)

folio

Sets the ‘page number’ of the first Text object in the sequence – accessible through its corresponding .folio attribute. Subsequent objects in the sequence count up from there. Defaults to 1 if omitted.

verso

Pass a 2-tuple to set x/y coordinates for ‘even’ pages in the sequence. If omitted, all the Text objects will use the same x/y position as defined in the positional arguments.

an iterable generator of Text objects (as many as needed to fully lay out the string)

with export('~/book.pdf') as book:
    size(340, 450)

    for txt in paginate(40,40, 600,800, src='~/Documents/war-and-peace.txt'):
        with book.page:
            plot(txt)
            text(WIDTH/2, 430, align=CENTER, size=9, str=txt.pg+1)

stylesheet("name", *font, **options) # define a style
stylesheet("name") # retrieve a preexisting style
stylesheet("name", None) # undefine a style

Part of the canvas’s state is a global Stylesheet object which is used by the text() command to format strings with XML-delimited inline styles. The stylesheet() command allows you associate font() and layout() settings with names. You can then apply these attributes to a portion of your string by enclosing it in an XML element using the same name.

The first argument is a string defining the new style’s name. All subsequent arguments will be interpreted identically to the font() command’s syntax. You can use both positional and keyword arguments. For example the following are equivalent:

stylesheet('title', 'gill sans', 'bold', 22, italic=True)

stylesheet('title', size=22, family='gill sans', italic=True, weight='bold')

Paragraph layout options can also be added to styles using the same set of arguments supported by the layout() command. Note that in PlotDevice, paragraph settings are ‘winner take all’ for each "\n"-separated line of text. So whatever the paragraph style is set to for the first character of that line will apply until the next carriage return.

Once you’ve defined a style, you can refer to it when calling the text() command, either by using the style name as a tag within some xml input, or by passing a style keyword argument to be applied to an entire string:

text(40,40, xml="<title>Ignite the seven cannons!</title>")

text(40,40, str="Ignite the seven cannons!", style="title")

Styles ‘cascade’ in the same way as CSS definitons. Rather than fully specifying your styles, you can have each tag modify only a subset of attributes. Omitted attributes will be ‘inherited’ from other enclosing style tags or, ultimately, the canvas’s current font() and layout() settings.

The Stylesheet stores individual styles as dictionaries of attributes. If your script needs access to the properties set by a previously defined style, call stylesheet() with the style name as the sole argument. It will return the dictionary associated with the name.

stylesheet('serif', 'Adobe Garamond', 'semibold', 11)
print(stylesheet('serif'))
>>> {'family': u'Adobe Garamond Pro', 'weight': 'semibold', 'size': 11}

Should you need to remove a style defined earlier in the script, call stylesheet() again with None as the new value for the tag name you’re undefining:

stylesheet("big-mistake", None)

textpath(txt, x, y, width=None, height=1000000, **options)

Works exactly like the text() command, except it returns a Bezier rather than drawing to the screen. You can use the Bezier with commands like clip(), mask(), or plot(). You can also access the inner and outer strokes of the individual glyphs by iterating through its contours property.

You can also generate a Bezier with the text() command’s outline parameter:

pth = text("Antitoi Bros. Video", 20,100, outline=True, plot=False)

Alternatively, use a bezier() context to capture the path in a local variable:

with bezier(20,100, plot=False) as pth:
    text("Enfield Tennis Acad.", 0,0)
... # use the Bezier object in pth