8 Pict Text Layout

8.16.0.4

8 Pict Text Layout🔗ℹ

The text function from pict can draw text, but only in a fixed, given font. The pict/text library provides support for font configuration, nestable styles, and basic paragraph typesetting.

annotation

TextContent

Satisfied by a string, a pict, or a list of values that satisfy TextContent.

function

fun t(content :: TextContent, ...,

~font: font :: draw.Font = current_font()) :: Pict

Accepts content as either a string, pict, or list of such content (including, potentially, nested lists) and combines it into into a single pict. Strings are converted to text using text with font, and lists are flattened; the result listing of picts is the combined with beside and #'topline mode.

Support for lists makes t suitable for use with @ notation, as in @t{Hello}.

> t("Hello").scale(2)
> @t{Hello}.scale(2)
> parameterize { current_font:
current_font() with (style = #'italic) }:
@t{Hello}.scale(2)

function

fun bold(content :: TextContent, ...) :: Pict

function

fun italic(content :: TextContent, ...) :: Pict

function

fun underline(content :: TextContent, ...) :: Pict

function

fun tt(content :: TextContent, ...) :: Pict

function

fun roman(content :: TextContent, ...) :: Pict

Similar to t, but starts with current_font() and adds boldness, italicness, underlinedness, fixed-widthness, or serifness to obtain the font for converting strings.

The current_font_to_tt and current_font_to_roman parameters determine how a font is adjusted to make it fixed-width or seriffed.

> @bold{Hello}.scale(2)
> @t{To @bold{boldly} go}.scale(2)
> @roman{x = y + z}.scale(2)

function

fun subscript(content :: TextContent, ...) :: Pict

function

fun superscript(content :: TextContent, ...) :: Pict

Like t, but the resulting pict’s scale and baseline are adjusted to form subscript or superscript text.

> @t{H@subscript{2}O}.scale(2)
> @t{x@superscript{2}}.scale(2)

function

fun strikethrough(content :: TextContent, ...,

~line: line :: ColorMode = #'inherit,

~line_width: line_width :: LineWidth = 3,

~dy: dy = 0) :: Pict

Like t, but a horizontal line is added on top of the resulting pict. The line, line_width, and dy arguments affect the striketrough line.

> @strikethrough{wrong}.scale(2)

expression

boldly(content_expr, ...)

expression

boldly: body; ...

expression

italicly(content_expr, ...)

expression

italicly: body; ...

expression

ttly(content_expr, ...)

expression

ttly: body; ...

expression

romanly(content_expr, ...)

expression

romanly: body; ...

Macros that parameterize content_exprs or bodys to adjust the current_font parameter in the same way as bold, italic, tt, or roman. For the forms with content_exprs, the results of the expressions are passed on to t. For the forms with bodys, the result is the result of the body sequence.

> @bold{a @italic{b} c}.scale(2)
> @boldly{a @italic{b} c}.scale(2)

function

fun lines(p :: Pict, ...,

~horiz: align :: HorizAlignment = #'left) :: Pict

Like stack, but using current_line_sep() as the separation amount and with a default horizontal alignment of #'left.

function

fun para(content :: TextContent, ...,

~width: width = current_para_width(),

~horiz: horiz :: HorizAlignment = #'left,

~full: full = #false,

~decode: decode = #true) :: Pict

Accepts content similar to t, but combines into multiple lines instead of a single beside combination, and a blank space is added between picts that end up on the same line but could be split across lines.

The rules for spacing and line breaks are designed to work naturally with @ notation, and so they treat strings and list nestings specially:

when a string does not start or end with a space, and when it is preceded or followed by a pict (not a string or list), then no space is added before or after the string’s rendering;
after deciding on spacing around a string, the string is split on space characters to obtain a list of strings to convert separately;
strings are converted to text using t, but first rewritten through the following conversions, unless decode is #false:
- --- → — (em dash)
- -- → – (en dash)
- `` → “ (curly open quote)
- '' → ” (curly close quote)
- ' → ’ (curly single close quote)

The width argument determines the maximum width of a line, and if full is true, then the resulting pict is padded to that width. The horiz argument controls both how multiple lines are aligned relative to one another and how padding is added when full is true. Lines are separated by current_line_sep() space.

> @para{Say ``hello'' for me!}
> @para(~width: 50){Say ``hello'' for me!}
> @para(~width: 50, ~horiz: #'right){Say ``hello'' for me!}
> para(& for List (i in 0..50): @t{Echo}.scale((50 - i)/50))
> parameterize { current_font:
                   current_font() with (size = 18, kind = #'roman) }:
    para(@{There's a fine line between fishing},
         @{and just standing on the shore like an idiot.},
         @{--- Stephen Wright})

function

fun item(content :: TextContent, ...,

~bullet: bullet :: maybe(Pict) = #false,

~width: width = current_para_width(),

~horiz: align :: HorizAlignment = #'left,

~full: full = #false) :: Pict

function

fun subitem(content :: TextContent, ...,

~bullet: bullet :: maybe(Pict) = #false,

~width: width = current_para_width(),

~horiz: align :: HorizAlignment = #'left,

~full: full = #false) :: Pict

Like para, but the paragraph is narrowed to leave room for a bullet and space after the bullet. When bullet is #false, then • is used for item or ◦ is used for subitem.

> lines(
    @para{Outline},
    @item{Introduction},
    @subitem{short version},
    @subitem{long version},
    @item{Conclusion}
  )

function

fun verbatim(content :: TextContent, ...,

~font: font :: draw.Font = current_font()) :: Pict

Accepts content similar to tt, but recognizes newline characters as line breaks.

> @verbatim{
   Say ``hello''
   for me!
  }

context parameter

Parameter.def current_font :: draw.Font

The default font used by functions from pict/text for formatting text, including by t and para.

context parameter

Parameter.def current_font_to_tt :: (draw.Font -> draw.Font)

context parameter

Parameter.def current_font_to_roman :: (draw.Font -> draw.Font)

Font adjusters used by tt, roman, ttly, and romanly to modify a font to change it to a fixed-width or serif one.

context parameter

Parameter.def current_para_width :: Real

The default line width for para and related functions.

context parameter

Parameter.def current_line_sep :: Real

The default amount of separate used between lines by lines, para and related functions.

1	Overview
2	Pict Objects
3	Pict Constructors
4	Pict Combiners
5	Pict Animators
6	Pict Rebuilds
7	Pict Finders
8	Pict Text Layout
9	Pict Radial Shapes
10	Pict Speech Balloons
11	Code as Picts