Skip to main content

Search OfficeIMO

Enter a topic, API type, or PowerShell command.

Documentation Search all OfficeIMO/
Class

OfficeTextLayoutEngine

OfficeIMO.Drawing

Namespace
OfficeIMO.Drawing
Assembly
OfficeIMO.Core
Source revision
ba882f6b0d07 with working tree changes
Modifiers
static

Shared dependency-free text layout helpers for OfficeIMO renderers.

Inheritance

  • object
  • OfficeTextLayoutEngine

Methods

ClipTextBlockToHeight 2 overloads
public static OfficeTextBlockLayout ClipTextBlockToHeight(IReadOnlyList<OfficeTextLine> lines, double fontSize, double lineHeight, double maxWidth, double maxHeight, Func<string?, double, double> measure, bool alreadyClipped = false) #

Clips measured text lines to the requested block height and ellipsizes the last visible line when lines are omitted.

Parameters

lines System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeTextLine> required
Measured text lines to clip.
fontSize double required
Resolved font size used for measurement.
lineHeight double required
Resolved line height.
maxWidth double required
Maximum line width used for ellipsis trimming.
maxHeight double required
Maximum block height.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
alreadyClipped bool = false optional
Whether an earlier layout stage already clipped or ellipsized the text.

Returns

OfficeTextBlockLayout A measured text block whose visible lines fit the requested height.
public static OfficeTextBlockLayout ClipTextBlockToHeight(IReadOnlyList<OfficeTextLine> lines, double fontSize, double lineHeight, double maxWidth, double maxHeight, Func<string?, double, double> measure, bool alreadyClipped, OfficeTextOverflowBehavior overflowBehavior) #

Clips measured text lines to the requested block height and applies the requested overflow policy to omitted lines.

Parameters

lines System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeTextLine> required
Measured text lines to clip.
fontSize double required
Resolved font size used for measurement.
lineHeight double required
Resolved line height.
maxWidth double required
Maximum line width used for ellipsis trimming.
maxHeight double required
Maximum block height.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
alreadyClipped bool required
Whether an earlier layout stage already clipped or ellipsized the text.
overflowBehavior OfficeIMO.Drawing.OfficeTextOverflowBehavior required
How omitted or oversized text should be represented in the returned layout.

Returns

OfficeTextBlockLayout A measured text block whose visible lines fit the requested height.
public static double FitSingleLineFontSize(string? text, double fontSize, double maxWidth, double minimumFontSize, Func<string?, double, double> measure, int iterations = 10) #

Finds the largest single-line font size that fits within the requested width.

Parameters

text string? required
Text to measure.
fontSize double required
Initial font size passed to measure.
maxWidth double required
Maximum accepted line width.
minimumFontSize double required
Minimum font size when fitting is required.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
iterations int = 10 optional
Number of binary-search iterations used between the minimum and initial font size.

Returns

double The initial font size when text already fits; otherwise the largest measured size above the minimum that fits.
public static OfficeTextBlockLayout FitWrappedText(string? text, double fontSize, double maxWidth, double maxHeight, double lineHeightFactor, double minimumFontSize, Func<string?, double, double> measure, OfficeTextParagraphIndent? paragraphIndent = null) #

Wraps and measures a text block, reducing font size when the measured block does not fit the requested bounds.

Parameters

text string? required
Text to wrap and measure.
fontSize double required
Initial font size passed to measure.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used to derive line height from font size.
minimumFontSize double required
Minimum font size when scaling down to fit.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while fitting wrapped text.

Returns

OfficeTextBlockLayout Measured text block with the resolved font size, line height, width, height, and lines.
LayoutRichTextBlock 5 overloads
public static OfficeRichTextBlockLayout LayoutRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, double> measure, bool wrap, bool shrinkToFit = false, double minimumFontSize = 1, OfficeTextParagraphIndent? paragraphIndent = null) #

