..Shapes..Text

Nested namespaces

Graphical rendering of test is a complex matter with lots of parameters to be controlled. By having a separate namespace for these things, the ..Shapes..Graphics gets less content and will be easier to apprehend.

The bindings in this section are closely related to the text state parameters in pdf.

newText
This is a hot value.
Spawns:	§•Text

textmode
fill:false::§Boolean stroke:false::§Boolean → §TextRenderingMode
Dynamic references:	none
Constructs a value that specifies a text rendering mode, which can be assigned to @rendering. If both arguments are false, the rendering mode will cause the text not to display at all, which is useful when clipping.
See also:	@rendering ..Shapes..Graphics..clip

kerning
<>::{( §String ∪ §Float )} → §KernedText
Dynamic references:	none
Manual kerning. Each §Float value between §String values will subtract horizontal distance between the adjacent glyphs when the text is added to a §•Text object. The distance is interpreted in units of the font size.
See also:	kern

kern
<>::{( §String ∪ §Float )} → §KernedText
Dynamic references:	none
Interleaves automatically kerned text with manual kernings. Automatic kerning needs support by the metrics of the current font must, and it is forbidden to call this function unless the current font indicates that kern pairs supported by having its kerning? field set to true.
See also:	kerning

@font
Used by:
Type:	§Font
Default binding:	FONT_HELVETICA
Intended to be used when creating text using the built-in mechanisms of pdf.

@size
Used by:
Type:	§Length
Default binding:	10 bp
Constraint:	@size > 0 bp
Intended to be used as the size of text.

@horizontalscaling
Used by:
Type:	§Float
Default binding:	1
Constraint:	@horizontalscaling > 0
Horizontal scaling of the font.

@rendering

Used by:

Type:

§TextRenderingMode

Text rendering mode.

Design note: It would have been possible to split the rendering mode into two separate dynamic variables; one for stroking, and one for filling. One obvious benefit of this would have been that the special type §TextRenderingMode would not have been necessary. However, the rendering mode is usually perceived as one entity; controlling one of the two flags while not caring about the other seems very unlikely. This is why the two are kept together.

See also:

..Shapes..Graphics..clip

@knockout
Used by:
Type:	§Boolean
Default binding:	false
The text knockout mode. Refer to the pdf reference for details.

@characterspacing
Used by:
Type:	( §Length ∪ §Float )
Default binding:	0 bp
Extra space to add between characters. A §Float is interpreted as a scaling of @size.

@wordspacing
Used by:
Type:	( §Length ∪ §Float )
Default binding:	0 bp
Extra space to add at each space character. A §Float is interpreted as a scaling of @size.

@leading
Used by:
Type:	( §Length ∪ §Float )
Default binding:	1
The vertical distance between lines of text. A §Float is interpreted as a scaling of @size.

@rise
Used by:
Type:	( §Length ∪ §Float )
Default binding:	1
Vertical offset of the text from the normal baseline. A §Float is interpreted as a scaling of @size.

newFont
This is a hot value.
Spawns:	§•Font

font
family::§String style:void::§String outline:false::§Boolean → §Font
Dynamic references:	none
Locates and loads a font, which can be assigned to @font. Currently, the only supported font format is TrueType. This function requires the Shapes compiler to be built with both FreeType and FontConfig. The two arguments family and style are used to point out a particular font. If outline is true, the font will not produce text that references glyphs inside a font program stored in the pdf file, but the glyphs will be drawn as filled paths without any connection to characters. Outlining the font has the advantage that no font program needs to be stored in the pdf file, but there are several drawbacks: It will not be possible for viewing applications to search or copy the text. Outlining each glyph may produce bigger files when there is a lot of text. Outlining may slow down display of the pdf, and rules out font-rendering techniques that are normally used to enhance the visual appearance of text. Besides these differences, there result should look the same no matter whether fonts are outlined or not. This implies that bounding boxes of outlined fonts are computed exactly as for non-outlined fonts, even though the glyph outlines would allow more “accurate” boxes to be computed. The font is located using FontConfig, so if font fails to find your font, this is most likely an issue with FontConfig, and not with Shapes. To check what fonts FontConfig knows about, one can use the command line utility fc-list. For instance, calling font with family equal to Santa Fe LET, and not passing anything for style, should correspond to the command line call fc-list 'Santa Fe LET':font-format=TrueType and if style was set to Regular (which Santa Fe LET does not provide; the only style is called Plain), that would correspond to fc-list 'Santa Fe LET':style=Regular:font-format=TrueType This way, you can experiment with font families and styles in the terminal before trying to select the font in your Shapes program.
See also:	@font

..Shapes..Text

Typeset text

Glyphs and fonts