ConsoleForge.Widgets Namespace Reference

Classes
class	ImageWidget
	Renders an image inside its allocated terminal region. More...
struct	RgbaImageData
	Pre-decoded RGBA image data for use with ImageWidget's half-block Unicode fallback renderer. More...

Enumerations
enum	ImageRenderMode { Auto , Kitty , HalfBlock , None }
	Rendering strategy for ImageWidget. More...

Functions
	Checkbox (string label="", bool isChecked=false, char checkedChar='✓', char uncheckedChar=' ', Style? style=null)
	Positional constructor for inline usage.
static int	ComputeScrollOffset (int selectedIndex, int viewportHeight, int currentScrollOffset)
	Computes a new ScrollOffset that keeps selectedIndex within the visible viewport.
static int	ComputeScrollOffset (int selectedIndex, int viewportHeight, int currentScrollOffset)
	Computes a new ScrollOffset that keeps selectedIndex within the visible data-row viewport.
static int	ComputeScrollRow (int cursorRow, int viewportHeight, int currentScrollRow)
	Compute a new ScrollRow that keeps cursorRow within the visible viewport.
	List (IReadOnlyList< string > items, int selectedIndex=0, Style? style=null, Style? selectedItemStyle=null, int paddingLeft=1, int paddingRight=0, int scrollOffset=0)
	Positional constructor for inline usage.
	ProgressBar (double value, double maximum=100, bool showPercent=true, char fillChar='█', char emptyChar='░', Style? style=null)
	Positional constructor for inline usage.
void	Render (IRenderContext ctx)
	Renders the checkbox as [✓] Label or [ ] Label.
record	ShelfItem (string Title, byte[]? Poster=null, ConsoleForge.Terminal.TerminalCapabilities? Capabilities=null, string? Key=null)
	One card in a HorizontalShelf.
	Table (IReadOnlyList< TableColumn > columns, IReadOnlyList< IReadOnlyList< string > > rows, int selectedIndex=-1, Style? headerStyle=null, Style? rowStyle=null, int paddingLeft=1, int paddingRight=1, int scrollOffset=0)
	Positional constructor for inline usage.
record	TableColumn (string Header, int Width=0, Style? Style=null)
	Defines a single column in a Table widget.
	Tabs (IReadOnlyList< string > labels, int activeIndex=0, IWidget? body=null, Style? style=null, Style? activeTabStyle=null, Style? inactiveTabStyle=null)
	Positional constructor for inline usage.
	TextArea (IReadOnlyList< string >? lines=null, int cursorRow=0, int cursorCol=0, int scrollRow=0, int maxLines=0, Style? style=null)
	Positional constructor for inline usage.
	TextInput (string value="", string placeholder="", int cursorPosition=0, Style? style=null)
	Positional constructor for inline usage.

Variables
record	BorderBox
	A widget that renders a bordered box with an optional title and a body child widget.
record	Checkbox
	A single toggleable checkbox widget.
record	Container
	A layout container that arranges child widgets along a given axis.
record	HorizontalShelf
	A horizontally scrolling strip of cards — cover art with a caption — of the kind a media library uses for "Continue Watching" or "Recently Added".
record	List
	A scrollable list widget that displays items and highlights the selected one.
record	Modal
	A centered dialog overlay widget.