Lays out styled rich text runs into a bounded text block with optional wrapping and height clipping.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled. Hard line breaks are always honored.
shrinkToFit bool = false optional
Whether non-wrapped rich text should proportionally shrink run font sizes to fit the requested width.
minimumFontSize double = 1 optional
Minimum font size for any run when shrinkToFit is enabled.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while laying out wrapped rich text.

Returns

OfficeRichTextBlockLayout Measured rich text block with visible lines and clipping state.
public static OfficeRichTextBlockLayout LayoutRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, double> measure, bool wrap, bool shrinkToFit, double minimumFontSize, OfficeTextOverflowBehavior overflowBehavior, OfficeTextParagraphIndent? paragraphIndent = null) #

Lays out styled rich text runs into a bounded text block with optional wrapping, overflow policy, and height clipping.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled. Hard line breaks are always honored.
shrinkToFit bool required
Whether non-wrapped rich text should proportionally shrink run font sizes to fit the requested width.
minimumFontSize double required
Minimum font size for any run when shrinkToFit is enabled.
overflowBehavior OfficeIMO.Drawing.OfficeTextOverflowBehavior required
How overflowing rich text should be represented in the returned layout.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while laying out wrapped rich text.

Returns

OfficeRichTextBlockLayout Measured rich text block with visible lines and clipping state.
public static OfficeRichTextBlockLayout LayoutRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, string?, double> measure, bool wrap, bool shrinkToFit = false, double minimumFontSize = 1, OfficeTextParagraphIndent? paragraphIndent = null) #

Lays out styled rich text runs into a bounded text block with optional wrapping and height clipping.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, string?, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled. Hard line breaks are always honored.
shrinkToFit bool = false optional
Whether non-wrapped rich text should proportionally shrink run font sizes to fit the requested width.
minimumFontSize double = 1 optional
Minimum font size for any run when shrinkToFit is enabled.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while laying out wrapped rich text.

Returns

OfficeRichTextBlockLayout Measured rich text block with visible lines and clipping state.
public static OfficeRichTextBlockLayout LayoutRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, string?, double> measure, bool wrap, bool shrinkToFit, double minimumFontSize, OfficeTextOverflowBehavior overflowBehavior, OfficeTextParagraphIndent? paragraphIndent = null) #

Lays out styled rich text runs into a bounded text block with optional wrapping, overflow policy, and height clipping.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, string?, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled. Hard line breaks are always honored.
shrinkToFit bool required
Whether non-wrapped rich text should proportionally shrink run font sizes to fit the requested width.
minimumFontSize double required
Minimum font size for any run when shrinkToFit is enabled.
overflowBehavior OfficeIMO.Drawing.OfficeTextOverflowBehavior required
How overflowing rich text should be represented in the returned layout.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while laying out wrapped rich text.

Returns

OfficeRichTextBlockLayout Measured rich text block with visible lines and clipping state.
public static OfficeRichTextBlockLayout LayoutRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, string?, double> measure, bool wrap, bool shrinkToFit, double minimumFontSize, OfficeTextOverflowBehavior overflowBehavior, OfficeTextParagraphIndent? paragraphIndent, CancellationToken cancellationToken) #

Lays out styled rich text runs into a bounded text block with cooperative cancellation.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, string?, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled. Hard line breaks are always honored.
shrinkToFit bool required
Whether non-wrapped rich text should proportionally shrink run font sizes to fit the requested width.
minimumFontSize double required
Minimum font size for any run when shrinkToFit is enabled.
overflowBehavior OfficeIMO.Drawing.OfficeTextOverflowBehavior required
How overflowing rich text should be represented in the returned layout.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? required
Optional first-line and continuation-line offsets applied while laying out wrapped rich text.
cancellationToken System.Threading.CancellationToken required
Token checked while normalizing, tokenizing, measuring, and wrapping rich text.

Returns

OfficeRichTextBlockLayout Measured rich text block with visible lines and clipping state.
LayoutStackedRichTextBlock 2 overloads
public static OfficeRichTextBlockLayout LayoutStackedRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, double> measure, bool shrinkToFit = true, double minimumFontSize = 1) #

