Creates a new terminal.

Parameters:

• backend - Terminal::Backend instance for I/O operations (default: Terminal::Backend.new)
• terminfo - Terminfo instance for capability strings (default: Terminfo.new)
• sync_updates - Enable DEC mode 2026 synchronized updates (default: true)

Returns whether alternate screen mode is active.

Sets the background color with full ANSI-8, ANSI-256, and RGB support.

Caches the color to avoid redundant escape sequences when called repeatedly with the same color.

Clears the cell buffer (fills with default cells).

Call render() to display changes on screen.

Clears the screen.

Writes the clear screen escape sequence immediately and flushes. Also resets cached render state since screen content is cleared.

Closes the terminal and underlying backend.

Returns the current terminal mode, or nil if not yet set.

Delegates to underlying Backend instance.

Disables enhanced keyboard protocol.

Returns to legacy keyboard mode where Tab/Ctrl+I, Enter/Ctrl+M, etc. are indistinguishable.

Disables mouse input tracking.

Disables both SGR and normal mouse protocols.

Disables raw mode on the terminal.

Enables blink.

Caches attribute state to avoid redundant escape sequences.

Enables bold text.

Caches attribute state to avoid redundant escape sequences.

Enables italic/cursive text.

Caches attribute state to avoid redundant escape sequences.

Enables dim/faint text.

Caches attribute state to avoid redundant escape sequences.

Enables enhanced keyboard protocol for disambiguated key reporting.

This enables the Kitty keyboard protocol (if supported) and falls back to modifyOtherKeys. Enhanced mode allows distinguishing between keys that normally send the same bytes:

• Tab vs Ctrl+I
• Enter vs Ctrl+M
• Backspace vs Ctrl+H

Not all terminals support these protocols. Unsupported terminals will simply ignore the escape sequences and continue with legacy behavior.

Example:

terminal.enable_enhanced_keyboard
# Now Ctrl+I and Tab are distinguishable
terminal.disable_enhanced_keyboard # When done

Enables hidden/invisible text.

Caches attribute state to avoid redundant escape sequences.

Enables mouse input tracking.

Enables SGR extended mouse protocol (mode 1006) for better coordinate support and unambiguous button detection. Falls back to normal mode (1000) on older terminals that don't support SGR.

Example:

terminal.enable_mouse
# Now mouse events will be reported via poll_event
terminal.disable_mouse # When done

Enables raw mode on the terminal.

Enables reverse video.

Caches attribute state to avoid redundant escape sequences.

Enables strikethrough text.

Caches attribute state to avoid redundant escape sequences.

Enables underline.

Caches attribute state to avoid redundant escape sequences.

Returns whether enhanced keyboard protocol is enabled.

Enters alternate screen mode.

Switches to alternate screen buffer, clears the screen, enters keypad mode, and hides cursor. Also resets cached render state since we're entering a fresh screen.

Exits alternate screen mode.

Shows cursor, exits keypad mode, and returns to main screen buffer. Also resets cached render state since we're returning to the main screen which may have different state.

Delegates flush to backend.

Sets the foreground color with full ANSI-8, ANSI-256, and RGB support.

Caches the color to avoid redundant escape sequences when called repeatedly with the same color.

Gets a cell at the specified position from the buffer.

Returns nil if coordinates are out of bounds.

Hides the cursor (rendered on next render()).

Returns the input file descriptor for Reader.

Invalidates the buffer, forcing a full re-render on next render().

Call this after the terminal screen has been cleared externally. Unlike sync(), this doesn't render immediately - it marks the buffer so the next render() call will redraw everything.

Returns whether mouse tracking is currently enabled.

Moves cursor to the specified position.

Uses the terminfo cup capability with tparm processing for proper terminal-specific cursor addressing. The cup capability handles the 0-to-1 based coordinate conversion via the %i operation.

Parameters:

• x: Column position (0-based)
• y: Row position (0-based)

Returns the output file descriptor.

Returns whether raw mode is currently enabled.

Renders cell buffer changes to the screen.

Only cells that have changed since the last render are redrawn (diff-based). This is more efficient than full redraws for partial updates.

