Terminal Class Reference

Low-level terminal I/O abstraction. More...

#include <terminal.h>

Public Types
enum	ColorSupport {   NoColor , Grayscale16 , Grayscale256 , GrayscaleTrue ,   Basic , Color256 , TrueColor }
	Describes the color capability level of the terminal. More...
using	ResizeCallback = std::function< void(int cols, int rows)>
	Callback type for window resize notifications.

Public Member Functions
	Terminal ()
	Constructs a Terminal and saves the current terminal state.
	~Terminal ()
	Destructor. Restores terminal state and cleans up.
	Terminal (const Terminal &)=delete
Terminal &	operator= (const Terminal &)=delete
Error	enableRawMode ()
	Enables raw terminal mode (disables line buffering, echo, etc).
Error	disableRawMode ()
	Restores the terminal to its original mode.
bool	isRawMode () const
	Returns true if raw mode is currently enabled.
Result< int >	readInput (char *buf, int maxLen)
	Reads available input bytes without blocking.
Error	windowSize (int &cols, int &rows) const
	Queries the current terminal window size.
Size2Di32	size () const
	Returns the terminal size as a Size2Du32 (width x height).
Error	enableMouseTracking ()
	Enables xterm SGR mouse tracking.
Error	disableMouseTracking ()
	Disables mouse tracking.
bool	isMouseTrackingEnabled () const
	Returns true if mouse tracking is enabled.
Error	enableBracketedPaste ()
	Enables bracketed paste mode.
Error	disableBracketedPaste ()
	Disables bracketed paste mode.
Error	enableAlternateScreen ()
	Switches to the alternate screen buffer.
Error	disableAlternateScreen ()
	Switches back to the main screen buffer.
void	setResizeCallback (ResizeCallback cb)
	Sets a callback for window resize events (SIGWINCH on POSIX).
void	installSignalHandlers ()
	Installs signal handlers for clean terminal restoration.
Result< int >	writeOutput (const char *data, int len)
	Writes raw bytes to stdout.

Static Public Member Functions
static ColorSupport	colorSupport ()
	Detects the color support level of the terminal.

Detailed Description

Low-level terminal I/O abstraction.

Provides raw terminal mode, non-blocking input, window size queries, mouse tracking, alternate screen buffer management, and color capability detection. Platform-specific implementations use termios on POSIX and Console API on Windows.

Member Enumeration Documentation

ColorSupport

enum Terminal::ColorSupport

Describes the color capability level of the terminal.

The TUI rendering pipeline always works with full RGB Color values internally. During TuiScreen::flush(), each cell's foreground and background are converted to the nearest representable color for the active ColorSupport level. This means the UI degrades gracefully to any color mode, but for the best visual results, applications should provide a TuiPalette whose colors are chosen with the target color mode in mind.

When the NO_COLOR environment variable is set, the detected color capability is mapped to its grayscale equivalent (e.g. TrueColor becomes GrayscaleTrue). Grayscale modes convert each color to its perceptual luminance (Rec. 709) before emitting it.

See also

TuiScreen::setColorMode()

TuiPalette

Enumerator
NoColor	No color support (e.g. dumb terminal).
Grayscale16	Grayscale via the 4 gray entries in the 16-color palette (NO_COLOR + Basic).
Grayscale256	Grayscale via the 24-entry grayscale ramp in the 256-color palette (NO_COLOR + 256).
GrayscaleTrue	Grayscale via 24-bit RGB with equal R=G=B (NO_COLOR + TrueColor).
Basic	Basic 8/16 color support (standard ANSI).
Color256	256 color support (xterm-256color and similar).
TrueColor	24-bit true color support.

Member Function Documentation

colorSupport()

static ColorSupport Terminal::colorSupport ( )

static

Detects the color support level of the terminal.

Examines environment variables to determine the level of color support. The PROMEKI_COLOR variable, if set, overrides auto-detection (accepted values: "truecolor", "24bit", "256", "basic", "ansi", "16", "none"). Otherwise, COLORTERM, TERM, and TERM_PROGRAM are examined.

When NO_COLOR is set (see https://no-color.org/), the detected capability is mapped to its grayscale equivalent. The result is cached after the first call.

Returns

The detected ColorSupport level.

disableAlternateScreen()

Error Terminal::disableAlternateScreen

(

)

Switches back to the main screen buffer.

Returns

Error::Ok on success, or an error on failure.

disableBracketedPaste()

Error Terminal::disableBracketedPaste

(

)

Disables bracketed paste mode.

Returns

Error::Ok on success, or an error on failure.

disableMouseTracking()

Error Terminal::disableMouseTracking

(

)

Disables mouse tracking.

Returns

Error::Ok on success, or an error on failure.

disableRawMode()

Error Terminal::disableRawMode

(

)

Restores the terminal to its original mode.

Returns

Error::Ok on success, or an error on failure.

enableAlternateScreen()

Error Terminal::enableAlternateScreen

(

)

Switches to the alternate screen buffer.

Returns

Error::Ok on success, or an error on failure.

enableBracketedPaste()

Error Terminal::enableBracketedPaste

(

)

Enables bracketed paste mode.

Returns

Error::Ok on success, or an error on failure.

enableMouseTracking()

Error Terminal::enableMouseTracking

(

)

Enables xterm SGR mouse tracking.

Returns

Error::Ok on success, or an error on failure.

enableRawMode()

Error Terminal::enableRawMode

(

)

Enables raw terminal mode (disables line buffering, echo, etc).

Returns

Error::Ok on success, or an error on failure.

installSignalHandlers()

void Terminal::installSignalHandlers

(

)

Installs signal handlers for clean terminal restoration.

Ensures raw mode and alternate screen are restored on SIGTERM, SIGINT, and other termination signals.

readInput()

Result< int > Terminal::readInput	(	char *	buf,
		int	maxLen
	)

Reads available input bytes without blocking.

Parameters

buf	Buffer to read into.
maxLen	Maximum bytes to read.

Returns

A Result containing the number of bytes read (0 if nothing available), or an error.

setResizeCallback()

void Terminal::setResizeCallback

(

ResizeCallback

cb

)

Sets a callback for window resize events (SIGWINCH on POSIX).

Parameters

cb	The callback to invoke on resize.

windowSize()

Error Terminal::windowSize	(	int &	cols,
		int &	rows
	)		const

Queries the current terminal window size.

Parameters

cols	Output: number of columns.
rows	Output: number of rows.

Returns

Error::Ok on success, or an error on failure.

writeOutput()

Result< int > Terminal::writeOutput	(	const char *	data,
		int	len
	)

Writes raw bytes to stdout.

Parameters

data	The data to write.
len	Number of bytes to write.

Returns

A Result containing the number of bytes written, or an error.

---

The documentation for this class was generated from the following file:

• include/promeki/core/terminal.h