TextLayoutOptions Class
How a text is laid out: the box it must fit, how its lines are broken and aligned.
public sealed class TextLayoutOptionsRemarks
The options are immutable; TextLayoutOptions.Default lays out a text of any width on one line per paragraph.
Constructors
| Name | Description |
|---|---|
| TextLayoutOptions() |
TextLayoutOptions()
TextLayoutOptions.cspublic TextLayoutOptions()No documentation is available.
Properties
| Name | Description |
|---|---|
| Alignment | Gets how the lines are placed in the width of the layout. TextAlignment.Start by default. |
| CombineUprightDigits | 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. |
| Default | Gets the default options: no maximum size, lines aligned at their start. |
| Direction | Gets the base direction of the paragraphs. TextDirection.Auto by default. |
| Ellipsis | 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. |
| FirstLineIndent | Gets the space before the first line of each paragraph, in pixels; negative for a hanging indent. 0 by default. |
| Hinting | 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. |
| HyphenCharacter | 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. |
| Hyphenation | Gets whether words are hyphenated at the end of a line. TextHyphenation.Manual by default. |
| Justification | 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. |
| LineBreak | Gets how strict the line breaking rules of Chinese and Japanese text are. TextLineBreak.Normal by default. |
| LineBreakDictionary | 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. |
| LineBreakStrategy | 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. |
| LineHeight | 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. |
| MaxHeight | 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. |
| MaxLines | Gets the largest number of lines; Int32.MaxValue (the default) for no limit. The lines after are not part of the layout. |
| MaxWidth | 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. |
| Orientation | 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. |
| OverflowWrap | Gets what happens to a word that is wider than TextLayoutOptions.MaxWidth. TextOverflowWrap.Normal by default. |
| SubpixelRendering | 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. |
| TabSize | Gets the distance between two tabulation stops, in spaces of the font of the tabulation. 8 by default. |
| TabStops | Gets the tabulation stops of the lines, by increasing position, or an empty list (the default) for stops every TextLayoutOptions.TabSize spaces only. |
| Trimming | Gets what replaces the text that does not fit the layout. TextTrimming.None by default. |
| WordBreak | Gets where a line can be broken inside a word. TextWordBreak.Normal by default. |
| Wrapping | Gets whether a line that is wider than TextLayoutOptions.MaxWidth continues on the next line. TextWrapping.Wrap by default. |
| WritingMode | Gets the direction of the lines: horizontal (the default), or vertical with lines that follow each other to the left or to the right. |
Alignment
TextLayoutOptions.csGets how the lines are placed in the width of the layout. TextAlignment.Start by default.
public TextAlignment Alignment { get; init; }Property value
CombineUprightDigits
TextLayoutOptions.csGets 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
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.
Default
TextLayoutOptions.csGets the default options: no maximum size, lines aligned at their start.
public static TextLayoutOptions Default { get; }Property value
Direction
TextLayoutOptions.csGets the base direction of the paragraphs. TextDirection.Auto by default.
public TextDirection Direction { get; init; }Property value
Ellipsis
TextLayoutOptions.csGets 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; }FirstLineIndent
TextLayoutOptions.csGets 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
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.
Hinting
TextLayoutOptions.csGets 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
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.csGets 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; }Hyphenation
TextLayoutOptions.csGets whether words are hyphenated at the end of a line. TextHyphenation.Manual by default.
public TextHyphenation Hyphenation { get; init; }Property value
Justification
TextLayoutOptions.csGets 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
LineBreak
TextLayoutOptions.csGets how strict the line breaking rules of Chinese and Japanese text are. TextLineBreak.Normal by default.
public TextLineBreak LineBreak { get; init; }Property value
LineBreakDictionary
TextLayoutOptions.csGets 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
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.csGets 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
LineHeight
TextLayoutOptions.csGets 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
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.
MaxHeight
TextLayoutOptions.csGets 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; }MaxLines
TextLayoutOptions.csGets 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; }MaxWidth
TextLayoutOptions.csGets 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; }Orientation
TextLayoutOptions.csGets 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
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.
OverflowWrap
TextLayoutOptions.csGets what happens to a word that is wider than TextLayoutOptions.MaxWidth. TextOverflowWrap.Normal by default.
public TextOverflowWrap OverflowWrap { get; init; }Property value
SubpixelRendering
TextLayoutOptions.csGets 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
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.
TabSize
TextLayoutOptions.csGets the distance between two tabulation stops, in spaces of the font of the tabulation. 8 by default.
public int TabSize { get; init; }TabStops
TextLayoutOptions.csGets 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
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.
Trimming
TextLayoutOptions.csGets what replaces the text that does not fit the layout. TextTrimming.None by default.
public TextTrimming Trimming { get; init; }Property value
WordBreak
TextLayoutOptions.csGets where a line can be broken inside a word. TextWordBreak.Normal by default.
public TextWordBreak WordBreak { get; init; }Property value
Wrapping
TextLayoutOptions.csGets 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
WritingMode
TextLayoutOptions.csGets 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
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.