When sync_updates is enabled, wraps the render in DEC mode 2026 sequences (BSU/ESU) to prevent screen tearing during rapid updates.

Resets all attributes to default.

Also clears cached color/attribute state since reset affects all styling.

Resets the cached render state.

Call this when the terminal state becomes unknown (e.g., after external programs have modified the terminal, or after errors). This forces the next color/attribute calls to emit escape sequences even if the cached values match.

The following operations automatically reset render state:

• enter_alternate_screen
• exit_alternate_screen
• clear_screen
• reset_attributes

Resizes the buffer to new dimensions.

Preserves existing content where possible.

Sets a cell at the specified position in the buffer.

Parameters:

• x: Column position (0-based)
• y: Row position (0-based)
• ch: Character to display
• fg: Foreground color (default: white)
• bg: Background color (default: default terminal color)
• attr: Text attributes (default: None)

Returns false if coordinates are out of bounds. Call render() to display changes on screen.

Sets cursor position in the buffer and makes it visible.

Coordinates are clamped to buffer bounds. Call render() to display the cursor on screen.

Sets terminal to specific mode using Terminal::Mode flags.

Updates raw_mode_enabled tracking based on whether mode is raw. Does not handle screen or cursor transitions - use with_mode for that.

Parameters:

• mode: Terminal::Mode flags specifying desired behavior

Example:

terminal.set_mode(Terminal::Mode.cooked)
terminal.set_mode(Terminal::Mode.raw)

ameba:disable Naming/AccessorMethodName

Shows the cursor at current position (rendered on next render()).

Delegates size to backend.

Forces a full redraw of all cells.

Useful after terminal resize or screen corruption.

When sync_updates is enabled, wraps the sync in DEC mode 2026 sequences (BSU/ESU) to prevent screen tearing during the full redraw.

Sets whether synchronized updates are enabled.

Can be toggled at runtime. Set to false for debugging or compatibility with terminals that misbehave with sync sequences.

Returns whether synchronized updates are enabled.

When enabled, render operations are wrapped in BSU/ESU sequences to prevent screen tearing. Enabled by default.

Executes a block with cbreak mode.

Cbreak mode provides character-by-character input with echo and signal handling. Useful for interactive prompts where you want immediate response but still show typed characters.

By default, preserves alternate screen since cbreak is typically used within a TUI context.

Example:

terminal.with_cbreak_mode do
  print "Press any key: "
  key = STDIN.read_char
end

Executes a block with cooked (shell-like) mode.

Cooked mode enables canonical input, echo, and signal handling - ideal for shell-out operations where the subprocess needs full terminal control.

By default, exits alternate screen to show the normal terminal, then re-enters alternate screen after the block.

Example:

terminal.with_cooked_mode do
  system("vim file.txt")
end

Executes a block with specific terminal mode, restoring previous mode after.

This is the recommended way to temporarily switch modes for operations like shell-out or password input. Handles:

• Mode switching via Backend
• Alternate screen exit/entry based on preserve_screen parameter
• Cursor visibility (shown for user-interactive modes)

Parameters:

• mode: Terminal::Mode to use within the block
• preserve_screen: If false (default) and mode is canonical, exits alternate screen during block. If true, stays in alternate screen.

Example:

terminal.with_mode(Terminal::Mode.cooked) do
  system("vim file.txt")
end
# Previous mode and screen state restored

Executes a block with password input mode.

Password mode enables canonical (line-buffered) input with signal handling but disables echo. Perfect for secure password entry.

By default, preserves alternate screen since password prompts often appear within a TUI context.

Example:

terminal.with_password_mode do
  print "Password: "
  password = gets
end

Executes a block with raw mode enabled, ensuring cleanup.

Delegates write to backend.

Writes hide cursor escape sequence immediately.

Caches visibility state to avoid redundant escape sequences. Note: This is part of the Renderer interface, called by Buffer. For buffer-based cursor control, use hide_cursor instead.

Writes show cursor escape sequence immediately.

Caches visibility state to avoid redundant escape sequences. Note: This is part of the Renderer interface, called by Buffer. For buffer-based cursor control, use show_cursor instead.