Table of Contents

Class HudElementBase

Namespace
RichHudFramework.UI
Assembly
RichHudClient.dll

Abstract base for all UI elements with definite size and position. Extends HudParentBase and HudNodeBase.

public abstract class HudElementBase : HudNodeBase, IReadOnlyHudElement, IReadOnlyHudNode, IReadOnlyHudParent
Inheritance
HudElementBase
Implements
Derived
Inherited Members

Examples

The following example demonstrates how to create a custom UI element by extending this class. It implements a loading bar with an infinitely looping animation using two TexturedBox components. The background box uses masking to clip the foreground bar as it slides continuously from left to right.

public class LoadingBarExample : HudElementBase
{
    private float animStep;
    private readonly TexturedBox foreground, background;

    // Recommended constructor format
    public LoadingBarExample(HudParentBase parent = null) : base(parent)
    {
        background = new TexturedBox(this)
        {
            Color = TerminalFormatting.DarkSlateGrey, // Dark background
            DimAlignment = DimAlignments.UnpaddedSize,
            IsMasking = true // Clip contents that slide out of bounds
        };

        foreground = new TexturedBox(background)
        { 
            Color = TerminalFormatting.Mercury, // Bright foreground
            DimAlignment = DimAlignments.Height,
            ParentAlignment = ParentAlignments.InnerLeft
        };

        // Set default size and padding
        UnpaddedSize = new Vector2(200f, 30f);
        Padding = new Vector2(20f);
        animStep = 0f;
    }

    protected override void Layout()
    {
        // Update animation state
        animStep = Math.Abs(animStep + 1E-2f) % 1.3f;

        // Update position based on animation step
        foreground.Width = background.Width * 0.3f;
        foreground.Offset = new Vector2(background.Width * animStep - foreground.Width, 0f);
    }
}

Remarks

This class serves as the foundational base class for UI elements within the framework, providing essential functionality for sizing, positioning, hierarchy management, and input interaction. While lighter base classes exist in the node graph, this class represents the minimum requirement for any element that requires definite dimensions and offsets.

Parenting and Registration

Every UI element must be registered to a parent node to be updated, rendered, or receive input. Registration is normally performed automatically by the constructor, or manually via Register.

  • For an element to be rendered or process input, its hierarchy must ultimately trace back to one of the global root nodes provided by HudMain.
  • Visibility and input handling for registered nodes can be toggled dynamically using Visible and InputEnabled.

Update Cycle and Customization

This class extends HudNodeBase and HudParentBase, exposing the core update loop hooks required to create custom UI behavior imperatively:

  1. Measure: Logic for calculating element dimensions for self-resizing (occurring before the main layout pass).
  2. Layout: Logic for arranging child elements, setting finalized sizes, and updating relative positioning.
  3. Draw: Logic for rendering the element (e.g., drawing billboards or text).
  4. InputDepth and HandleInput: Logic for cursor and keyboard polling.
Note

Parent nodes can override the sizing of child nodes during layout. Custom UI elements should be designed to respect overrides where practical to ensure stable and correct positioning.

Layout and Alignment

By default, UI elements are placed relative to the center of the parent node; their Origins are centered. This differs from many UI systems that default to top-left. For UI elements attached directly to one of the root nodes, their position will be relative to the center of the screen. Positioning is set via Offset.

This class includes declarative utilities to simplify layout management without requiring manual calculations in the Layout hook:

  • ParentAlignment: Configures the anchoring of the element's Origin relative to its parent. When attached directly to Root or HighDpiRoot, this alignment is clamped to keep the element within screen bounds.

  • DimAlignment: Configures automatic size matching. Elements can be set to match their parent's width, height, or both (with or without padding).

By combining these alignment properties with container types like HudChain<TElementContainer, TElement>, complex UI layouts can be constructed without resorting to writing manual layout logic.

Input Handling

Input can be polled manually, using the HandleInput method seen above, but most standard UI elements have events for value changes, and mouse input events via IMouseInput components. BindInputElement provides events for registering custom IBind presses (created with BindManager) within the context of the UI node. This allows most common input handling to be implemented using only event-driven logic.

Constructors

HudElementBase(HudParentBase)

Initializes a new UI element attached to the given parent.

public HudElementBase(HudParentBase parent)

Parameters

parent HudParentBase

Properties

CachedSize

Last known final size, and the next size that will be used on Draw.

protected Vector2 CachedSize { get; }

Property Value

Vector2

CanIgnoreMasking

If set to true, then the element can ignore any bounding masks imposed by its parents. Supersedes selective masking flag.

public bool CanIgnoreMasking { get; set; }

Property Value

bool

DimAlignment

Determines how/if an element will copy its parent's dimensions.

public DimAlignments DimAlignment { get; set; }

Property Value

DimAlignments

Height

Height of the element. Units in pixels with HudMain.Root.

public float Height { get; set; }

Property Value

float

IsMasking

If set to true, the hud element will act as a clipping mask for child elements. False by default. Masking parent elements can still affect non-masking children.

public bool IsMasking { get; set; }

Property Value

bool

IsMousedOver

Indicates whether or not the element is capturing the cursor.

public virtual bool IsMousedOver { get; }

Property Value

bool

IsSelectivelyMasked

If set to true, the hud element will treat its parent as a clipping mask, whether it's configured as a mask or not.

public bool IsSelectivelyMasked { get; set; }

Property Value

bool

MaskingBox

Defines the clipping mask applied to the element and its children.

protected BoundingBox2? MaskingBox { get; }

Property Value

BoundingBox2?

Offset

Position of the center of the UI element relative to its origin.

public Vector2 Offset { get; set; }

Property Value

Vector2

Origin

Starting/anchoring position of the hud element. Starts in the center of the parent node by default. This behavior can be modified with ParentAlignment flags.

public Vector2 Origin { get; }

Property Value

Vector2

OriginAlignment

Origin offset used internally for parent alignment

protected Vector2 OriginAlignment { get; }

Property Value

Vector2

Padding

Border size. Included in total element size.

public Vector2 Padding { get; set; }

Property Value

Vector2

ParentAlignment

Determines the starting position/anchoring behavior of the hud element relative to its parent.

public ParentAlignments ParentAlignment { get; set; }

Property Value

ParentAlignments

Position

Current position of the center of the UI element. Origin + Offset.

public Vector2 Position { get; }

Property Value

Vector2

ShareCursor

If set to true the hud element will share the cursor with other elements.

public bool ShareCursor { get; set; }

Property Value

bool

Size

Size of the element. Units in pixels with HudMain.Root.

public Vector2 Size { get; set; }

Property Value

Vector2

UnpaddedSize

Element size without padding

public Vector2 UnpaddedSize { get; set; }

Property Value

Vector2

UseCursor

Enables or disables cursor input and capture

public bool UseCursor { get; set; }

Property Value

bool

Width

Width of the element. Units in pixels with HudMain.Root.

public float Width { get; set; }

Property Value

float
Edit this page