Table of Contents

Interface ITextBoard

Namespace
RichHudFramework.UI.Rendering
Assembly
RichHudClient.dll

Represents a renderable text element that supports rich text formatting, scrolling, and advanced layout.

This interface combines text manipulation (via ITextBuilder) with rendering logic. It handles text clipping, auto-resizing, text alignment, and coordinate-based character lookups. 

public interface ITextBoard : ITextBuilder, IIndexedCollection<ILine>
Inherited Members

Examples

Example 1: Efficient Text Updates

The following example demonstrates how to rebuild text in an update loop using the ITextBuilder interface methods inherited by the board. This pattern is often cleaner than manipulating StringBuilder or RichText objects.

public class TextBuilderExample : HudElementBase
{
    private static readonly List<string> values = new List<string> { "Value 1", "Value 2", "Value 3", "Value 4" };
    private readonly Label textElement;

    // ... Initialization code ...

    protected override void HandleInput(Vector2 cursorPos)
    {
        // Access the board directly to manipulate the buffer
        ITextBuilder text = textElement.TextBoard;
        text.Clear();

        // Rebuild the list
        foreach (string val in values)
        {
            text.Append(val);
            text.Append('\n');
        }
    }
}

Example 2: Implementing a Scrollable Text Box

This example demonstrates how to wrap a TextBox and a ScrollBar inside a basic HudElementBase. It synchronizes the slider's value with the board's TextOffset.

public class ScrollingTextBox : HudElementBase
{
    private readonly TextBox text;
    private readonly ScrollBar vScroll;
    private const string LoremIpsum = "Arbitrary long text..."; 

    public ScrollingTextBox(HudParentBase parent = null) : base(parent)
    {
        text = new TextBox() 
        { 
            AutoResize = false, 
            VertCenterText = false,
            Text = LoremIpsum, 
            BuilderMode = TextBuilderModes.Wrapped
        };

        vScroll = new ScrollBar() 
        { 
            Vertical = true, 
            // Hook the slider event to update the text offset
            UpdateValueCallback = OnScrollUpdate 
        };

        // Layout: Text takes available width (1f), ScrollBar takes fixed width
        var layout = new HudChain(this)
        {
            AlignVertical = false,
            DimAlignment = DimAlignments.UnpaddedSize,
            SizingMode = HudChainSizingModes.FitMembersOffAxis,
            CollectionContainer = { { text, 1f }, vScroll }
        };

        UnpaddedSize = new Vector2(300, 200);
    }

    protected override void Layout()
    {
        // 1. Synchronize the slider if the text offset changes externally (e.g., caret movement)
        vScroll.Value = text.TextBoard.TextOffset.Y; 

        // 2. Calculate the maximum scrollable range (Total Size - Visible Size)
        float maxOffset = Math.Max(0f, text.TextBoard.TextSize.Y - text.TextBoard.Size.Y);
        vScroll.Max = maxOffset;

        // 3. Update the slider handle size to reflect the visible proportion of text
        if (text.TextBoard.TextSize.Y > 0)
            vScroll.VisiblePercent = (text.TextBoard.Size.Y / text.TextBoard.TextSize.Y);
    }

    // Apply the slider value to the text board's Y offset
    private void OnScrollUpdate(object sender, EventArgs args) =>
        text.TextBoard.TextOffset = new Vector2(0f, vScroll.Value);
}

Remarks

The ITextBoard interface provides the fundamental rendering and layout logic for UI elements that display text. It acts as a bridge between the raw string manipulation provided by ITextBuilder (which it inherits) and the visual presentation. This interface is the backing component for standard controls such as Label and TextBox.

Advanced Formatting and Layout

Unlike simple string or RichText properties, ITextBoard exposes granular control over text presentation. It manages line breaking via BuilderMode, vertical alignment via VertCenterText, and dimensions via AutoResize. When AutoResize is disabled, the board clips content that exceeds its FixedSize.

Dynamic Text Manipulation

Because it extends ITextBuilder, this interface allows for the modification of text without generating significant garbage. Developers can append, insert, or clear text segments efficiently, making it suitable for high-frequency updates (e.g., debug stats or chat logs). It also provides access to structural metadata through ILine and IRichChar.

ITextBoard supplies the utilities required for scrolling and click-based navigation:

  • Scrolling: The TextOffset property allows the visible window to be panned across the TextSize.
  • Caret Navigation: MoveToChar calculates the offset required to bring a specific character index into view.
  • Hit Testing: GetCharAtOffset translates a screen-space position into a character index, essential for mouse selection and cursor placement.
Note

While the text elements in the built-in UI library (like Label) do not include scrollbars by default, ITextBoard provides the underlying infrastructure to implement them manually. See the examples above for a standard implementation pattern.

Properties

AutoResize

If true, the text board's Size will automatically expand or contract to fit the TextSize.

bool AutoResize { get; set; }

Property Value

bool

FixedSize

The fixed dimensions of the text box used when AutoResize is false. This property is ignored if AutoResize is enabled.

Vector2 FixedSize { get; set; }

Property Value

Vector2

Scale

The base visual scale of the text board. This is applied multiplicatively after the scaling specified in GlyphFormat.

float Scale { get; set; }

Property Value

float

Size

The current boundaries of the text box as rendered. If AutoResize is true, this matches TextSize. If false, this returns FixedSize.

Vector2 Size { get; }

Property Value

Vector2

TextOffset

The render offset of the text content (scrolling/panning).

Note: AutoResize must be disabled for this to take effect.

The value is automatically clamped to ensure the text remains within visible bounds.

Vector2 TextOffset { get; set; }

Property Value

Vector2

TextSize

The total dimensions of the text content, including text currently outside the visible range. This value updates immediately upon modification.

Vector2 TextSize { get; }

Property Value

Vector2

VertCenterText

If true, the text content will be vertically aligned to the center of the text board.

bool VertCenterText { get; set; }

Property Value

bool

VisibleLineRange

Returns the index range of the lines currently visible within the text board's bounds. X = Start Line Index, Y = End Line Index.

Vector2I VisibleLineRange { get; }

Property Value

Vector2I

Methods

GetCharAtOffset(Vector2)

Retrieves the index of the character located at the specified local offset.

Vector2I GetCharAtOffset(Vector2 localPos)

Parameters

localPos Vector2

Position relative to the center of the TextBoard.

Returns

Vector2I

The index of the character (X: Line/Char, Y: Column).

MoveToChar(Vector2I)

Calculates and applies the minimum scroll offset required to bring the character at the specified index into view.

void MoveToChar(Vector2I index)

Parameters

index Vector2I

The index of the character (X: Line/Char, Y: Column).

Events

TextChanged

Invoked whenever a change is made to the text. This event is rate-limited and invokes once every 500ms at most.

event Action TextChanged

Event Type

Action
Edit this page