TextLayoutOptions Class

How a text is laid out: the box it must fit, how its lines are broken and aligned.

public sealed class TextLayoutOptions

Remarks

The options are immutable; TextLayoutOptions.Default lays out a text of any width on one line per paragraph.

Constructors

NameDescription
TextLayoutOptions()

TextLayoutOptions()

TextLayoutOptions.cs
public TextLayoutOptions()

No documentation is available.

Properties

NameDescription
AlignmentGets how the lines are placed in the width of the layout. TextAlignment.Start by default.
CombineUprightDigitsGets the length of the runs of digits that are set horizontally in the room of one upright character of a vertical line (tate-chu-yoko): 0 (the default) for none, or 2, 3 or 4.
DefaultGets the default options: no maximum size, lines aligned at their start.
DirectionGets the base direction of the paragraphs. TextDirection.Auto by default.
EllipsisGets the text that ends a trimmed line, or null (the default) for the horizontal ellipsis (U+2026) when the font has it and three periods otherwise.
FirstLineIndentGets the space before the first line of each paragraph, in pixels; negative for a hanging indent. 0 by default.
HintingGets how the outlines of the glyphs are fitted to the pixel grid. TextHinting.None by default: the outlines are scaled exactly and the glyphs are placed at fractions of a pixel.
HyphenCharacterGets the text drawn at the end of a line that ends inside a hyphenated word, or null (the default) for the hyphen (U+2010) when the font has it and the hyphen-minus (U+002D) otherwise.
HyphenationGets whether words are hyphenated at the end of a line. TextHyphenation.Manual by default.
JustificationGets where a justified line (TextAlignment.Justify) takes the room it is stretched by: the spaces between words (TextJustification.InterWord, the default), or also between the characters of Chinese, Japanese, Korean and Thai text, or between every two characters. It is not used with another alignment.
LineBreakGets how strict the line breaking rules of Chinese and Japanese text are. TextLineBreak.Normal by default.
LineBreakDictionaryGets the words of the languages that are written without spaces between words (Thai, Lao, Khmer, Burmese), or null (the default) for the word lists of ICU.
LineBreakStrategyGets how the places where wrapped lines end are chosen: as each line is filled (TextLineBreakStrategy.Greedy, the default), or for the whole paragraph at once (TextLineBreakStrategy.Optimal). It is not used when lines are not wrapped.
LineHeightGets the height of each line, in pixels, or null (the default) for the height the fonts of the line ask for: the largest ascent, descent and line gap of the fonts used on it.
MaxHeightGets the height the lines must fit, in pixels; Double.PositiveInfinity (the default) for no limit. The lines that do not fit are not part of the layout, except the first one. In a vertical layout (TextLayoutOptions.WritingMode), it is the height lines are wrapped at and aligned in, as TextLayoutOptions.MaxWidth is in a horizontal one.
MaxLinesGets the largest number of lines; Int32.MaxValue (the default) for no limit. The lines after are not part of the layout.
MaxWidthGets the width lines are wrapped at and aligned in, in pixels; Double.PositiveInfinity (the default) for no limit: lines are then only broken at the line breaks of the text, and aligned in the width of the widest one. In a vertical layout (TextLayoutOptions.WritingMode), it is the width the lines must fit, as TextLayoutOptions.MaxHeight is in a horizontal one.
OrientationGets how the characters of a vertical line are set: each one as the Unicode Standard says (the default), all upright, or all on their side. It is not used in a horizontal layout.
OverflowWrapGets what happens to a word that is wider than TextLayoutOptions.MaxWidth. TextOverflowWrap.Normal by default.
SubpixelRenderingGets how the glyphs are antialiased when the layout is filled at a point: with one coverage per pixel (TextSubpixelRendering.None, the default), or with one per color of the pixel, for the order of the stripes of red, green and blue of the screen the image is shown on.
TabSizeGets the distance between two tabulation stops, in spaces of the font of the tabulation. 8 by default.
TabStopsGets the tabulation stops of the lines, by increasing position, or an empty list (the default) for stops every TextLayoutOptions.TabSize spaces only.
TrimmingGets what replaces the text that does not fit the layout. TextTrimming.None by default.
WordBreakGets where a line can be broken inside a word. TextWordBreak.Normal by default.
WrappingGets whether a line that is wider than TextLayoutOptions.MaxWidth continues on the next line. TextWrapping.Wrap by default.
WritingModeGets the direction of the lines: horizontal (the default), or vertical with lines that follow each other to the left or to the right.

Gets how the lines are placed in the width of the layout. TextAlignment.Start by default.

