RichTextBuilder Class

Builds a RichText, one span after the other.

public sealed class RichTextBuilder

Remarks

A builder is not thread-safe. It can be reused after RichTextBuilder.Build, and emptied with RichTextBuilder.Clear.

Constructors

NameDescription
RichTextBuilder()

RichTextBuilder()

RichTextBuilder.cs
public RichTextBuilder()

No documentation is available.

Methods

NameDescription
Append(string, TextStyle)Adds a text with a style.
AppendPlaceholder(double, double, double, TextStyle)Adds a placeholder: room in the line for something the text does not draw, such as an icon or a badge, which moves with the text around it when lines are wrapped and aligned.
AppendRuby(string, TextStyle, string, TextStyle)Adds a ruby: a text, the base, with an annotation set beside it, such as the reading of Japanese kanji in kana (furigana), or a pronunciation.
Build()Creates the text with the spans added so far.
Clear()Removes every span.

Append(string, TextStyle)

RichTextBuilder.cs

Adds a text with a style.

public RichTextBuilder Append(string text, TextStyle style)

Parameters

text string
The text; an empty text adds nothing.
style TextStyle
The style of the text.

Returns

RichTextBuilder This builder.

Exceptions

ArgumentNullException
text or style is null.

AppendPlaceholder(double, double, double, TextStyle)

RichTextBuilder.cs

Adds a placeholder: room in the line for something the text does not draw, such as an icon or a badge, which moves with the text around it when lines are wrapped and aligned.

public RichTextBuilder AppendPlaceholder(double width, double height, double baseline, TextStyle style)

Parameters

width double
The width of the placeholder, in pixels: zero or positive, up to 65536.
height double
The height of the placeholder, in pixels: zero or positive, up to 65536.
baseline double
The distance from the top of the placeholder down to the baseline of its line, in pixels: height to stand on the baseline. Its magnitude must not exceed 65536.
style TextStyle
The style of the placeholder: the one of the text around it, as a rule.

Returns

RichTextBuilder This builder.

Exceptions

ArgumentNullException
style is null.
ArgumentOutOfRangeException
width or height is not between 0 and 65536, or baseline is not between -65536 and 65536.

Remarks

The placeholder is one character of the text (U+FFFC, the object replacement character): it has an index, a caret can be before or after it, and a line can end before or after it. It takes width on its line, and its line is at least as tall as it needs: the placeholder rises baseline above the baseline of the line, and goes height less baseline below it. A placeholder as tall as its baseline stands on the baseline, as a capital letter does.

Nothing is drawn there: TextLayout.Placeholders gives the rectangle of each placeholder of a layout, for the caller to draw in after the text. The style gives the direction and the decorations the placeholder has among its neighbors, and its line the height of its fonts.

In a vertical layout (TextLayoutOptions.WritingMode), the placeholder takes height down its line and is centered on the line, which is at least as wide as width: baseline is not used. With TextOrientation.Sideways, the placeholder is turned with its line as the text is: its rectangle is height wide and width tall.

AppendRuby(string, TextStyle, string, TextStyle)

RichTextBuilder.cs

Adds a ruby: a text, the base, with an annotation set beside it, such as the reading of Japanese kanji in kana (furigana), or a pronunciation.

public RichTextBuilder AppendRuby(string text, TextStyle style, string annotation, TextStyle annotationStyle)

Parameters

text string
The base: a text that is not empty.
style TextStyle
The style of the base.
annotation string
The annotation; an empty one adds a base that a line never ends inside, with nothing beside it.
annotationStyle TextStyle
The style of the annotation.

Returns

RichTextBuilder This builder.

Exceptions

ArgumentNullException
text, style, annotation or annotationStyle is null.
ArgumentException
text is empty.

Remarks

The base is part of the text, with its style: it is shaped, measured and hit like the rest of the text, but a line never ends inside it. The annotation is not part of the text: it is laid out on its own, with annotationStyle (usually half the size of the base), and drawn with the glyphs of the layout, centered on the base. A base shorter than its annotation gets the difference as room, half before it and half after it, so that the annotation does not run over the text around it. The line is as tall as it needs for the annotation to stand on the ascent of the font of the base.

In a horizontal layout, the annotation is above the base. In a vertical layout (TextLayoutOptions.WritingMode), it is set in the same writing mode and orientation as the text, in a column on the right of the base, centered along it: the side of Japanese and Chinese vertical text. The annotation is not part of the positions of the text (TextLayout.HitTest, the carets and the selections), and is not hyphenated, wrapped or justified.

Example

public static void DrawRuby(string fontPath, string outputPath)
{
    var font = Font.Load(fontPath);
    var text = new TextStyle(font, size: 28);
    var reading = new TextStyle(font, size: 14);

    // The base is part of the text; the annotation is set beside it, at half the size, and a line never ends inside the base
    var rubyText = new RichTextBuilder()
        .AppendRuby("東京", text, "とうきょう", reading)
        .Append("の", text)
        .AppendRuby("日本語", text, "にほんご", reading)
        .Build();

    // Above the base in a horizontal layout, on its right in a vertical one
    var horizontal = TextLayout.Create(rubyText);
    var vertical = TextLayout.Create(rubyText, new TextLayoutOptions { WritingMode = TextWritingMode.VerticalRightToLeft });

    var width = (int)Math.Ceiling(horizontal.Width + vertical.Width) + 40;
    var height = (int)Math.Ceiling(Math.Max(horizontal.Height, vertical.Height)) + 20;
    using var image = new Image<Rgba32>(width, height, new Rgba32(255, 255, 255));
    image.Draw(canvas =>
    {
        canvas.FillText(new Rgba32(0, 0, 0), horizontal, new PointD(10, 10));
        canvas.FillText(new Rgba32(0, 0, 0), vertical, new PointD(horizontal.Width + 30, 10));
    });
    image.Save(outputPath);
}

Creates the text with the spans added so far.

public RichText Build()

Returns

RichText The text; it does not change when the builder does.

Removes every span.

public void Clear()