SurfaceCell

Namespace: Hex1b.Surfaces

Assembly: Hex1b.dll

Represents a single cell in a surface - the atomic unit of terminal rendering.

public readonly record struct SurfaceCell : IEquatable<SurfaceCell>

Implements

• IEquatable<SurfaceCell>

Constructors

SurfaceCell(string, Hex1bColor?, Hex1bColor?, CellAttributes, int, TrackedObject<SixelData>?, TrackedObject<KgpCellData>?, TrackedObject<HyperlinkData>?, UnderlineStyle, Hex1bColor?)

Represents a single cell in a surface - the atomic unit of terminal rendering.

Parameters:

• Character (String): The grapheme cluster (user-perceived character) to display. May be multiple code points for emoji, combining characters, etc.
• Foreground (Nullable<Hex1bColor>): The foreground color, or null for transparent (shows through from layer below).
• Background (Nullable<Hex1bColor>): The background color, or null for transparent (shows through from layer below).
• Attributes (CellAttributes): Text styling attributes (bold, italic, underline, etc.).
• DisplayWidth (Int32): The number of terminal columns this cell occupies. 1 for normal, 2 for wide, 0 for continuation.
• Sixel (TrackedObject<SixelData>): Optional tracked reference to Sixel graphics data.
• Kgp (TrackedObject<KgpCellData>): Optional tracked reference to KGP (Kitty Graphics Protocol) image data.
• Hyperlink (TrackedObject<HyperlinkData>): Optional tracked reference to hyperlink data.
• UnderlineStyle (UnderlineStyle): The underline style (single, double, curly, dotted, dashed). Only meaningful when Attributes has Underline flag.
• UnderlineColor (Nullable<Hex1bColor>): The underline color (independent of foreground), or null for default (foreground color).

public SurfaceCell(string Character, Hex1bColor? Foreground, Hex1bColor? Background, CellAttributes Attributes = CellAttributes.None, int DisplayWidth = 1, TrackedObject<SixelData>? Sixel = null, TrackedObject<KgpCellData>? Kgp = null, TrackedObject<HyperlinkData>? Hyperlink = null, UnderlineStyle UnderlineStyle = UnderlineStyle.None, Hex1bColor? UnderlineColor = null)

Properties

Attributes

Text styling attributes (bold, italic, underline, etc.).

Returns: CellAttributes

public CellAttributes Attributes { get; init; }

Background

The background color, or null for transparent (shows through from layer below).

Returns: Nullable<Hex1bColor>

public Hex1bColor? Background { get; init; }

Character

The grapheme cluster (user-perceived character) to display. May be multiple code points for emoji, combining characters, etc.

Returns: String

public string Character { get; init; }

DisplayWidth

The number of terminal columns this cell occupies. 1 for normal, 2 for wide, 0 for continuation.

Returns: Int32

public int DisplayWidth { get; init; }

Foreground

The foreground color, or null for transparent (shows through from layer below).

Returns: Nullable<Hex1bColor>

public Hex1bColor? Foreground { get; init; }

HasHyperlink

Gets whether this cell contains hyperlink data.

Returns: Boolean

public bool HasHyperlink { get; }

HasKgp

Gets whether this cell contains KGP (Kitty Graphics Protocol) image data.

Returns: Boolean

public bool HasKgp { get; }

HasSixel

Gets whether this cell contains Sixel graphics data.

Returns: Boolean

public bool HasSixel { get; }

HasTransparentBackground

Gets whether this cell has a transparent background. When compositing, the background from the layer below will show through.

Returns: Boolean

public bool HasTransparentBackground { get; }

HasTransparentForeground

Gets whether this cell has a transparent foreground. When compositing, the foreground from the layer below will show through.

Returns: Boolean

public bool HasTransparentForeground { get; }

Hyperlink

Optional tracked reference to hyperlink data.

Returns: TrackedObject<HyperlinkData>

public TrackedObject<HyperlinkData>? Hyperlink { get; init; }

IsContinuation

Gets whether this cell is a continuation of a previous wide character. Continuation cells should not be rendered directly - the wide character in the previous cell covers this position.

Returns: Boolean

public bool IsContinuation { get; }

IsTransparent

Gets whether this cell is fully transparent (both foreground and background are null).

Returns: Boolean

public bool IsTransparent { get; }

IsWide

Gets whether this cell contains a wide character (occupies 2+ columns).

Returns: Boolean

public bool IsWide { get; }

Kgp

Optional tracked reference to KGP (Kitty Graphics Protocol) image data.

Returns: TrackedObject<KgpCellData>

public TrackedObject<KgpCellData>? Kgp { get; init; }

Sixel

Optional tracked reference to Sixel graphics data.

Returns: TrackedObject<SixelData>

public TrackedObject<SixelData>? Sixel { get; init; }

UnderlineColor

The underline color (independent of foreground), or null for default (foreground color).

Returns: Nullable<Hex1bColor>

public Hex1bColor? UnderlineColor { get; init; }

UnderlineStyle

The underline style (single, double, curly, dotted, dashed). Only meaningful when Attributes has Underline flag.

Returns: UnderlineStyle

public UnderlineStyle UnderlineStyle { get; init; }

Methods

WithAddedAttributes(CellAttributes)

Creates a new cell with additional attributes added.

Parameters:

• attributes (CellAttributes):

Returns: SurfaceCell

public SurfaceCell WithAddedAttributes(CellAttributes attributes)

WithAttributes(CellAttributes)

Creates a new cell with the specified attributes.

Parameters:

• attributes (CellAttributes):

Returns: SurfaceCell

public SurfaceCell WithAttributes(CellAttributes attributes)

WithBackground(Hex1bColor?)

Creates a new cell with the specified background color.

Parameters:

• background (Nullable<Hex1bColor>):

Returns: SurfaceCell

public SurfaceCell WithBackground(Hex1bColor? background)

WithForeground(Hex1bColor?)

Creates a new cell with the specified foreground color.

Parameters:

• foreground (Nullable<Hex1bColor>):

Returns: SurfaceCell

public SurfaceCell WithForeground(Hex1bColor? foreground)

Remarks

A represents a single character position in a terminal surface, including the character to display, its colors, styling attributes, and optional extensions like hyperlinks and sixel graphics.

For wide characters (CJK, emoji, etc.) that occupy multiple terminal columns, the primary cell contains the character with set to 2 (or more), and subsequent cells are continuation cells with set to 0.