58.4 Text Content and Layout

9.3

Racket

58.4 Text Content and Layout🔗ℹ

Use plain-text for a single line, paragraph for line breaks or wrapping, and rich-text for styled spans. These constructors store explicit text properties. Use the role-based constructors in Semantic Text and Typography when properties should inherit from a typography theme.

58.4.1 Plain, Multiline, and Rich Text Visuals

58.4.1.1 Constructing Text Visuals

58.4.1.2 Inspecting and Updating Text

58.4.1 Plain, Multiline, and Rich Text Visuals🔗ℹ

A text Visual stores immutable Unicode content, inline style runs, and explicit font/layout anchors. plain-text preserves the original one-line API; paragraph adds explicit lines and renderer-measured wrapping; and rich-text adds styled spans. Every form implements gen:visual, gen:affine-visual, and gen:opacity-visual. Its raw structure constructor and internal transform and opacity fields are not public.

The reference position is an anchor selected on the untransformed text box. Horizontal alignment chooses its left edge, center, or right edge. Vertical alignment chooses its top edge, center, font baseline, or bottom edge. For a paragraph the baseline is the first rendered line’s baseline. Scale and rotation are applied around that anchor.

procedure
(text-font-family? value) → boolean?
value : any/c

Returns #t when value is one of the supported portable font family symbols:

'default
'decorative
'roman
'script
'swiss
'modern
'symbol
'system

A family is a portable request, not a promise of one particular installed font face. The drawing backend chooses a suitable platform font.

procedure
(text-font-style? value) → boolean?
value : any/c

Returns #t for 'normal, 'italic, or 'slant. These are the supported font slant styles.

procedure
(text-font-weight? value) → boolean?
value : any/c

Returns #t for 'normal, 'bold, or 'light.

procedure
(text-horizontal-alignment? value) → boolean?
value : any/c

Returns #t for 'left, 'center, or 'right. The value identifies the horizontal part of the text box that is placed at the Visual’s reference position.

procedure
(text-vertical-alignment? value) → boolean?
value : any/c

Returns #t for 'top, 'center, 'baseline, or 'bottom. The 'baseline choice places the font baseline at the Visual’s reference position.

