Class RatatuiTerminal

Namespace

RatatuiUnity

High-level C# API for the ratatui native library. Wraps lifecycle, layout, style, and widget commands. Must be disposed when no longer needed.

public sealed class RatatuiTerminal : IDisposable

Inheritance

object

RatatuiTerminal

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

RatatuiTerminal(int, int, float)

public RatatuiTerminal(int cols, int rows, float fontSize = 16)

Parameters

cols int

Terminal width in character columns.

rows int

Terminal height in character rows.

fontSize float

Font size in pixels.

Fields

BytesPerPixel

Bytes per pixel in the native pixel buffer (RGB24).

public const int BytesPerPixel = 3

Field Value

int

Properties

CellHeight

Height of a single character cell in pixels (PixelHeight / Rows).

public int CellHeight { get; }

Property Value

int

CellWidth

Width of a single character cell in pixels (PixelWidth / Cols).

public int CellWidth { get; }

Property Value

int

Cols

Terminal width in character columns.

public int Cols { get; }

Property Value

int

PixelHeight

Height of the rendered texture in pixels.

public int PixelHeight { get; }

Property Value

int

PixelWidth

Width of the rendered texture in pixels.

public int PixelWidth { get; }

Property Value

int

RootArea

Root area ID (always 0).

public uint RootArea { get; }

Property Value

uint

Rows

Terminal height in character rows.

public int Rows { get; }

Property Value

int

Version

Returns the native library version string.

public static string Version { get; }

Property Value

string

Methods

BarChart(uint, string, ushort, ushort)

Render a bar chart. data is a newline-separated list of "label\tvalue" pairs (e.g. "Jan\t42\nFeb\t37").

public void BarChart(uint areaId, string data, ushort barWidth = 3, ushort barGap = 1)

Parameters

areaId uint

data string

barWidth ushort

barGap ushort

BeginCanvas(uint, double, double, double, double, Marker)

Begin a canvas builder. Finalize with Render().

public CanvasBuilder BeginCanvas(uint areaId, double xMin, double xMax, double yMin, double yMax, Marker marker = Marker.Dot)

Parameters

areaId uint

xMin double

xMax double

yMin double

yMax double

marker Marker

Returns

CanvasBuilder

BeginChart(uint)

Begin a chart builder. Finalize with Render().

public ChartBuilder BeginChart(uint areaId)

Parameters

areaId uint

Returns

ChartBuilder

BeginFrame()

Start a new frame. Clears all queued widget commands. Call before adding widgets and before EndFrame().

public void BeginFrame()

BeginStyledParagraph(uint, Alignment, bool)

Begin a styled paragraph builder. Finalize with Render().

public StyledText BeginStyledParagraph(uint areaId, Alignment alignment = Alignment.Left, bool wrap = false)

Parameters

areaId uint

alignment Alignment

wrap bool

Returns

StyledText

Block(uint, string, Borders)

Render a bordered block with an optional title into areaId.

public void Block(uint areaId, string title = "", Borders borders = Borders.All)

Parameters

areaId uint

title string

borders Borders

Calendar(uint, int, int, int)

Render a monthly calendar for the given date.

public void Calendar(uint areaId, int year, int month, int day)

Parameters

areaId uint

year int

month int

day int

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

EndFrame()

Execute all queued widget commands and copy the RGB24 pixel data into a newly allocated byte[]. Prefer EndFrameRaw() to avoid a ~1-2 MB GC allocation every frame.

public byte[] EndFrame()

Returns

byte[]

EndFrameRaw()

Execute all queued widget commands and return a direct pointer to the native RGB24 pixel buffer. The pointer is valid until the next BeginFrame() call. Byte count is PixelWidth * PixelHeight * 3. Prefer this over EndFrame() to avoid a managed byte[] allocation every frame — pass the pointer directly to Texture2D.LoadRawTextureData(IntPtr, int).

public nint EndFrameRaw()

Returns

nint

EndFrameRawIfDirty()

Like EndFrameRaw(), but uses a hash-based dirty check on the cell buffer. Returns Zero when the buffer content is unchanged from the previous frame, allowing the caller to skip the GPU texture upload. The previous frame's pixel data remains valid and the texture does not need updating.

public nint EndFrameRawIfDirty()

Returns

nint

~RatatuiTerminal()

protected ~RatatuiTerminal()

Gauge(uint, float, string)

Render a progress gauge. ratio is clamped to [0, 1].

public void Gauge(uint areaId, float ratio, string label = "")

Parameters

areaId uint

ratio float

label string

HitTest(int, int)

Returns the most specific area ID at the given terminal cell coordinates. Uses the area_map from the previous frame's layout. Returns 0 (root area) if no specific widget area contains the cell.

public uint HitTest(int col, int row)

Parameters

col int

row int

Returns

uint

Inner(uint, ushort, ushort)

Returns a new area ID that represents the inside of areaId shrunk by the given margin on each side.

Typical usage: call after Block(uint, string, Borders) to get the area inside the border:

term.Block(area, "Title", Borders.All);
uint inner = term.Inner(area);          // 1 char inside borders
term.Paragraph(inner, "Hello");

Use horizontal = 2 for one extra character of text padding on left/right in addition to the border.

public uint Inner(uint areaId, ushort horizontal = 1, ushort vertical = 1)

Parameters

areaId uint

horizontal ushort

vertical ushort

Returns

uint

LineGauge(uint, float, string)

Render a horizontal line gauge. ratio is clamped to [0, 1].

