Table of Contents

Class RichText

Namespace
RichHudFramework.UI
Assembly
RichHudClient.dll

Reusable rich text builder designed for efficient construction and reuse of formatted text. Internally minimises StringBuilder allocations by merging consecutive text segments that share identical formatting.

public class RichText : IEnumerable<MyTuple<StringBuilder, MyTuple<byte, float, Vector2I, Color>>>, IEnumerable, IEquatable<RichText>
Inheritance
RichText
Implements

Examples

Example 1: Dynamic Text Construction

The following example shows a reused RichText buffer to construct a formatted string in a loop. This pattern is efficient for text that updates frequently (e.g., every frame in HandleInput).

private static readonly GlyphFormat headerFormat = new GlyphFormat(textSize: 1.5f, alignment: TextAlignment.Center);
private static readonly GlyphFormat footerFormat = new GlyphFormat(textSize: 0.8f, color: Color.LightGoldenrodYellow);

private readonly Label multilineLabel;
private readonly RichText buffer = new RichText();

protected override void HandleInput(Vector2 cursorPos)
{
    // Clear the buffer to reuse the internal StringBuilders
    buffer.Clear();

    for (int i = 0; i < 10; i++)
    {
        // Add text with specific styles
        buffer.Add("This is a formatted header\n", headerFormat);
        buffer.Add("This is body text that will receive defaulted formatting.\n");
        buffer.Add("This is a formatted footer\n", footerFormat);
    }

    // Reassigning the buffer updates the UI element's text board
    multilineLabel.Text = buffer;
}

Example 2: Declarative Styling

This example demonstrates how to use collection initializers to create a static, multi-styled text block. This approach is ideal for help text, tooltips, or static UI labels.

// Define reusable formats
var headerFormat = new GlyphFormat(textSize: 1.5f, alignment: TextAlignment.Center);
var subheaderFormat = new GlyphFormat(textSize: 1.1f, color: Color.LightGoldenrodYellow);
var bodyFormat = new GlyphFormat(textSize: 0.9f);

// Initialize RichText with a default body format
var text = new RichText(bodyFormat) 
{
    // 1. Add text with specific overriding formats (Header)
    { "Header for a Multi-Line Text Block\n", headerFormat },

    // 2. Add plain strings (inherits bodyFormat from constructor)
    "Multi-line body text using bodyFormat via defaultFormat.\n", 
    "Strings, StringBuilders, or other RichText objects are appended via dedicated Add() overloads.\n",

    // 3. Add a subsection header using the specific format
    { "Subsection: This is using subheaderFormat\n", subheaderFormat },

    // 4. Continue adding body text
    "Multi-line text requires the ITextBuilder or Label being written to to be in ",
    "the correct mode (Lined or Wrapped) to accept manual line breaks.\n"
};

Remarks

RichText acts as a specialized, reusable string builder designed to facilitate the efficient construction and storage of formatted text. Unlike a standard StringBuilder, this class maintains style information—such as color, font, and alignment—associated with specific text segments.

Most text-rendering UI elements within the framework expose properties of this type or provide access to an underlying ITextBuilder (see: Label.Text and Label.TextBoard). To streamline usage, string and StringBuilder instances can be implicitly converted to RichText, allowing plain text to be assigned directly to UI properties without manual conversion.

Formatting Behavior

Text added to a RichText instance without explicit formatting will inherit style instructions based on the following precedence:

  • If a defaultFormat was specified during construction, that format is applied immediately.

  • If no default was specified, the text remains unformatted until it is assigned to a UI element. Upon assignment, it adopts the default configuration of the target's ITextBuilder.

Collection Initializers

This class supports collection-initializer syntax. This allows developers to compose complex, multi-styled text blocks declaratively, mixing formatted strings, unformatted strings, and other RichText objects within a single initialization block.

Note

When retrieving a RichText property from a UI element (e.g., a Label), the accessor returns a deep copy of the content currently stored in the backing ITextBuilder. Modifying this returned instance—via methods like Add()—will not automatically update the UI element. To update the display, the modified instance must be reassigned to the property.

Constructors

RichText(RichText)

Creates a new RichText instance that is a deep copy of the given RichText.

public RichText(RichText original)

Parameters

original RichText

The rich text object to copy.

RichText(GlyphFormat?)

Initializes an empty RichText instance.

public RichText(GlyphFormat? defaultFormat = null)

Parameters

defaultFormat GlyphFormat?

Optional default formatting applied to text added without explicit formatting.

RichText(string, GlyphFormat?)

Initializes a new RichText instance containing the specified plain string.

public RichText(string text, GlyphFormat? defaultFormat = null)

Parameters

text string

Initial text content.

defaultFormat GlyphFormat?

Optional default formatting for the text.

