Class TextBlock

Namespace

SixLabors.Fonts

Assembly

SixLabors.Fonts.dll

Represents text prepared for repeated line layout, measurement, and rendering.

public sealed class TextBlock

Inheritance

object

TextBlock

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Instances are safe to measure and render concurrently. The block retains the most recent line-broken layout; concurrent calls can only duplicate deterministic layout work, never observe partial state.

Constructors

TextBlock(ReadOnlySpan<char>, TextOptions)

Initializes a new instance of the TextBlock class.

public TextBlock(ReadOnlySpan<char> text, TextOptions options)

Parameters

text ReadOnlySpan<char>

The text to prepare.

options TextOptions

The text options used to prepare, measure, and render the block.

Remarks

WrappingLength and VisibleBounds are ignored while preparing the block; pass the wrapping length (use -1 to disable wrapping) and any visible bounds to the measurement or rendering methods.

TextBlock(string, TextOptions)

Initializes a new instance of the TextBlock class.

public TextBlock(string text, TextOptions options)

Parameters

text string

The text to prepare.

options TextOptions

The text options used to prepare, measure, and render the block.

Remarks

WrappingLength and VisibleBounds are ignored while preparing the block; pass the wrapping length (use -1 to disable wrapping) and any visible bounds to the measurement or rendering methods.

Properties

TextDecorationSkipInk

Gets a value indicating whether underline and overline decorations skip over glyph ink when this block is rendered.

public TextDecorationSkipInk TextDecorationSkipInk { get; }

Property Value

TextDecorationSkipInk

Methods

CountLines(float)

Gets the number of laid-out lines at the supplied wrapping length.

public int CountLines(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

int

The laid-out line count.

EnumerateLineLayouts()

Creates an enumerator that lays out this block one line at a time.

public LineLayoutEnumerator EnumerateLineLayouts()

Returns

LineLayoutEnumerator

A line layout enumerator for this block.

GetGlyphMetrics(float)

Gets the positioned metrics of each laid-out glyph entry.

public ReadOnlyMemory<GlyphMetrics> GetGlyphMetrics(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

ReadOnlyMemory<GlyphMetrics>

A read-only memory region containing per-glyph metrics entries.

GetGraphemeMetrics(float)

Gets the positioned metrics of each laid-out grapheme.

public ReadOnlyMemory<GraphemeMetrics> GetGraphemeMetrics(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

ReadOnlyMemory<GraphemeMetrics>

A read-only memory region containing per-grapheme metrics entries.

GetIntersections(float, float, float)

Gets the x-axis intervals where the laid-out glyph outlines cross a horizontal band. Glyphs whose bounds do not touch the band skip outline decoding entirely.

public ReadOnlyMemory<float> GetIntersections(float wrappingLength, float lowerLimit, float upperLimit)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

lowerLimit float

One edge of the horizontal band.

upperLimit float

The other edge of the horizontal band.

Returns

ReadOnlyMemory<float>

A read-only memory region containing merged, x-sorted interval pairs (start, end, start, end, ...); empty when no outline crosses the band.

GetLineLayouts(float)

Gets visual line layouts for this block at the supplied wrapping length.

public ReadOnlyMemory<LineLayout> GetLineLayouts(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

ReadOnlyMemory<LineLayout>

A read-only memory region containing LineLayout entries in final layout order.

Remarks

The returned memory contains every laid-out line, including lines produced by hard line breaks.

GetLineMetrics(float)

Gets per-line layout metrics at the supplied wrapping length.

public ReadOnlyMemory<LineMetrics> GetLineMetrics(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

ReadOnlyMemory<LineMetrics>

A read-only memory region containing LineMetrics in pixel units.

GetWordMetrics(float)

Gets the positioned metrics of each Unicode word-boundary segment.

public ReadOnlyMemory<WordMetrics> GetWordMetrics(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

ReadOnlyMemory<WordMetrics>

A read-only memory region containing per-word-boundary segment metrics entries.

Measure(float)

Measures the full set of layout metrics for this block at the supplied wrapping length.

public TextMetrics Measure(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

TextMetrics

A TextMetrics instance containing every measurement for the laid-out text.

MeasureAdvance(float)

Measures the logical advance of this block at the supplied wrapping length.

public FontRectangle MeasureAdvance(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

FontRectangle

The logical advance rectangle.

MeasureBounds(float)

Measures the rendered glyph bounds of this block at the supplied wrapping length.

public FontRectangle MeasureBounds(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

FontRectangle

The rendered glyph bounds.

MeasureRenderableBounds(float)

Measures the union of logical advance and rendered glyph bounds at the supplied wrapping length.

public FontRectangle MeasureRenderableBounds(float wrappingLength)

Parameters

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

Returns

FontRectangle

The full renderable bounds.

RenderTo(IGlyphRenderer, float)

Renders this block to the supplied glyph renderer at the supplied wrapping length.

public void RenderTo(IGlyphRenderer renderer, float wrappingLength)

Parameters

renderer IGlyphRenderer

The target renderer.

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

RenderTo(IGlyphRenderer, float, in FontRectangle)

Renders the visible portion of this block to the supplied glyph renderer at the supplied wrapping length, culling whole lines that lie outside the supplied visible bounds.

public void RenderTo(IGlyphRenderer renderer, float wrappingLength, in FontRectangle visibleBounds)

Parameters

renderer IGlyphRenderer

The target renderer.

wrappingLength float

The wrapping length in pixels. Use -1 to disable wrapping.

visibleBounds FontRectangle

The visible region in pixels, in the same space as the rendered output.

Remarks

Culling is line-granular: every glyph on a line intersecting visibleBounds is rendered, and the comparison inflates each line box by one line height on each side so ink or decorations overhanging a line box never disappear at the band edges. A culled line still advances layout, so visible lines render at positions identical to a full render, and BeginText(in FontRectangle) always receives the full text bounds.