TextLayoutOptions Class

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.

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 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. Hinting applies to horizontal text; a vertical layout (TextLayoutOptions.WritingMode) is not hinted.

The Unicode line breaking algorithm leaves the text of these scripts to a dictionary: without one, a line of such text is only broken at a space, or anywhere when TextLayoutOptions.OverflowWrap allows it. With one, a line can also end before each word the dictionary finds, as TextLayoutOptions.LineBreakDictionary specifies. A dictionary can hold the words of several languages. No word list is provided with the library.

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.

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.

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.

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.