Formatted Strings

drawBot.FormattedString(txt, font=None, fill=(0, 0, 0), cmykFill=None, stroke=None, cmykStroke=None, strokeWidth=1, align=None, lineHeight=None, openTypeFeatures=None)

Return a string object that can handle text formatting.

This is a reusable object, if you want to draw the same over and over again. FormattedString objects can be drawn with the text(txt, (x, y)) and textBox(txt, (x, y, w, h)) methods.

FormattedString methods

formattedString.append(txt, font=None, fontSize=None, fill=None, cmykFill=None, stroke=None, cmykStroke=None, strokeWidth=None, align=None, lineHeight=None)

Add txt to the formatted string with some additional formatting attributes for the given text:

  • font: the font to be used
  • fontSize: the font size
  • fill: the fill color
  • cmykFill: the cmyk fill color
  • stroke: the stroke color
  • cmykStroke: the cmyk stroke color
  • strokeWidth: the stroke width
  • align: the alignment of the text
  • lineHeight: the line height
  • openTypeFeatures: enable OpenType features

All formatting attributes follow the same notation as other similar DrawBot methods. A color is a tuple of (r, g, b, alpha) and a cmykColor is a tuple of (c, m, y, k, alpha).

Text can also be added with formattedString += “hello”. This will append the text with the current settings of the formatted string.

formattedString.font(fontName, fontSize=None)

Set a font with the name of the font. Optionally a fontSize can be set directly. The default font, also used as fallback font, is ‘LucidaGrande’. The default fontSize is 10pt.

The name of the font relates to the font’s PostScript name.

formattedString.fontSize(fontSize)

Set the font size in points. The default fontSize is 10pt.

formattedString.fill(r, g, b, a)

Sets the fill color with a red, green, blue and alpha value. Each argument must a value float between 0 and 1.

formattedString.stroke(r, g, b, a)

Sets the stroke color with a red, green, blue and alpha value. Each argument must a value float between 0 and 1.

formattedString.cmykFill(c, m, y, k, a)

Set a fill using a CMYK color before drawing a shape. This is handy if the file is intended for print.

Sets the CMYK fill color. Each value must be a float between 0.0 and 1.0.

formattedString.cmykStroke(c, m, y, k, a)

Set a stroke using a CMYK color before drawing a shape. This is handy if the file is intended for print.

Sets the CMYK stroke color. Each value must be a float between 0.0 and 1.0.

formattedString.strokeWidth(value)

Sets the stroke width.

formattedString.align(align)

Sets the text alignment. Possible align values are: left, center and right.

formattedString.lineHeight(value)

Set the line height.

formattedString.openTypeFeatures(frac=True, case=True, ...)

Enable OpenType features.

# create an empty formatted string object
t = FormattedString()
# set a font
t.font("HoeflerText-Regular")
# set a font size
t.fontSize(60)
# add some text
t += "0123456789 Hello"
# enable some open type features
t.openTypeFeatures(smcp=True, lnum=True)
# add some text
t += " 0123456789 Hello"
# draw the formatted string
text(t, (10, 100))
formattedString.size()

Return the size of the string.

# create a formatted string
txt = FormattedString()

# adding some text with some formatting
txt.append("hello", font="Helvetica", fontSize=100, fill=(1, 0, 0))
# adding more text
txt.append("world", font="Times-Italic", fontSize=50, fill=(0, 1, 0))

# setting a font
txt.font("Helvetica-Bold")
txt.fontSize(75)
txt += "hello again"

# drawing the formatted string
text(txt, (10, 10))


# create a formatted string
txt = FormattedString()

# adding some text with some formatting
txt.append("hello", font="Hoefler Text", fontSize=50)
# adding more text with an
txt.append("world", font="Hoefler Text", fontSize=50, openTypeFeatures=dict(smcp=True))

text(txt, (10, 110))
formattedString.fontAscender()

Returns the current font ascender, based on the current font and fontSize.

formattedString.fontDescender()

Returns the current font descender, based on the current font and fontSize.

formattedString.fontXHeight()

Returns the current font x-height, based on the current font and fontSize.

formattedString.fontCapHeight()

Returns the current font cap height, based on the current font and fontSize.

formattedString.fontLeading()

Returns the current font leading, based on the current font and fontSize.

formattedString.fontLineHeight()

Returns the current line height, based on the current font and fontSize. If a lineHeight is set, this value will be returned.

formattedString.appendGlyph(glyphName1, glyphName2, ...)

Appends a glyph by his glyph name using the current font.

# create an empty formatted string object
t = FormattedString()
# set a font
t.font("Menlo-Regular")
# set a font size
t.fontSize(60)
# add some glyphs
t.appendGlyph("Eng", "Eng.alt")
# draw the formatted string
text(t, (10, 100))