DrawBot

 

Previous

Text Properties

Next

Images

More

Formatted Strings

FormattedString(txt=None, font=None, fontSize=10, fallbackFont=None, fill=(0, 0, 0), cmykFill=None, stroke=None, cmykStroke=None, strokeWidth=1, align=None, lineHeight=None, tracking=None, baselineShift=None, openTypeFeatures=None, tabs=None, language=None, indent=None, tailIndent=None, firstLineIndent=None, paragraphTopSpacing=None, paragraphBottomSpacing=None)

Return a string object that can handle text formatting.

size(1000, 200)
# 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, 30))


# create a formatted string
txt = FormattedString()

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

text(txt, (10, 150))
Open in DrawBot: formattedString.pyDownload: formattedString.py
class FormattedString(txt=None, **kwargs)

Bases: drawBot.context.baseContext.SVGContextPropertyMixin, drawBot.context.baseContext.ContextPropertyMixin

FormattedString 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.

clear()
append(txt, **kwargs)

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

  • font: the font to be used for the given text, if a font path is given the font will be installed and used directly.
  • fallbackFont: the fallback font
  • fontSize: the font size to be used for the given text
  • fill: the fill color to be used for the given text
  • cmykFill: the cmyk fill color to be used for the given text
  • stroke: the stroke color to be used for the given text
  • cmykStroke: the cmyk stroke color to be used for the given text
  • strokeWidth: the strokeWidth to be used for the given text
  • align: the alignment to be used for the given text
  • lineHeight: the lineHeight to be used for the given text
  • tracking: set tracking for the given text in absolute points
  • baselineShift: set base line shift for the given text
  • openTypeFeatures: enable OpenType features
  • fontVariations: pick a variation by axes values
  • tabs: enable tabs
  • indent: the indent of a paragraph
  • tailIndent: the tail indent of a paragraph
  • firstLineIndent: the first line indent of a paragraph
  • paragraphTopSpacing: the spacing at the top of a paragraph
  • paragraphBottomSpacing: the spacing at the bottom of a paragraph
  • language: the language of the text

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”. It will append the text with the current settings of the formatted string.

font(fontNameOrPath, fontSize=None, fontNumber=0)

Set a font with the name of the font. If a font path is given the font will used directly. 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.

The font name is returned, which is handy when the font was loaded from a path.

fontNumber(fontNumber)
fallbackFont(fontNameOrPath, fontNumber=0)

Set a fallback font, used whenever a glyph is not available in the normal font. If a font path is given the font will be installed and used directly.

fallbackFontNumber(fontNumber)
fontSize(fontSize)

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

fill(*fill)

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

stroke(*stroke)

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

cmykFill(*cmykFill)

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.

cmykStroke(*cmykStroke)

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.

strokeWidth(strokeWidth)

Sets stroke width.

align(align)

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

lineHeight(lineHeight)

Set the line height.

tracking(tracking)

Set the tracking between characters. It adds an absolute number of points between the characters.

baselineShift(baselineShift)

Set the shift of the baseline.

underline(underline)

Set the underline value. Underline must be single, thick, double or None.

url(url)

set the url value. url must be a string or None

openTypeFeatures(*args, **features)

Enable OpenType features and return the current openType features settings.

If no arguments are given openTypeFeatures() will just return the current openType features settings.

size(1000, 200)
# create an empty formatted string object
t = FormattedString()
# set a font
t.font("Didot")
# set a font size
t.fontSize(60)
# add some text
t += "0123456789 Hello"
# enable some open type features
t.openTypeFeatures(smcp=True, onum=True)
# add some text
t += " 0123456789 Hello"
# draw the formatted string
text(t, (10, 80))
Open in DrawBot: openTypeFeaturesFormattedString.pyDownload: openTypeFeaturesFormattedString.py
listOpenTypeFeatures(fontNameOrPath=None, fontNumber=0)

List all OpenType feature tags for the current font.

Optionally a fontNameOrPath can be given. If a font path is given the font will be used directly.

fontVariations(*args, **axes)

Pick a variation by axes values and return the current font variations settings.

If no arguments are given fontVariations() will just return the current font variations settings.

listFontVariations(fontNameOrPath=None, fontNumber=0)

List all variation axes for the current font.

Returns a dictionary with all axis tags instance with an info dictionary with the following keys: name, minValue and maxValue. For non variable fonts an empty dictionary is returned.

Optionally a fontNameOrPath can be given. If a font path is given the font will be used directly.

listNamedInstances(fontNameOrPath=None, fontNumber=0)

List all named instances from a variable font for the current font.

Returns a dictionary with all named instance as postscript names with their location. For non variable fonts an empty dictionary is returned.