Lays out styled rich text runs as upright stacked text elements for vertical cell and shape renderers.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum stacked block width.
maxHeight double required
Maximum stacked block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
shrinkToFit bool = true optional
Whether the stacked block should reduce font sizes to fit both width and height.
minimumFontSize double = 1 optional
Minimum font size when scaling down to fit.

Returns

OfficeRichTextBlockLayout A measured rich text block with one Unicode text element per line.
public static OfficeRichTextBlockLayout LayoutStackedRichTextBlock(IReadOnlyList<OfficeRichTextRun> runs, double maxWidth, double maxHeight, double lineHeightFactor, Func<string?, double, string?, double> measure, bool shrinkToFit = true, double minimumFontSize = 1) #

Lays out styled rich text runs as upright stacked text elements for vertical cell and shape renderers.

Parameters

runs System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeRichTextRun> required
Styled text runs.
maxWidth double required
Maximum stacked block width.
maxHeight double required
Maximum stacked block height.
lineHeightFactor double required
Multiplier used with the largest run font size to derive line height.
measure System.Func<string?, double, string?, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
shrinkToFit bool = true optional
Whether the stacked block should reduce font sizes to fit both width and height.
minimumFontSize double = 1 optional
Minimum font size when scaling down to fit.

Returns

OfficeRichTextBlockLayout A measured rich text block with one Unicode text element per line.
public static OfficeTextBlockLayout LayoutStackedTextBlock(string? text, double fontSize, double maxWidth, double maxHeight, double lineHeightFactor, double minimumFontSize, Func<string?, double, double> measure, bool shrinkToFit = true) #

Lays out text as upright stacked text elements for vertical cell and shape renderers.

Parameters

text string? required
Text to stack. CR/LF breaks are ignored because each text element becomes its own line.
fontSize double required
Initial font size passed to measure.
maxWidth double required
Maximum stacked block width.
maxHeight double required
Maximum stacked block height.
lineHeightFactor double required
Multiplier used to derive line height from font size.
minimumFontSize double required
Minimum font size when scaling down to fit.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
shrinkToFit bool = true optional
Whether the stacked block should reduce font size to fit both width and height.

Returns

OfficeTextBlockLayout A measured text block with one Unicode text element per line.
LayoutTextBlock 2 overloads
public static OfficeTextBlockLayout LayoutTextBlock(string? text, double fontSize, double maxWidth, double maxHeight, double lineHeightFactor, double minimumFontSize, Func<string?, double, double> measure, bool wrap, bool forceSingleLine = false, bool shrinkToFit = false, OfficeTextParagraphIndent? paragraphIndent = null) #

Lays out a bounded text block with optional wrapping, single-line normalization, shrink-to-fit, and height clipping.

Parameters

text string? required
Text to lay out.
fontSize double required
Initial font size passed to measure.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used to derive line height from font size.
minimumFontSize double required
Minimum font size when single-line shrink-to-fit is enabled.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled.
forceSingleLine bool = false optional
Whether line breaks should be normalized to spaces and wrapping disabled.
shrinkToFit bool = false optional
Whether single-line text should reduce font size to fit the requested width.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while laying out wrapped text.

Returns

OfficeTextBlockLayout Measured text block with the resolved font size, line height, width, height, lines, and clipping state.
public static OfficeTextBlockLayout LayoutTextBlock(string? text, double fontSize, double maxWidth, double maxHeight, double lineHeightFactor, double minimumFontSize, Func<string?, double, double> measure, bool wrap, bool forceSingleLine, bool shrinkToFit, OfficeTextOverflowBehavior overflowBehavior, OfficeTextParagraphIndent? paragraphIndent = null) #

Lays out a bounded text block with optional wrapping, single-line normalization, shrink-to-fit, overflow policy, and height clipping.

Parameters