record	ModalDismissedMsg
	Dispatched by convention when the user dismisses a modal (e.g.
IFocusable	Next
record	ProgressBar
	A horizontal progress bar widget.
record	Spinner
	An animated spinner widget.
record	Table
	A tabular data widget.
record	Tabs
	A tabbed navigation widget.
record	TextArea
	A multi-line text input widget.
record	TextBlock
	A widget that renders a single string, wrapping at region width.
record	TextInput
	A single-line text input widget that accepts keyboard input when focused.
record	ZStack
	A layered widget that renders its children back-to-front over the same region.

Enumeration Type Documentation

ImageRenderMode

enum ConsoleForge.Widgets.ImageRenderMode

Rendering strategy for ImageWidget.

Enumerator
Auto	Automatically select the best available mode: Kitty when TerminalCapabilities.SupportsKittyGraphics is true and ImageWidget.PngData is present; otherwise HalfBlock when ImageWidget.RgbaData is present; otherwise no-op.
Kitty	Use the Kitty terminal graphics protocol. Requires ImageWidget.PngData and a capable terminal. Falls back to no-op if PNG data is absent.
HalfBlock	Use Unicode half-block characters with 24-bit colour. Requires ImageWidget.RgbaData. Falls back to no-op if absent.
None	Render nothing. Reserves layout space without drawing pixels.

Function Documentation

Checkbox()

ConsoleForge.Widgets.Checkbox	(	string	label = "",
		bool	isChecked = false,
		char	checkedChar = '✓',
		char	uncheckedChar = ' ',
		Style?	style = null )

Positional constructor for inline usage.

Parameters

label	Text displayed next to the checkbox.
isChecked	Initial checked state.
checkedChar	Indicator character when checked.
uncheckedChar	Indicator character when unchecked.
style	Optional visual style override.

ComputeScrollOffset() [1/2]

int ConsoleForge.Widgets.ComputeScrollOffset ( int selectedIndex, int viewportHeight, int currentScrollOffset )

static

Computes a new ScrollOffset that keeps selectedIndex within the visible viewport.

Call this from your model's Update handler after storing the widget Update returned.

Parameters

selectedIndex	The newly selected item index.
viewportHeight	Number of visible rows in the List's region.
currentScrollOffset	Current ScrollOffset.

Kept for a model that stores the widget rather than a ListState. It has no item count to clamp against, so it only slides the offset far enough to show the selection — ListState does that and bounds the offset too.

ComputeScrollOffset() [2/2]

int ConsoleForge.Widgets.ComputeScrollOffset ( int selectedIndex, int viewportHeight, int currentScrollOffset )

static

Computes a new ScrollOffset that keeps selectedIndex within the visible data-row viewport.

Call this from your model's Update handler when processing TableSelectionChangedMsg.

Parameters

selectedIndex	The newly selected row index.
viewportHeight	Number of rows in the Table's region minus 1 for the header row.
currentScrollOffset	Current ScrollOffset.

ComputeScrollRow()

int ConsoleForge.Widgets.ComputeScrollRow ( int cursorRow, int viewportHeight, int currentScrollRow )

static

Compute a new ScrollRow that keeps cursorRow within the visible viewport.

Call this from your model's Update handler after storing the widget Update returned, and on WindowResizeMsg.

Parameters

cursorRow	The cursor row after the edit.
viewportHeight	Number of visible rows in the TextArea's region.
currentScrollRow	Current scroll offset.

Returns

Adjusted scroll row ensuring cursor is visible.

Shares its arithmetic with ListState, which keeps a viewport of its own and so can hold the offset consistent rather than recomputing it on demand.

List()

ConsoleForge.Widgets.List	(	IReadOnlyList< string >	items,
		int	selectedIndex = 0,
		Style?	style = null,
		Style?	selectedItemStyle = null,
		int	paddingLeft = 1,
		int	paddingRight = 0,
		int	scrollOffset = 0 )

Positional constructor for inline usage.

Parameters

items	Display strings to show.
selectedIndex	Initially highlighted row index (clamped).
style	Optional style for unselected rows.
selectedItemStyle	Optional style for the highlighted row.
paddingLeft	Blank columns inserted to the left of each item's text. Provides breathing room when the list is placed inside a BorderBox. Defaults to 1.
paddingRight	Blank columns reserved to the right of each item's text. Defaults to 0.
scrollOffset	First visible item index. Defaults to 0.

Render()

void ConsoleForge.Widgets.Render

(

IRenderContext

ctx

)

Renders the checkbox as [✓] Label or [ ] Label.

Renders visible lines into the allocated region.

Renders the tab bar on row 0 of the allocated region, then delegates Body into the remaining rows.

Renders the header row, separator line, and data rows into ctx 's allocated region.

Renders the progress bar into ctx 's allocated region.

The indicator brackets and label are styled together. When focused, the active theme's Theme.FocusedStyle is blended in.

Draws a filled portion followed by an empty portion, then an optional percentage label at the right edge.

Parameters

ctx	The render context providing the target region, theme, and write methods.

Rows that exceed the available height are clipped. Column widths are resolved on each render; flex columns share remaining space equally.

Parameters

ctx	The render context providing the target region, theme, and write methods.

Lines outside [ScrollRow, ScrollRow + height) are not drawn. When focused, the cursor position is highlighted with reverse-video.

ShelfItem()

record ConsoleForge.Widgets.ShelfItem ( string Title, byte?[] Poster = null, ConsoleForge.Terminal.TerminalCapabilities? Capabilities = null, string? Key = null )

sealed

One card in a HorizontalShelf.

Parameters

Title	Caption below the artwork. Truncated to the card width.
Poster	PNG artwork, or null while it is still loading — the card draws a placeholder until the bytes arrive, so a shelf can render before its images do.
Capabilities	Terminal capabilities, forwarded to ImageWidget so it can pick the Kitty path where available and half-blocks otherwise.
Key	Caller's identifier for the item this card came from — a rating key, an id. The shelf does not read it; it is here so an Update handling a selection knows what was selected without indexing back into a list that may have been replaced.

TableColumn()

record ConsoleForge.Widgets.TableColumn ( string Header, int Width = 0, Style? Style = null )

sealed

Defines a single column in a Table widget.

Parameters

Header	Column header text.
Width	Column width in characters. Use 0 to distribute remaining space equally among all zero-width columns.
Style	Optional per-column style for the data cells.

Tabs()

ConsoleForge.Widgets.Tabs	(	IReadOnlyList< string >	labels,
		int	activeIndex = 0,
		IWidget?	body = null,
		Style?	style = null,
		Style?	activeTabStyle = null,
		Style?	inactiveTabStyle = null )

Positional constructor for inline usage.

Parameters

labels	Tab label strings.
activeIndex	Initially active tab (clamped to valid range).
body	Content widget for the active tab.
style	Optional tab bar style override.
activeTabStyle	Optional style for the active tab label.
inactiveTabStyle	Optional style for inactive tab labels.

TextArea()

ConsoleForge.Widgets.TextArea	(	IReadOnlyList< string >?	lines = null,
		int	cursorRow = 0,
		int	cursorCol = 0,
		int	scrollRow = 0,
		int	maxLines = 0,
		Style?	style = null )

Positional constructor for inline usage.

Parameters

lines	Initial line content. Null or empty → single empty line.
cursorRow	Initial cursor row (clamped).
cursorCol	Initial cursor column (clamped).
scrollRow	Initial vertical scroll offset.
maxLines	Max line count (0 = unlimited).
style	Optional visual style override.

TextInput()

ConsoleForge.Widgets.TextInput	(	string	value = "",
		string	placeholder = "",
		int	cursorPosition = 0,
		Style?	style = null )

Positional constructor for inline usage.

Parameters

value	Initial text value.
placeholder	Placeholder shown when value is empty.
cursorPosition	Initial cursor position (clamped to value length).
style	Optional visual style override.

Variable Documentation

BorderBox

record ConsoleForge.Widgets.BorderBox

sealed

A widget that renders a bordered box with an optional title and a body child widget.

Default border style is Borders.Normal unless overridden by the widget style or theme.

Checkbox

ConsoleForge.Widgets.Checkbox

sealed

A single toggleable checkbox widget.

Object-initializer constructor; all properties default.

Renders as [✓] Label or [ ] Label. Space or Enter toggles the value; Update returns the toggled checkbox for the model to store.

Container

record ConsoleForge.Widgets.Container

sealed

A layout container that arranges child widgets along a given axis.

Participates in two-pass layout via IContainer. Supports optional scrolling along the main axis.

HorizontalShelf

record ConsoleForge.Widgets.HorizontalShelf

sealed

A horizontally scrolling strip of cards — cover art with a caption — of the kind a media library uses for "Continue Watching" or "Recently Added".

The shelf renders a window onto Items at ScrollOffset columns and draws only the cards that fall inside it, so a shelf of a thousand items costs the same as one of ten.

It knows nothing about pages. ScrollOffset is a column position, and what moves it is the model's business: jump it to a PageOffset for paging, ease it between two of them over several frames for an animated slide, or step it by Stride for a continuous scroll. Cards that straddle an edge are clipped, which is what makes the intermediate frames of a slide look right.

Selection and scroll live in your model. The shelf is not focusable and never changes them; give it the values to draw and fold key handling into your own Update, where a two-dimensional layout of several shelves needs it anyway.

// paging: the model owns the page number and asks the shelf where that lands
var shelf = new HorizontalShelf(items, cardWidth: 18, cardGap: 2);
shelf = shelf with { ScrollOffset = shelf.PageOffset(Page, shelfWidth) };
 
// later, an animated slide is the same call with an eased offset in between
shelf = shelf with { ScrollOffset = Anim?.CurrentOffset ?? shelf.PageOffset(Page, shelfWidth) };

List

ConsoleForge.Widgets.List

sealed

A scrollable list widget that displays items and highlights the selected one.

Object-initializer constructor; all properties default.

Dispatches ListItemSelectedMsg when the user presses Enter.

Modal

record ConsoleForge.Widgets.Modal

sealed

A centered dialog overlay widget.

Renders a bordered box on top of whatever is already in the cell buffer (paint-over, no viewport capture).

Compose with ZStack to show a modal on top of existing content:

new ZStack([
    mainLayout,
    isOpen ? new Modal("Confirm", body: confirmBody) : new TextBlock(""),
])

Focus — FocusManager traverses into Body automatically (Modal implements ISingleBodyWidget). The model is responsible for routing keyboard input to the modal when it is open.

Backdrop — off by default, and the modal then draws only its dialog box. Cells outside the box are left untouched, so lower ZStack layers show through exactly as they were. Nothing dims them: there is no middle setting.

ShowBackdrop fills the modal's entire region with spaces in BackdropStyle before the dialog is drawn, which erases what is underneath rather than tinting it — a paint-over, not a translucent overlay. Since Width and Height default to flex and ZStack hands every layer the full region, that region is normally the whole terminal, so a backdrop over a ZStack blanks the application behind the dialog. That is the intended behaviour of the flag, not a bug; leave it off to keep context visible.

ModalDismissedMsg

record ConsoleForge.Widgets.ModalDismissedMsg

sealed

Dispatched by convention when the user dismisses a modal (e.g.

presses Escape). The model should set its open-flag to false and remove the modal from the view tree.

Next

IFocusable ConsoleForge.Widgets.Next

Apply one key press to Value and CursorPosition and return the edited widget — this instance is never mutated, so the model must store what comes back.

Process a key event and return the edited widget.

Left/Right arrows cycle tabs.

Navigation lives in ListState; this only carries it across, so a model that keeps its own ListState and one that stores the widget behave identically.

The widget has no viewport to hand over — it learns its region only at render time — so ScrollOffset is left to the model via ComputeScrollOffset, and PageUp/PageDown do nothing here. A model holding a ListState with WithViewport gets both.

Number keys 1–9 jump to a specific tab.

The model stores what this returns; nothing is dispatched.

The editing rules live in TextAreaState, which in turn defers single-line editing to TextInputState. A model that keeps its own TextAreaState and one that stores the widget behave identically.

ScrollRow is untouched here: the widget has no viewport until render time, so a model updates it with ComputeScrollRow after storing the result.

The editing rules live in TextInputState; this only carries them across, so a model that keeps its own TextInputState and one that stores the widget behave identically.

ProgressBar

ConsoleForge.Widgets.ProgressBar

sealed

A horizontal progress bar widget.

Object-initializer constructor.

Fills a region proportionally based on Value relative to Maximum.

Spinner

record ConsoleForge.Widgets.Spinner

sealed

An animated spinner widget.

Cycles through a sequence of frames on each render. Models should advance Frame via a Cmd.Tick or Sub.Interval.

The spinner does not self-animate — it renders the frame at index Frame % Frames.Length. Advance Frame in your model's Update handler to produce motion.

Table

ConsoleForge.Widgets.Table

sealed

A tabular data widget.

Object-initializer constructor.

Renders a header row followed by data rows. Columns are defined by Columns; each row is a string array whose elements correspond to each column in order.

Columns with Width == 0 share the remaining horizontal space equally. Content that exceeds a column's width is truncated. No scrolling — clip to the available height. For scrolling, wrap in a scrollable Container.

Tabs

ConsoleForge.Widgets.Tabs

sealed

A tabbed navigation widget.

Object-initializer constructor; all properties default.

Renders a tab bar on the first row, and the Body widget in the remaining area.

The caller is responsible for supplying the correct Body for the ActiveIndex (swap it in the model's Update handler when TabChangedMsg arrives).

Key handling when focused:

• Left/Right arrows — cycle tabs, wrap-around.
• Number keys 1–9 — jump directly to tab N-1.

Tab switching does not move keyboard focus to the body — the model controls focus assignment independently.

TextArea

ConsoleForge.Widgets.TextArea

sealed

A multi-line text input widget.

Object-initializer constructor; all properties default.

Cursor position and scroll state live in the model (all properties are { get; init; }) — Update returns the next widget rather than mutating this one, so the model stores what it returns.

Scroll — The widget renders lines [ScrollRow, ScrollRow + visibleHeight). Update ScrollRow in your model's Update handler; use ComputeScrollRow as a helper.

Line endings — All text is stored as a list of strings (one per logical line). The widget does not produce or consume
in its messages.

TextBlock

record ConsoleForge.Widgets.TextBlock

sealed

A widget that renders a single string, wrapping at region width.

Inherits style from the active theme's BaseStyle when widget style has no properties set.

TextInput

ConsoleForge.Widgets.TextInput

sealed

A single-line text input widget that accepts keyboard input when focused.

Object-initializer constructor; all properties default.

ZStack

record ConsoleForge.Widgets.ZStack

sealed

A layered widget that renders its children back-to-front over the same region.

Each layer is given the full allocated region; later layers paint over earlier ones.

Typical usage — base layout + optional overlay:

new ZStack([
    mainLayout,
    isModalOpen ? new Modal(...) : new TextBlock(""),
])

Core.FocusManager traverses all layers for focus collection, so interactive widgets in any layer participate in Tab-order traversal.

Layers composite by painting, not by blending: a layer that writes a cell replaces what was there, and one that fills its whole region hides every layer beneath it. Modal.ShowBackdrop is the case to know about — it blanks the full region before drawing its dialog, which erases the layout you stacked it over.