public TextAlignment Alignment { get; init; }

Property value

TextAlignment

CombineUprightDigits

TextLayoutOptions.cs

Gets the length of the runs of digits that are set horizontally in the room of one upright character of a vertical line (tate-chu-yoko): 0 (the default) for none, or 2, 3 or 4.

public int CombineUprightDigits { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not 0, 2, 3 or 4.

Remarks

A run of ASCII digits (0 to 9) that is not longer than this, between two characters that are not digits and in one span, is set as the text of a style that is combined upright (TextStyle.IsCombinedUpright): the date 2026 or the number 12 in a column of Japanese text. Longer numbers are on their side, as other text is. It is the digits value of the text-combine-upright property of CSS. It is not used in a horizontal layout, nor with TextOrientation.Sideways.

Gets the default options: no maximum size, lines aligned at their start.

public static TextLayoutOptions Default { get; }

Property value

TextLayoutOptions

Gets the base direction of the paragraphs. TextDirection.Auto by default.

public TextDirection Direction { get; init; }

Property value

TextDirection

Gets the text that ends a trimmed line, or null (the default) for the horizontal ellipsis (U+2026) when the font has it and three periods otherwise.

public string? Ellipsis { get; init; }

Property value

string?

Exceptions

ArgumentException
The value is longer than 16 characters.

FirstLineIndent

TextLayoutOptions.cs

Gets the space before the first line of each paragraph, in pixels; negative for a hanging indent. 0 by default.

public double FirstLineIndent { get; init; }

Property value

double

Exceptions

ArgumentOutOfRangeException
The value is not finite, or its magnitude exceeds 1048576.

Remarks

A positive value indents the first line of each paragraph from the side the paragraph starts from, and leaves the other lines at the edge. A negative value is a hanging indent, as text-indent: hanging in CSS: the first line starts at the edge, and the lines after it are indented by the magnitude of the value. In both cases, every line stays in the box of the layout: the indent counts in the width that is left for the line it applies to, and in the width of the layout when lines are not wrapped at TextLayoutOptions.MaxWidth.

The indent is on the left of a left-to-right paragraph, on the right of a right-to-left one, and at the top of a vertical line. TextAlignment.Center and TextAlignment.End align an indented line in the room the indent leaves.

Gets how the outlines of the glyphs are fitted to the pixel grid. TextHinting.None by default: the outlines are scaled exactly and the glyphs are placed at fractions of a pixel.

public TextHinting Hinting { get; init; }

Property value

TextHinting

Exceptions

ArgumentOutOfRangeException
The value is not a member of TextHinting.

Remarks

Hinting makes small text (9 to 16 pixels) sharper: the horizontal edges of the glyphs (the baseline, the x-height, the horizontal stems), and with TextHinting.Full the vertical ones, fall on whole pixels. The baseline of each glyph is then on a whole pixel of the layout, and with TextHinting.Full the advances are whole pixels too and each glyph starts on a whole pixel: what the layout measures is what it draws.

The grid is the pixel grid of the layout: draw it at a whole-pixel origin, without a transform that scales or rotates the canvas, for the edges to fall on the pixels of the image.

In a vertical layout (TextLayoutOptions.WritingMode), the outline of a glyph is fitted in its own orientation. An upright glyph keeps its axes: with TextHinting.Light, its origin is on a whole pixel down the column. A glyph on its side, such as a Latin letter of a mixed line, is fitted across the column: its baseline is on a whole pixel along the x axis of the image, and its position down the column does not change. With TextHinting.Full, each glyph starts on a whole pixel along both axes and advances by a whole number of pixels down the column: the advance of an upright glyph, which the instructions do not hint, is rounded.

HyphenCharacter

TextLayoutOptions.cs

Gets the text drawn at the end of a line that ends inside a hyphenated word, or null (the default) for the hyphen (U+2010) when the font has it and the hyphen-minus (U+002D) otherwise.

public string? HyphenCharacter { get; init; }

Property value

string?

Exceptions

ArgumentException
The value is longer than 16 characters.

Gets whether words are hyphenated at the end of a line. TextHyphenation.Manual by default.

public TextHyphenation Hyphenation { get; init; }

Property value

TextHyphenation

Gets where a justified line (TextAlignment.Justify) takes the room it is stretched by: the spaces between words (TextJustification.InterWord, the default), or also between the characters of Chinese, Japanese, Korean and Thai text, or between every two characters. It is not used with another alignment.

public TextJustification Justification { get; init; }

Property value

TextJustification

Gets how strict the line breaking rules of Chinese and Japanese text are. TextLineBreak.Normal by default.

public TextLineBreak LineBreak { get; init; }

Property value

TextLineBreak

LineBreakDictionary

TextLayoutOptions.cs

Gets the words of the languages that are written without spaces between words (Thai, Lao, Khmer, Burmese), or null (the default) for the word lists of ICU.

public LineBreakDictionary? LineBreakDictionary { get; init; }

Property value

LineBreakDictionary?

Remarks

The Unicode line breaking algorithm leaves the text of these scripts to a dictionary. By default, a line of such text can end before each of its words, as the line break iterator of ICU finds them: the words of a run of the letters of one of these scripts are those of the dictionary break engines of ICU and of its word lists (IcuDictionaryBreakEngine, in Meziantou.Framework.Unicode.Dictionaries). The other scripts that are written without spaces, such as Tai Tham, are only broken at a space, or anywhere when TextLayoutOptions.OverflowWrap allows it.

A dictionary replaces the word lists of ICU: a line can then end before each word the dictionary finds, as TextLayoutOptions.LineBreakDictionary specifies, and a dictionary without words, such as LineBreakDictionary.Parse(""), only breaks such text at a space. A dictionary can hold the words of several languages. With TextWordBreak.BreakAll or TextLineBreak.Anywhere, a line already breaks between any two letters.

LineBreakStrategy

TextLayoutOptions.cs

Gets how the places where wrapped lines end are chosen: as each line is filled (TextLineBreakStrategy.Greedy, the default), or for the whole paragraph at once (TextLineBreakStrategy.Optimal). It is not used when lines are not wrapped.

public TextLineBreakStrategy LineBreakStrategy { get; init; }

Property value

TextLineBreakStrategy

Gets the height of each line, in pixels, or null (the default) for the height the fonts of the line ask for: the largest ascent, descent and line gap of the fonts used on it.

public double? LineHeight { get; init; }

Property value

double?

Exceptions

ArgumentOutOfRangeException
The value is not a positive number up to 1048576.

Remarks

The glyphs of a line of a fixed height are centered in it: what the height adds to or takes from the height of the fonts is split above and below.

Gets the height the lines must fit, in pixels; Double.PositiveInfinity (the default) for no limit. The lines that do not fit are not part of the layout, except the first one. In a vertical layout (TextLayoutOptions.WritingMode), it is the height lines are wrapped at and aligned in, as TextLayoutOptions.MaxWidth is in a horizontal one.

public double MaxHeight { get; init; }

Property value

double

Exceptions

ArgumentOutOfRangeException
The value is negative or is not a number.

Gets the largest number of lines; Int32.MaxValue (the default) for no limit. The lines after are not part of the layout.

public int MaxLines { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not positive.

Gets the width lines are wrapped at and aligned in, in pixels; Double.PositiveInfinity (the default) for no limit: lines are then only broken at the line breaks of the text, and aligned in the width of the widest one. In a vertical layout (TextLayoutOptions.WritingMode), it is the width the lines must fit, as TextLayoutOptions.MaxHeight is in a horizontal one.

public double MaxWidth { get; init; }

Property value

double

Exceptions

ArgumentOutOfRangeException
The value is negative or is not a number.

Gets how the characters of a vertical line are set: each one as the Unicode Standard says (the default), all upright, or all on their side. It is not used in a horizontal layout.

public TextOrientation Orientation { get; init; }

Property value

TextOrientation

Remarks

With TextOrientation.Mixed, a character the standard sets upright with another glyph than in a horizontal line (a small kana, an ideographic comma) is upright, and one it sets on its side unless the font has a vertical form for it (a bracket, a long vowel mark) is upright when the font has that form, and on its side otherwise. Upright text is laid out from the top, whatever its script: among right-to-left text, it keeps the order of the text.

Gets what happens to a word that is wider than TextLayoutOptions.MaxWidth. TextOverflowWrap.Normal by default.

public TextOverflowWrap OverflowWrap { get; init; }

Property value

TextOverflowWrap

SubpixelRendering

TextLayoutOptions.cs

Gets how the glyphs are antialiased when the layout is filled at a point: with one coverage per pixel (TextSubpixelRendering.None, the default), or with one per color of the pixel, for the order of the stripes of red, green and blue of the screen the image is shown on.

public TextSubpixelRendering SubpixelRendering { get; init; }

Property value

TextSubpixelRendering

Exceptions

ArgumentOutOfRangeException
The value is not a member of TextSubpixelRendering.

Remarks

Subpixel rendering triples the horizontal resolution of the text on an LCD screen whose pixels are made of three vertical stripes, as ClearType and FreeType do: the glyphs are rasterized at three times the width of the image, the coverage of each third of a pixel is filtered with the five weights of the default LCD filter of FreeType (8, 77, 86, 77 and 8 over 256), which keeps colored fringes faint, and each color of a pixel is composited with the coverage of its stripe. The fringes show on other screens, when the image is scaled, and on screens whose stripes are in the other order: use it for images shown at their size on a known screen.

A text is drawn with subpixel rendering when it is filled at a point (DrawingCanvas.FillText), with antialiasing, with a SolidBrush (also for the styles that have their own brush) whose compositing is CompositeMode.SourceOver and blending BlendMode.Normal, outside a CompositingSpace.LinearSrgb compositing space, on an image of PixelFormat.Rgba32, PixelFormat.Bgra32, PixelFormat.Rgb24, PixelFormat.Rgba64 or PixelFormat.Rgb48, and when the text has no glyph drawn with the colors of its font, no background, no outline and no synthetic bold. Otherwise, and along a path, it is drawn with grayscale antialiasing. The transformation and the clip of the canvas apply. A pixel that is not opaque gets the mean of the three coverages: colored fringes over transparent pixels would show on any background.

Gets the distance between two tabulation stops, in spaces of the font of the tabulation. 8 by default.

public int TabSize { get; init; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not from 1 to 1024.

Gets the tabulation stops of the lines, by increasing position, or an empty list (the default) for stops every TextLayoutOptions.TabSize spaces only.

public IReadOnlyList<TextTabStop> TabStops { get; init; }

Property value

IReadOnlyList<TextTabStop>

Exceptions

ArgumentNullException
The value is null.
ArgumentException
The positions do not increase, a stop is the default value, or there are more than 256 stops.

Remarks

A tabulation goes to the first stop after the text before it on its line, and places the text after it at that stop as the stop says (TextTabAlignment): its start, its end, its middle or its decimal separator. When that text is too wide for its alignment, it starts where the tabulation is: a tabulation never moves back. After the last stop, the tabulations go to the stops every TextLayoutOptions.TabSize spaces, as without stops.

The positions are measured from where the text of the line starts, after its indent, in pixels; in a text fitted to a box (TextLayout.CreateToFit), they are scaled with the text. A line is measured with its stops when it is wrapped: an aligned text counts in the width of the line where its stop puts it.

Gets what replaces the text that does not fit the layout. TextTrimming.None by default.

public TextTrimming Trimming { get; init; }

Property value

TextTrimming

Gets where a line can be broken inside a word. TextWordBreak.Normal by default.

public TextWordBreak WordBreak { get; init; }

Property value

TextWordBreak

Gets whether a line that is wider than TextLayoutOptions.MaxWidth continues on the next line. TextWrapping.Wrap by default.

public TextWrapping Wrapping { get; init; }

Property value

TextWrapping

Gets the direction of the lines: horizontal (the default), or vertical with lines that follow each other to the left or to the right.

public TextWritingMode WritingMode { get; init; }

Property value

TextWritingMode

Remarks

In a vertical layout, what is said of the width of a line is said of its height, and the other way around: TextLayoutOptions.MaxHeight is the length lines are wrapped at and aligned in, TextLayoutOptions.MaxWidth is the room the lines must fit, TextLayoutOptions.LineHeight is the width of a line, TextLayoutOptions.Alignment places a line from its top, and TextLayoutOptions.FirstLineIndent moves the indented lines of a paragraph down. TextLayoutOptions.Orientation says which characters are upright.

A vertical line has a central baseline, in the middle of its width: upright characters are centered on it (with the vertical metrics of their font: vhea, vmtx, VORG, and the vertical forms of the vert feature), and the text that is on its side has the middle of its font on it: the middle of the ideographic em box the BASE table of the font gives for its script, or of its ascent and its descent. With TextOrientation.Sideways, the line is a horizontal line turned a quarter of a turn clockwise, and its baseline is the one of its text.

The features a style turns on for one direction apply to the other one where the font has their counterpart: kern, palt, halt, chws and hkna are applied to upright text as vkrn, vpal, vhal, vchw and vkna, and the vertical ones to the text that is on its side as the horizontal ones. The text that is on its side has the forms its font has for that (vrtr). A style that turns vrt2 on uses the rotated glyphs of the font instead: the characters the font has a rotated glyph for are set upright with that glyph, in the place of the vertical forms, and the others are turned.