procedure
(text-span content
[ #:font-size font-size
#:font-face font-face
#:font-family font-family
#:font-style font-style
#:font-weight font-weight
#:color color]) → text-span?
  content : string?
  font-size : (or/c false/c (and/c finite-real? positive?)) = #f
  font-face : (or/c false/c string?) = #f
  font-family : (or/c false/c text-font-family?) = #f
  font-style : (or/c false/c text-font-style?) = #f
  font-weight : (or/c false/c text-font-weight?) = #f
  color : any/c = #f

Creates one immutable inline rich-text run. A false style keyword inherits the corresponding outer rich-text style. Spans may contain explicit line breaks. They are text only: a formula, image, or another Visual cannot be an inline span.

procedure
(text-span? value) → boolean?
value : any/c

Returns #t when value is a built-in immutable text span.

procedure
(text-span-content span) → string?
span : text-span?

Returns the span’s immutable Unicode source text.

procedure
(text-span-font-size span)
→ (or/c false/c (and/c finite-real? positive?))
span : text-span?

Returns the optional local font size, or #f when it inherits.

procedure
(text-span-font-face span) → (or/c false/c string?)
span : text-span?

Returns the optional preferred face string.

procedure
(text-span-font-family span) → (or/c false/c text-font-family?)
span : text-span?

Returns the optional portable font family.

procedure
(text-span-font-style span) → (or/c false/c text-font-style?)
span : text-span?

Returns the optional font slant.

procedure
(text-span-font-weight span) → (or/c false/c text-font-weight?)
span : text-span?

Returns the optional font weight.

procedure
(text-span-color span) → any/c
span : text-span?

Returns the optional adapter colour, or #f when it inherits.

58.4.1.1 Constructing Text Visuals🔗ℹ

procedure
(plain-text content
#:id id
[ #:center center
#:rotation rotation
#:scale scale
#:opacity opacity
#:font-size font-size
#:font-face font-face
#:font-family font-family
#:font-style font-style
#:font-weight font-weight
#:color color
#:horizontal-alignment horizontal-alignment
#:vertical-alignment vertical-alignment])
→ text-visual?
  content : string?
  id : symbol?
  center : vec2? = origin
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  font-size : (and/c finite-real? positive?) = 1/2
  font-face : (or/c string? #f) = #f
  font-family : text-font-family? = 'default
  font-style : text-font-style? = 'normal
  font-weight : text-font-weight? = 'normal
  color : any/c = theme-foreground
  horizontal-alignment : text-horizontal-alignment? = 'center
  vertical-alignment : text-vertical-alignment? = 'center

Creates a semantic one-line text Visual. The required id is its stable Visual identity. center is the selected text anchor in the containing coordinate system. At the top level it is a world-space point; inside a group it is local to that group.

content may be empty and may contain arbitrary Unicode characters, but it may not contain a carriage return or newline. The constructor copies the string into immutable storage. A mutable font-face string is copied in the same way. A false font-face asks the backend to select a face from font-family. When both are supplied, the face is preferred and the family remains the fallback classification.

font-size is measured in local world units before the Visual’s scale is applied. The default is one half world unit. Non-uniform scale may stretch the rendered text independently in x and y. Rotation is counter-clockwise in radians.

color is deliberately opaque model data. The built-in Pict renderer passes it to Pict color handling. A different renderer may interpret it differently. opacity is semantic global opacity and is applied to the complete rendered line after renderer dispatch.

The alignment arguments determine which point of the original text box is at center. Alignment is resolved before scale and rotation. This makes a left-baseline label, for example, grow to the right and rotate around the start of its baseline.

procedure
(paragraph content
#:id id
[ #:center center
#:rotation rotation
#:scale scale
#:opacity opacity
#:font-size font-size
#:font-face font-face
#:font-family font-family
#:font-style font-style
#:font-weight font-weight
#:color color
#:horizontal-alignment horizontal-alignment
#:vertical-alignment vertical-alignment
#:width width
#:line-spacing line-spacing
#:line-alignment line-alignment])
→ text-visual?
  content : string?
  id : symbol?
  center : vec2? = origin
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  font-size : (and/c finite-real? positive?) = 1/2
  font-face : (or/c string? #f) = #f
  font-family : text-font-family? = 'default
  font-style : text-font-style? = 'normal
  font-weight : text-font-weight? = 'normal
  color : any/c = theme-foreground
  horizontal-alignment : text-horizontal-alignment? = 'center
  vertical-alignment : text-vertical-alignment? = 'center
  width : (or/c false/c (and/c finite-real? positive?)) = #f
  line-spacing : (and/c finite-real? positive?) = 1
  line-alignment : text-horizontal-alignment? = 'left

Creates one ordinary multiline text Visual. Carriage-return, newline, and CRLF sequences are explicit line breaks. With a false width, only those explicit breaks create lines. Otherwise, width is a positive local world-space maximum: at rendering time Animate measures text runs with the active camera/font backend and wraps at inter-word whitespace. It does not hyphenate an overlong word.

line-spacing multiplies the largest natural line height in the paragraph. line-alignment aligns every resolved line inside the widest resolved line, while horizontal-alignment selects the anchor of that complete paragraph. The first line supplies a 'baseline anchor.

procedure
(rich-text #:id id
[ #:center center
#:rotation rotation
#:scale scale
#:opacity opacity
#:font-size font-size
#:font-face font-face
#:font-family font-family
#:font-style font-style
#:font-weight font-weight
#:color color
#:horizontal-alignment horizontal-alignment
#:vertical-alignment vertical-alignment
#:width width
#:line-spacing line-spacing
#:line-alignment line-alignment]
piece ...)
→ text-visual?
  id : symbol?
  center : vec2? = origin
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  font-size : (and/c finite-real? positive?) = 1/2
  font-face : (or/c string? #f) = #f
  font-family : text-font-family? = 'default
  font-style : text-font-style? = 'normal
  font-weight : text-font-weight? = 'normal
  color : any/c = theme-foreground
  horizontal-alignment : text-horizontal-alignment? = 'center
  vertical-alignment : text-vertical-alignment? = 'center
  width : (or/c false/c (and/c finite-real? positive?)) = #f
  line-spacing : (and/c finite-real? positive?) = 1
  line-alignment : text-horizontal-alignment? = 'left
  piece : (or/c string? text-span?)

Creates a paragraph layout from ordinary strings and text-span values. Strings inherit all outer font properties. A span overrides only its specified properties. The wrapping, line-spacing, and anchor rules are the same as for paragraph. Adjacent spans are separately shaped Pict runs, so a font backend cannot kern or ligate across their boundary.

Spans retain one combined source string.

Examples:

> (define label
(rich-text #:id 'label
"x = " (text-span "2" #:font-weight 'bold)))
> (text-visual-content label)
"x = 2"

58.4.1.2 Inspecting and Updating Text🔗ℹ

procedure
(text-visual? value) → boolean?
value : any/c

Returns #t when value is a built-in plain, paragraph, or rich text Visual.

procedure
(text-visual-content visual) → string?
visual : text-visual?

Returns the immutable concatenation of the Visual’s source text spans. It can contain explicit line breaks; automatic wrapping does not alter this source.

procedure
(text-visual-spans visual) → (listof text-span?)
visual : text-visual?

Returns the significant ordered immutable rich-text spans. A plain-text or paragraph Visual contains one inheriting span.

procedure
(text-visual-font-size visual) → (and/c finite-real? positive?)
visual : text-visual?

Returns the unscaled font size in local world units.

procedure
(text-visual-font-face visual) → (or/c string? #f)
visual : text-visual?

Returns the preferred immutable font-face string, or #f when no face was requested. Font availability and exact substitution are properties of the rendering environment, not the semantic model.

procedure
(text-visual-font-family visual) → text-font-family?
visual : text-visual?

Returns the portable fallback font-family symbol.

procedure
(text-visual-font-style visual) → text-font-style?
visual : text-visual?

Returns the stored font slant style.

procedure
(text-visual-font-weight visual) → text-font-weight?
visual : text-visual?

Returns the stored font weight.

procedure
(text-visual-color visual) → any/c
visual : text-visual?

Returns the stored adapter color value.

procedure
(text-visual-horizontal-alignment visual)
→ text-horizontal-alignment?
visual : text-visual?

Returns the horizontal anchor alignment.

procedure
(text-visual-vertical-alignment visual)
→ text-vertical-alignment?
visual : text-visual?

Returns the vertical anchor alignment.

procedure
(text-visual-width visual)
→ (or/c false/c (and/c finite-real? positive?))
visual : text-visual?

Returns the requested local world-space wrapping width, or #f when only explicit line breaks determine lines.

procedure
(text-visual-line-spacing visual)
→ (and/c finite-real? positive?)
visual : text-visual?

Returns the multiplicative resolved-line advance.

procedure
(text-visual-line-alignment visual)
→ text-horizontal-alignment?
visual : text-visual?

Returns the alignment used inside the resolved paragraph width.

procedure
(text-visual-with-content visual content) → text-visual?
visual : text-visual?
content : string?

Returns a new text Visual with content installed as one inheriting immutable span. Identity, affine transform, opacity, font data, colour, and layout options are preserved. Explicit line breaks are accepted; the original Visual is unchanged.

Changing content returns a new value.

Examples:

> (define before (plain-text "x = 2" #:id 'value))
> (define after (text-visual-with-content before "x = 3"))
> (text-visual-content before)
"x = 2"
> (text-visual-content after)
"x = 3"

procedure
(text-visual-with-spans visual spans) → text-visual?
visual : text-visual?
spans : (listof text-span?)

Returns a new text Visual with spans installed atomically. Outer font defaults and all layout/anchor settings are preserved. The content accessor of the result is the immutable concatenation of the supplied spans.

I	Concepts
II	Cookbook
III	Guide
IV	Complete Example Programs
V	Reference

52	Find a task or a name
53	Modules to require
54	Scenes and sampling
55	Scene states
56	Animation requests
57	Native model details
58	Visuals
59	Geometry
60	Number Lines and Coordinate Decorations
61	Point Markers, Scatter Plots, and Filled Areas
62	Probability and Statistical Diagrams
63	Calculus lessons
64	Colors
65	Slides
66	Slide command-line tools
67	Source Programs and Authored Timelines
68	Interactive Preview and Inspection
69	Preview controls and diagnostics
70	Projects and Final Rendering
71	Project execution and cache details
72	Pict Renderer Protocol
73	3D reference map
74	3D: Objects, groups, and paths
75	3D: Cameras and projection
76	3D: Views inside a Scene
77	3D: Animating 3D objects
78	3D: Animating the 3D camera
79	3D: Cuts, caps, and section measurements
80	3D: Supplementary surface, section, and annotation bindings
81	3D: Cuts, sections, and numerical volume
82	3D: Vectors
83	3D: Linear maps and rotations
84	3D: Affine transforms
85	3D: Bounds, rays, and planes
86	3D: Spatial maps and homotopies
87	3D: Materials and lights
88	3D: Lighting inspection
89	3D: Shadow descriptors and stable bounds
90	3D: Finite-light animation
91	3D: Software finite-light evaluation
92	3D: Colour space and final output
93	3D: Relations and geometric annotations
94	3D: Projected labels
95	3D: Textured billboards
96	3D: Spatial curves and vector diagrams
97	3D: Spatial anchors and label layout
98	3D: Anchors and projected labels
99	3D: Parametric surfaces and calculus
100	3D: Adaptive, trimmed, and implicit surfaces
101	3D: Constructive solids
102	3D: Surface constructors and queries
103	3D: Meshes
104	3D: Triangle topology
105	3D: Polygonal faces
106	3D: Deterministic convex hulls
107	3D: Polyhedral duals
108	3D: Schlegel diagrams and polyhedral nets
109	3D: Conservative mesh correspondence
110	3D: Topology-safe mesh matching
111	3D: Checking and repairing mesh orientation
112	3D: Clipping, sections, and transparency
113	3D: Prepared spatial ODE trajectories and vector fields
114	3D: Seeds and streamline sets
115	3D: Poincare sections and return maps
116	3D: Equilibria and local linearization
117	3D: Flow maps and volume change
118	3D: Drawing and inspecting trajectories
119	3D: Reading prepared trajectories
120	3D: Drawing vector fields and particles
121	3D: Trajectory display
122	3D: Spatial inspection and exact picking
123	3D: Retained renderer backends
124	3D: Compiled geometry and instances
125	3D: Frame requests and results
126	3D: Software rendering and statistics
127	3D: Optional Racket/ Open GL backend
128	Experimental Derived Visuals
129	Source Package Hygiene

58.1	Visual Protocols and Groups
58.2	Shapes and Path Visuals
58.3	Bitmap and SVG Visuals
58.4	Text Content and Layout
58.5	Semantic Text and Typography Styles
58.6	Numbers and Units
58.7	Matrices, Tables, and Vector Diagrams
58.8	Formula Construction and Layout
58.9	Formula Assemblies and Named Parts
58.10	Formula Source Selection and Matching
58.11	Arrows and Coordinate Axes
58.12	Live Endpoints and Mathematical Annotations
58.13	Complex and Polar Visuals
58.14	Function, Parametric, and Data Plots
58.15	Graph Helpers and Traced Paths
58.16	ODE Trajectories and Streamlines
58.17	Relations and Live Layout