text string? required
Text to lay out.
fontSize double required
Initial font size passed to measure.
maxWidth double required
Maximum block width.
maxHeight double required
Maximum block height.
lineHeightFactor double required
Multiplier used to derive line height from font size.
minimumFontSize double required
Minimum font size when single-line shrink-to-fit is enabled.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
wrap bool required
Whether soft wrapping is enabled.
forceSingleLine bool required
Whether line breaks should be normalized to spaces and wrapping disabled.
shrinkToFit bool required
Whether single-line text should reduce font size to fit the requested width.
overflowBehavior OfficeIMO.Drawing.OfficeTextOverflowBehavior required
How overflowing text should be represented in the returned layout.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while laying out wrapped text.

Returns

OfficeTextBlockLayout Measured text block with the resolved font size, line height, width, height, lines, and clipping state.
public static double MeasureMaxLineWidth(IReadOnlyList<OfficeTextLine> lines) #

Gets the widest measured line.

Parameters

lines System.Collections.Generic.IReadOnlyList<OfficeIMO.Drawing.OfficeTextLine> required
Measured text lines.

Returns

double The maximum OfficeTextLine.Width value, or zero for an empty set.
public static IReadOnlyList<OfficeTextLine> MeasureUnwrappedLines(string? text, double fontSize, Func<string?, double, double> measure) #

Measures authored lines without applying word wrapping or trimming authored whitespace. Tabs are expanded deterministically and line-count/text-size safety limits still apply.

Parameters

text string? required
fontSize double required
measure System.Func<string?, double, double> required

Returns

IReadOnlyList<OfficeTextLine>
public static double ResolveRotatedTextWidthLimit(double availableWidth, double availableHeight, double lineHeight, double rotationDegrees) #

Estimates the maximum unrotated single-line text width that can remain inside a rotated bounding rectangle.

Parameters

availableWidth double required
Available unrotated rectangle width.
availableHeight double required
Available unrotated rectangle height.
lineHeight double required
Estimated rendered line height.
rotationDegrees double required
Clockwise rotation in degrees.

Returns

double A positive width limit that callers can pass to single-line rotated text layout.
public static OfficeTextLine TrimLineStartToWidth(string? text, double fontSize, double maxWidth, Func<string?, double, double> measure, out bool clipped) #

Measures a single line and trims the beginning with an ellipsis when it exceeds the requested width.

Parameters

text string? required
Text to measure and trim.
fontSize double required
Font size passed to measure.
maxWidth double required
Maximum accepted line width.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
clipped bool required
Set to true when the returned line had to be shortened.

Returns

OfficeTextLine The measured line, possibly shortened with a leading ellipsis.
public static OfficeTextLine TrimLineToWidth(string? text, double fontSize, double maxWidth, Func<string?, double, double> measure, out bool clipped) #

Measures a single line and trims it with an ellipsis when it exceeds the requested width.

Parameters

text string? required
Text to measure and trim.
fontSize double required
Font size passed to measure.
maxWidth double required
Maximum accepted line width.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
clipped bool required
Set to true when the returned line had to be shortened.

Returns

OfficeTextLine The measured line, possibly shortened with an ellipsis.
public static IReadOnlyList<OfficeTextLine> WrapLines(string? text, double fontSize, double maxWidth, Func<string?, double, double> measure, OfficeTextParagraphIndent? paragraphIndent = null) #

Wraps text into measured lines using the supplied measurement delegate.

Parameters

text string? required
Text to wrap. CRLF and CR line breaks are normalized to LF.
fontSize double required
Font size passed to measure.
maxWidth double required
Maximum line width before wrapping or breaking long words.
measure System.Func<string?, double, double> required
Measurement delegate matching OfficeRasterCanvas.MeasureText.
paragraphIndent OfficeIMO.Drawing.OfficeTextParagraphIndent? = null optional
Optional first-line and continuation-line offsets applied while wrapping.

Returns

IReadOnlyList<OfficeTextLine> Measured wrapped lines. Empty input returns one empty line.