RichText(StringBuilder, GlyphFormat?)

Initializes a new RichText instance containing the contents of the given StringBuilder.

public RichText(StringBuilder text, GlyphFormat? defaultFormat = null)

Parameters

text StringBuilder

Initial text content.

defaultFormat GlyphFormat?

Optional default formatting for the text.

Fields

defaultFormat

Default formatting applied to any added text that does not specify its own format. If null, the default format of the UI element this text is assigned to will be used as the default when it is copied.

public GlyphFormat? defaultFormat

Field Value

GlyphFormat?

Methods

Add(GlyphFormat, string)

Appends a string with explicit formatting (order reversed for convenience).

public void Add(GlyphFormat newFormat, string text)

Parameters

newFormat GlyphFormat

Formatting to apply.

text string

Text to append.

Add(GlyphFormat, StringBuilder)

Appends a copy of the given StringBuilder with explicit formatting (order reversed for convenience).

public void Add(GlyphFormat newFormat, StringBuilder text)

Parameters

newFormat GlyphFormat

Formatting to apply.

text StringBuilder

Text to append.

Add(RichText)

Appends a deep copy of another RichText object's contents to this instance. Consecutive segments with identical formatting are automatically merged into the same StringBuilder.

public void Add(RichText text)

Parameters

text RichText

The rich text to append.

Add(char, GlyphFormat?)

Appends a single character using the specified formatting. If the new formatting matches the last segment's formatting, the character is added to the existing StringBuilder.

public void Add(char ch, GlyphFormat? newFormat = null)

Parameters

ch char

Character to append.

newFormat GlyphFormat?

Formatting to apply. If null, defaultFormat is used.

Add(string, GlyphFormat?)

Appends a string using the specified formatting. If the new formatting matches the last segment's formatting, the text is merged into the existing StringBuilder.

public void Add(string text, GlyphFormat? newFormat = null)

Parameters

text string

Text to append.

newFormat GlyphFormat?

Formatting to apply. If null, defaultFormat is used.

Add(StringBuilder, GlyphFormat?)

Appends a copy of the given StringBuilder using the specified formatting. If the new formatting matches the last segment's formatting, the text is merged into the existing StringBuilder.

public void Add(StringBuilder text, GlyphFormat? newFormat = null)

Parameters

text StringBuilder

Text to append.

newFormat GlyphFormat?

Formatting to apply. If null, defaultFormat is used.

Clear()

Removes all text from this instance and returns all pooled StringBuilder objects.

public void Clear()

Equals(RichText)

Determines whether this RichText instance contains identical text and formatting to another RichText instance.

public bool Equals(RichText other)

Parameters

other RichText

The object to compare with the current object.

Returns

bool

Equals(object)

Determines whether this instance and a specified object, which must also be a RichText object, have the same value.

public override bool Equals(object obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

GetCopy()

Creates and returns a new RichText instance that is a deep copy of this object.

public RichText GetCopy()

Returns

RichText

GetEnumerator()

Returns an enumerator that iterates through the underlying rich string members.

public IEnumerator<MyTuple<StringBuilder, MyTuple<byte, float, Vector2I, Color>>> GetEnumerator()

Returns

IEnumerator<MyTuple<StringBuilder, MyTuple<byte, float, Vector2I, Color>>>

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

ToString()

Returns a concatenated, unformatted copy of the entire text content as a string.

public override string ToString()

Returns

string

TrimExcess()

Reduces memory usage by trimming excess capacity from all internal StringBuilder instances and the object pool.

public void TrimExcess()

Operators

operator +(RichText, RichText)

Appends a copy of the right RichText to the left RichText and returns the modified left instance.

public static RichText operator +(RichText left, RichText right)

Parameters

left RichText
right RichText

Returns

RichText

operator +(RichText, string)

Appends a plain string to the left RichText instance and returns the modified instance.

public static RichText operator +(RichText left, string right)

Parameters

left RichText
right string

Returns

RichText

operator +(RichText, StringBuilder)

Appends a StringBuilder to the left RichText instance and returns the modified instance.

public static RichText operator +(RichText left, StringBuilder right)

Parameters

left RichText
right StringBuilder

Returns

RichText

implicit operator RichText(string)

Implicitly converts a string to a RichText instance using the default formatting.

public static implicit operator RichText(string text)

Parameters

text string

Returns

RichText

implicit operator RichText(StringBuilder)

Implicitly converts a StringBuilder to a RichText instance using the default formatting.

public static implicit operator RichText(StringBuilder text)

Parameters

text StringBuilder

Returns

RichText

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Returns an enumerator that iterates through a collection.

IEnumerator IEnumerable.GetEnumerator()

Returns

IEnumerator

An IEnumerator object that can be used to iterate through the collection.

Edit this page