9.3
58.5 Semantic Text and Typography Styles
A semantic text Visual retains a role and its explicit overrides; a text-style is a complete style, and a typography-theme is an immutable table of styles. text-treatment adds padding, background, and a cosmetic border. The contracts below distinguish an omitted property (inherit or retain) from an explicit #f (clear an optional property).
See also Text Content and Layout, Numbers and Units.
58.5.1 Semantic Text and Typography
Semantic text stores a presentation role instead of a resolved platform font. It lowers to the ordinary text-visual? protocol only when Animate renders or measures it under an explicit typography snapshot. Raw plain-text, paragraph, and rich-text remain independent of typography themes.
58.5.1.1 Backgrounds, Borders, and Padding
procedure
(text-treatment [ #:background background #:border-color border-color #:border-width border-width #:padding-x padding-x #:padding-y padding-y]) → text-treatment? background : (or/c false/c paint?) = #f border-color : (or/c false/c color-spec?) = #f border-width : (and/c finite-real? (>=/c 0)) = 0 padding-x : (and/c finite-real? (>=/c 0)) = 0 padding-y : (and/c finite-real? (>=/c 0)) = 0
Creates immutable optional presentation treatment for semantic text. Padding is
in ems of the resolved outer style. A border width is cosmetic device width:
semantic scaling changes the treatment box but not the visible pen thickness.
The treatment decorates the final text-content box, then that decorated box is
anchored, so its logical text anchor remains fixed. A border width of zero does
not draw a border.
A structured background paint uses the same local coordinates as every other Paint: the semantic text anchor is the origin, positive x points right, and positive y points up. Linear and radial gradients follow text placement, scaling, and rotation rather than starting at the treatment box’s top-left corner. The current Pict backend draws a checker-pattern as a device-aligned tile, so checker cells do not yet fully follow scale or rotation.
The built-in text renderer knows that content box exactly. A custom Pict renderer for a semantic text value instead declares its own logical Pict box; the treatment decorates that declared box. Animate does not inspect rendered pixels to guess a tighter ink box for custom renderers. Its treatment anchor is the center of the declared box, independently of the text alignment stored on the Visual. Backgrounds and padding scale with the Pict; a treatment border is added after that scale, so its width stays cosmetic (in device pixels).
procedure
(text-treatment? value) → boolean?
value : any/c
Returns #t when value is an immutable semantic text
treatment.
procedure
(text-treatment-background treatment) → (or/c false/c paint?)
treatment : text-treatment? (text-treatment-border-color treatment) → (or/c false/c color-spec?) treatment : text-treatment? (text-treatment-border-width treatment) → (and/c finite-real? (>=/c 0)) treatment : text-treatment? (text-treatment-padding-x treatment) → (and/c finite-real? (>=/c 0)) treatment : text-treatment? (text-treatment-padding-y treatment) → (and/c finite-real? (>=/c 0)) treatment : text-treatment?
Returns one immutable treatment property. Padding values are em multipliers,
not world distances or pixels.
procedure
(text-treatment-update treatment #:background background #:border-color border-color #:border-width border-width #:padding-x padding-x #:padding-y padding-y) → text-treatment? treatment : text-treatment? background : (or/c false/c paint?) border-color : (or/c false/c color-spec?) border-width : (and/c finite-real? (>=/c 0)) padding-x : (and/c finite-real? (>=/c 0)) padding-y : (and/c finite-real? (>=/c 0))
Returns a new treatment. Omit a keyword to keep its value from
treatment. Supplying #f explicitly removes a background or
border color.
An explicit false border color clears it; an omitted padding value is retained.
Examples:
> (define framed (text-treatment #:border-color "gray" #:border-width 1 #:padding-x 1/2)) > (define unframed (text-treatment-update framed #:border-color #f)) > (text-treatment-border-color unframed) #f
> (text-treatment-padding-x unframed) 1/2
58.5.1.2 Complete Styles
procedure
(text-style #:font-family font-family #:font-size font-size #:font-style font-style #:font-weight font-weight #:color color #:line-spacing line-spacing #:line-alignment line-alignment #:horizontal-alignment horizontal-alignment #:vertical-alignment vertical-alignment [ #:font-face font-face #:treatment treatment]) → text-style? font-family : text-font-family? font-size : (and/c finite-real? positive?) font-style : text-font-style? font-weight : text-font-weight? color : color-spec? line-spacing : (and/c finite-real? positive?) line-alignment : text-horizontal-alignment? horizontal-alignment : text-horizontal-alignment? vertical-alignment : text-vertical-alignment? font-face : (or/c false/c string?) = #f treatment : (or/c false/c text-treatment?) = #f
Creates one complete typography style. Its color is a semantic color
specification, not resolved RGBA. text-style-update returns a copy
that changes only explicitly supplied properties; an explicit #f may
clear a font face or treatment.
procedure
(text-style? value) → boolean?
value : any/c
Returns #t when value is a complete immutable text style.
procedure
(text-style-update style #:font-face font-face #:font-family font-family #:font-size font-size #:font-style font-style #:font-weight font-weight #:color color #:line-spacing line-spacing #:line-alignment line-alignment #:horizontal-alignment horizontal-alignment #:vertical-alignment vertical-alignment #:treatment treatment) → text-style? style : text-style? font-face : (or/c false/c string?) font-family : text-font-family? font-size : (and/c finite-real? positive?) font-style : text-font-style? font-weight : text-font-weight? color : color-spec? line-spacing : (and/c finite-real? positive?) line-alignment : text-horizontal-alignment? horizontal-alignment : text-horizontal-alignment? vertical-alignment : text-vertical-alignment? treatment : (or/c false/c text-treatment?)
Returns a new complete style. Omit a keyword to retain its value from
style. For #:font-face and #:treatment, supplying
#f explicitly clears the optional value.
procedure
(text-style-font-face style) → (or/c false/c string?)
style : text-style? (text-style-font-family style) → text-font-family? style : text-style? (text-style-font-size style) → (and/c finite-real? positive?) style : text-style? (text-style-font-style style) → text-font-style? style : text-style? (text-style-font-weight style) → text-font-weight? style : text-style? (text-style-color style) → color-spec? style : text-style? (text-style-line-spacing style) → (and/c finite-real? positive?) style : text-style? (text-style-line-alignment style) → text-horizontal-alignment? style : text-style? (text-style-horizontal-alignment style) → text-horizontal-alignment? style : text-style? (text-style-vertical-alignment style) → text-vertical-alignment? style : text-style? (text-style-treatment style) → (or/c false/c text-treatment?) style : text-style?
Returns one complete property from an immutable typography style.
procedure
(text-style->datum style) → any/c
style : text-style?
Returns the deterministic complete style datum used inside a typography theme.
procedure
(datum->text-style datum) → text-style?
datum : any/c
Validates and reads a datum produced by text-style->datum.
58.5.1.3 Typography Snapshots
procedure
(typography-theme #:id id [ #:styles styles #:extends parent] #:display-name display-name [ #:provenance provenance]) → typography-theme? id : symbol? styles : (or/c hash? (listof pair?)) = #hash() parent : (or/c false/c typography-theme?) = #f display-name : string? provenance : (or/c false/c string? symbol?) = #f
Creates an immutable complete typography snapshot. A root theme must contain
the standard roles. A child copies its parent’s complete table, then replaces
named complete styles. typography-ref gets one style, and
typography-theme-fingerprint identifies its appearance-relevant
contents. typography-theme->datum and
datum->typography-theme provide the deterministic versioned data
format used by project plans and preview workers. Serialization accounts for
the complete data tree, including styles, treatments, paints, and colors, and
rejects data beyond its generous resource limits. Decoding validates the
wrapper and style entries before it traverses their contents.
procedure
(typography-theme? value) → boolean?
value : any/c
Returns #t when value is an immutable typography snapshot.
procedure
(typography-theme-id theme) → symbol?
theme : typography-theme? (typography-theme-display-name theme) → string? theme : typography-theme? (typography-theme-provenance theme) → (or/c false/c string? symbol?) theme : typography-theme? (typography-style-keys theme) → (listof symbol?) theme : typography-theme? (typography-ref theme style-key) → text-style? theme : typography-theme? style-key : symbol? (typography-theme-fingerprint theme) → bytes? theme : typography-theme? (typography-theme->datum theme) → any/c theme : typography-theme? (datum->typography-theme datum) → typography-theme? datum : any/c
Inspect, look up, fingerprint, and transport a typography snapshot.
typography-style-keys is sorted deterministically. The fingerprint
describes appearance only: a theme’s display name and provenance do not change
it. The datum procedures use the version reported by
typography-theme-schema-version.
The version of the portable typography-theme datum format.
The standard immutable role table: 'title, 'subtitle,
'section-heading, 'body, 'caption,
'label, 'quotation, 'code, and
'annotation.
value
The ordered standard role keys required by a root typography theme.
58.5.1.4 Role-Based Text
procedure
(title-text content #:id id [ #:center center] #:font-size font-size ...) → semantic-text-visual? content : string? id : symbol? center : vec2? = origin font-size : (and/c finite-real? positive?) (subtitle-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (section-heading-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (body-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (caption-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (label-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (quotation-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (code-text content #:id id ...) → semantic-text-visual? content : string? id : symbol? (annotation-text content #:id id ...) → semantic-text-visual? content : string? id : symbol?
Creates semantic text with the corresponding standard role. The common
keywords include placement and affine presentation plus explicit font, color,
alignment, width, line-spacing, and treatment overrides. In addition to a
whole #:treatment, #:background, #:border-color,
#:border-width, #:padding-x, and #:padding-y can
change one treatment property while the other properties inherit. An omitted
property inherits from the role. A semantic text value retains that inheritance
data in the Scene.
procedure
(styled-text content #:style style-key #:id id ...) → semantic-text-visual? content : string? style-key : symbol? id : symbol?
Creates semantic text using a standard or custom named style. The selected
theme must contain style-key at the render or measurement boundary.
styled-rich-text is the rich-span counterpart; it accepts ordinary
strings and text-span values after its keywords.
procedure
(styled-rich-text #:style style-key #:id id [ #:center center #:rotation rotation #:scale scale #:opacity opacity #:width width] piece ...) → semantic-text-visual? style-key : symbol? id : symbol? center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 opacity : opacity? = 1 width : (or/c false/c (and/c finite-real? positive?)) = #f piece : (or/c string? text-span?)
Creates semantic rich text with the same inherited style and optional override
keywords as styled-text. The pieces retain the ordinary
rich-text span semantics after late style resolution.
procedure
(semantic-text-content visual) → string?
visual : semantic-text-visual? (semantic-text-spans visual) → (listof text-span?) visual : semantic-text-visual? (semantic-text-overrides visual) → semantic-text-overrides? visual : semantic-text-visual? (semantic-text-visual-width visual) → (or/c false/c (and/c finite-real? positive?)) visual : semantic-text-visual?
Returns the retained source data and maximum wrapping width. These are authored
data, before style resolution.
procedure
(semantic-text-override-inherited? value) → boolean?
value : any/c
Returns #t when one property in semantic-text-overrides
inherits from its named style rather than replacing it explicitly.
procedure
(semantic-text-visual? value) → boolean?
value : any/c
Recognizes a
semantic text Scene value.
procedure
(semantic-text-overrides? value) → boolean?
value : any/c
Recognizes the immutable record of explicit and inherited style properties
retained by a semantic text Visual.
procedure
(semantic-text-style-key visual) → symbol?
visual : semantic-text-visual?
Returns the retained role or custom style key.
A role-based constructor keeps its role in the model.
Examples:
> (define heading (title-text "Velocity" #:id 'heading)) > (semantic-text-style-key heading) 'title
procedure
(resolve-semantic-text-style visual theme) → text-style?
visual : semantic-text-visual? theme : typography-theme?
Purely resolves a semantic text value against one explicit immutable
typography theme. It does not render, look up platform fonts, or resolve the
style’s color specification.