Optionally a fontNameOrPath can be given. If a font path is given the font will be used directly.

tabs(*tabs)

Set tabs,tuples of (float, alignment) Aligment can be “left”, “center”, “right” or any other character. If a character is provided the alignment will be right and centered on the specified character.

# create a new formatted string
t = FormattedString()
# set some tabs
t.tabs((85, "center"), (232, "right"), (300, "left"))
# add text with tabs
t += " hello w o r l d".replace(" ", "\t")
# draw the string
text(t, (10, 10))
Open in DrawBot: tabsFormattedString.pyDownload: tabsFormattedString.py
indent(indent)

Set indent of text left of the paragraph.

# setting up some variables
x, y, w, h = 10, 10, 500, 600

txtIndent = 100
txtFirstLineIndent = 200
txtTailIndent = -100
txtFontSize = 22

paragraphTop = 3
paragraphBottom = 10

txt = '''DrawBot is an ideal tool to teach the basics of programming. Students get colorful graphic treats while getting familiar with variables, conditional statements, functions and what have you. Results can be saved in a selection of different file formats, including as high resolution, scaleable PDF, svg, movie, png, jpeg, tiff...'''

# a new page with preset size
newPage(w+x*2, h+y*2)
# draw text indent line
stroke(1, 0, 0)
line((x+txtIndent, y), (x+txtIndent, y+h))
# draw text firstline indent line
stroke(1, 1, 0)
line((x+txtFirstLineIndent, y), (x+txtFirstLineIndent, y+h))
# draw tail indent
pos = txtTailIndent
# tail indent could be negative
if pos <= 0:
    # substract from width of the text box
    pos = w + pos
stroke(0, 0, 1)
line((x+pos, y), (x+pos, y+h))
# draw a rectangle
fill(0, .1)
stroke(None)
rect(x, y, w, h)

# create a formatted string
t = FormattedString(fontSize=txtFontSize)
# set alignment
t.align("justified")
# add text
t += txt
# add hard return
t += "\n"
# set style for indented text
t.fontSize(txtFontSize*.6)
t.paragraphTopSpacing(paragraphTop)
t.paragraphBottomSpacing(paragraphBottom)
t.firstLineIndent(txtFirstLineIndent)
t.indent(txtIndent)
t.tailIndent(txtTailIndent)
# add text
t += txt
# add hard return
t += "\n"
# reset style
t.fontSize(txtFontSize)
t.indent(None)
t.tailIndent(None)
t.firstLineIndent(None)
t.paragraphTopSpacing(None)
t.paragraphBottomSpacing(None)
# add text
t += txt
# draw formatted string in a text box
textBox(t, (x, y, w, h))
Open in DrawBot: indent.pyDownload: indent.py
tailIndent(indent)

Set indent of text right of the paragraph.

If positive, this value is the distance from the leading margin. If 0 or negative, it’s the distance from the trailing margin.

firstLineIndent(indent)

Set indent of the text only for the first line.

paragraphTopSpacing(value)

set paragraph spacing at the top.

paragraphBottomSpacing(value)

set paragraph spacing at the bottom.

language(language)

Set the preferred language as language tag or None to use the default language.

language() will activate the locl OpenType features, if supported by the current font.

size()

Return the size of the text.

getNSObject()
copy()

Copy the formatted string.

fontContainsCharacters(characters)

Return a bool if the current font contains the provided characters. Characters is a string containing one or more characters.

fontContainsGlyph(glyphName)
fontFilePath()

Return the path to the file of the current font.

fontFileFontNumber()
listFontGlyphNames()

Return a list of glyph names supported by the current font.

fontAscender()

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

fontDescender()

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

fontXHeight()

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

fontCapHeight()

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

fontLeading()

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

fontLineHeight()

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

appendGlyph(*glyphNames)

Append a glyph by his glyph name or glyph index using the current font. Multiple glyph names are possible.

size(1300, 400)
# create an empty formatted string object
t = FormattedString()
# set a font
t.font("Menlo-Regular")
# set a font size
t.fontSize(300)
# add some glyphs by glyph name
t.appendGlyph("A", "ampersand", "Eng", "Eng.alt")
# add some glyphs by glyph ID (this depends heavily on the font)
t.appendGlyph(50, 51)
# draw the formatted string
text(t, (100, 100))
Open in DrawBot: appendGlyphFormattedString.pyDownload: appendGlyphFormattedString.py
svgClass

The svg class, as a string.

svgID

The svg id, as a string.

The svg link, as a string.

Drawing With Python
© Copyright Just van Rossum, Erik van Blokland, Frederik Berlaen
Last updated on Feb 20, 2023.
Created using Sphinx 1.8.6.