public void LineGauge(uint areaId, float ratio, string label = "")

Parameters

areaId uint

ratio float

label string

List(uint, string, int)

Render a list widget. items is a newline-separated string. Pass selected = -1 for no selection.

public void List(uint areaId, string items, int selected = -1)

Parameters

areaId uint

items string

selected int

Paragraph(uint, string, Alignment, bool)

Render a paragraph of text into areaId.

public void Paragraph(uint areaId, string text, Alignment alignment = Alignment.Left, bool wrap = true)

Parameters

areaId uint

text string

alignment Alignment

wrap bool

Scrollbar(uint, long, long, long, ScrollbarOrientation)

Render a scrollbar using "scroll offset" semantics. The thumb reaches the end of the track exactly when position equals contentLength - viewportLength (i.e. the content is scrolled to its last page). When viewportLength is at least as large as contentLength, the thumb fills the entire track to indicate that everything is already visible and no scrolling is possible.

public void Scrollbar(uint areaId, long contentLength, long position, long viewportLength, ScrollbarOrientation orientation = ScrollbarOrientation.VerticalRight)

Parameters

areaId uint

Target area.

contentLength long

Total number of scrollable items / rows.

position long

Top visible item index (clamped to 0 .. contentLength - viewportLength).

viewportLength long

Number of items visible at once. Must be >= 1.

orientation ScrollbarOrientation

Scrollbar placement / direction.

Remarks

Ratatui's underlying scrollbar formula is thumb_end / track = (position + viewport) / (contentLength - 1 + viewport), which only saturates when position == contentLength - 1. That corresponds to "last item at the top of the viewport" — past the visual end of the list — so a real scroll offset (max contentLength - viewportLength) never makes the thumb reach the bottom. Substituting contentLength' = contentLength - viewportLength + 1 reduces the formula to (position + viewport) / contentLength so the thumb saturates at the actual end of the scroll range.

Parameters are declared as long so callers passing either int or uint counts compile without explicit casts.

Scrollbar(uint, long, long, long, ScrollbarOrientation, bool)

Same as Scrollbar(uint, long, long, long, ScrollbarOrientation), but skips rendering when autoHide is true and the content fits the viewport (contentLength <= viewportLength) — i.e. nothing to scroll.

public void Scrollbar(uint areaId, long contentLength, long position, long viewportLength, ScrollbarOrientation orientation, bool autoHide)

Parameters

areaId uint

contentLength long

position long

viewportLength long

orientation ScrollbarOrientation

autoHide bool

SetBackgroundColor(byte, byte, byte)

Set the terminal background color. This is the color used for cells that have no explicit background set. Must be called before BeginFrame() for the change to take effect in that frame.

public void SetBackgroundColor(byte r, byte g, byte b)

Parameters

r byte

Red component (0–255).

g byte

Green component (0–255).

b byte

Blue component (0–255).

SetBackgroundColor(Color)

Convenience overload: Set the background color using a Unity UnityEngine.Color. Alpha channel is ignored — the terminal background is always opaque.

public void SetBackgroundColor(Color color)

Parameters

color Color

SetCustomFont(byte[])

Replace the embedded JetBrains Mono font with a custom TTF font.

public bool SetCustomFont(byte[] ttfBytes)

Parameters

ttfBytes byte[]

Returns

bool

True if the font was loaded successfully.

SetStyle(Color, Color, Modifier)

Convenience overload: SetStyle with Modifier flags enum.

public void SetStyle(Color fg, Color bg, Modifier modifiers)

Parameters

fg Color

bg Color

modifiers Modifier

SetStyle(Color, Color, byte)

Set a style that will be applied to the next widget command. Use Color.clear to keep the terminal default for fg or bg.

public void SetStyle(Color fg, Color bg, byte modifiers = 0)

Parameters

fg Color

bg Color

modifiers byte

Bitmask: 0x01=Bold, 0x02=Italic, 0x04=Underlined, 0x08=Dim

Sparkline(uint, ulong[])

Render a sparkline from an array of data values.

public void Sparkline(uint areaId, ulong[] data)

Parameters

areaId uint

data ulong[]

Split(uint, Direction, params Constraint[])

Split an area into children according to the provided constraints. Returns the array of child area IDs.

public uint[] Split(uint areaId, Direction direction, params Constraint[] constraints)

Parameters

areaId uint

direction Direction

constraints Constraint[]

Returns

uint[]

Table(uint, string)

Render a table. data format: first line = tab-separated headers; subsequent lines = tab-separated row cells.

public void Table(uint areaId, string data)

Parameters

areaId uint

data string

TableEx(uint, string, Constraint[], int)

Render a table with per-column width constraints and optional row selection. Same data format as Table(uint, string); pass null columnWidths for equal-width columns.

public void TableEx(uint areaId, string data, Constraint[] columnWidths = null, int selectedRow = -1)

Parameters

areaId uint

data string

columnWidths Constraint[]

selectedRow int

Tabs(uint, string, uint)

Render a tab bar. titles is a newline-separated string.

public void Tabs(uint areaId, string titles, uint selected = 0)

Parameters

areaId uint

titles string

selected uint

TryGetAreaRect(uint, out int, out int, out int, out int)

Returns the cell-space rectangle of the given area ID. Useful for positioning tooltips, calculating scroll bounds, etc. Returns false if the area ID is not found.

public bool TryGetAreaRect(uint areaId, out int x, out int y, out int width, out int height)

Parameters

areaId uint

x int

y int

width int

height int

Returns

bool