Formatted Strings¶
- class 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)¶
Bases:
SVGContextPropertyMixin,ContextPropertyMixinReturn 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))
- textProperties()¶
Return a dict with all current stylistic text properties.
- 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(r=None, g=None, b=None, alpha=1)¶
Sets the fill color with a red, green, blue and alpha value. Each argument must a value float between 0 and 1.
- stroke(r=None, g=None, b=None, alpha=1)¶
Sets the stroke color with a red, green, blue and alpha value. Each argument must a value float between 0 and 1.
- cmykFill(c=None, m=None, y=None, k=None, alpha=1)¶
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(c=None, m=None, y=None, k=None, alpha=1)¶
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.
- strikethrough(strikethrough)¶
Set the strikethrough value. Strikethrough 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))
- 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.
- fontNamedInstance(name, fontNameOrPath=None)¶
Set a font with name of a named instance. The name of the named instance must be listed in listNamedInstances(),
Optionally a fontNameOrPath can be given. If a font path is given that fontNameOrPath will be set.
- 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(tab, *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))
- 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))
- 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.
- writingDirection(direction)¶
Set the writing direction: None, ‘LTR’ or ‘RTL’.
- 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))