Cursor Output

Cursor output is the shared streaming API used by Terminal and CursorBuffer.

CursorWriter combines cursor movement, active color state, active character attributes, plain text output, and paragraph printing into a single, consistent interface. MoveMode distinguishes between absolute and relative cursor movement.

Use this API when you want to print mixed text and color arguments, write terminal-style output into a CursorBuffer, or precisely control cursor positioning.

This page documents the shared output model only. Screen lifecycle, full-screen rendering, refresh settings, and backend ownership remain on Terminal.

Usage

Printing Mixed Arguments

CursorWriter is designed for fluent, terminal-style output.

The print() and printLine() functions accept a mix of colors, character styles, character attributes, terminal strings, and plain text in a single call. As arguments are processed, the active color and attribute state is updated automatically.

terminal.printLine(
    fg::BrightGreen,
    "Service started at ",
    fg::BrightWhite,
    "09:42");

terminal.print(
    bg::BrightBlack,
    fg::BrightYellow,
    "[Q] ",
    fg::BrightWhite,
    "quit");

auto emphasis = CharAttributes{};
emphasis.setBold(true);
emphasis.setUnderline(true);
const auto headingStyle = CharStyle{Color{fg::BrightWhite, bg::Inherited}, emphasis};

terminal.printLine(
    headingStyle,
    "Important",
    CharAttributes::reset(),
    fg::BrightBlack,
    " uses both bold and underline.");

Because the active color and attribute state is part of the writer, subsequent output continues using the most recently selected values until you change them again or call CursorWriter::setDefaultColor(). Use CharAttributes::reset() when you want to explicitly turn all attributes back off. Use CursorWriter::style() and CursorWriter::setStyle() when you want to read or update the combined style in one step.

Moving the Cursor Explicitly

Use MoveMode when you need to control whether a movement is relative to the current cursor position or absolute within the writable area.

cursorBuffer.moveCursor(Position{10, 3}, MoveMode::Absolute);
cursorBuffer.print("Header");

cursorBuffer.moveCursor(Position{0, 2}, MoveMode::Relative);
cursorBuffer.printLine("First entry");

All convenience functions—such as moveLeft(), moveRight(), moveUp(), moveDown(), moveTo(), and moveHome()—are built on top of this same distinction.

VT100-Compatible Line Wrapping

The cursor writer follows a wrapping model compatible with traditional VT100-style terminals. This behavior is slightly different from a naïve “wrap immediately at the edge” approach.

When writing characters near the right edge of the buffer:

A character written into the last column does not immediately move the cursor to the next line.
Instead, a pending wrap is recorded internally.
The actual line break only happens when the next character is written.

This means:

The last column can be filled without triggering an immediate line break.
The next character causes the cursor to move to the beginning of the next line (if auto-wrap is enabled).

Wide characters (display width 2) are handled carefully:

If a wide character would not fully fit at the end of the line:
- With auto-wrap enabled, a line break occurs first.
- With auto-wrap disabled, the character is ignored.

Additional details to keep in mind:

If auto-wrap is disabled, writing at the right edge keeps the cursor pinned to the last column.
Explicit cursor movement (e.g. moveCursor()) clears any pending wrap.
Line breaks triggered by wrapping use the configured overflow mode (wrap, shift, or expand).

This behavior ensures compatibility with terminal output expectations and avoids subtle off-by-one rendering issues when mixing manual positioning and streaming text.

Printing Wrapped Paragraphs

Both Terminal and CursorBuffer implement the same paragraph-printing workflow via CursorWriter.

This allows you to reuse one paragraph configuration for direct terminal output and for buffered, scrollable content.

auto options = ParagraphOptions::defaultOptions();
options.setMaximumLineWraps(2);
options.setParagraphSpacing(ParagraphSpacing::DoubleLine);

logBuffer.printParagraph(
    "The same paragraph API works for live terminal output and for buffered history views.",
    options);

When writing to a Terminal, output is sent immediately to the active backend.

When writing to a CursorBuffer, the output becomes part of the buffer content and can later be rendered using Terminal::updateScreen() or displayed through a buffer view.

Choosing Between Terminal and CursorBuffer

Use Terminal when output should be written directly to the real console.

Use CursorBuffer when you want to keep the same streaming API, but retain the output for scrolling, clipping, copying, or re-rendering.

In practice, CursorWriter acts as the bridge between immediate output and retained, in-memory rendering.

Interface

class CursorWriter

The shared interface for buffers/terminals that support cursor-based output.

Subclassed by erbsland::cterm::CursorBuffer, erbsland::cterm::Terminal

Public Functions

virtual Color color() const noexcept = 0

Get the current color.

Returns:: The currently tracked terminal color state.

virtual CharAttributes charAttributes() const noexcept = 0

Get the current character attributes.

Returns:: The currently tracked character attribute state.

inline CharStyle style() const noexcept

Get the current combined text style.

Returns:: The currently tracked terminal style.

virtual void setColor(Color color) noexcept = 0

Set foreground and background color.

Note

Inherited colors are converted to Default colors.

Parameters:: color – The new combined color.

virtual void setCharAttributes(CharAttributes attributes) noexcept = 0

Set all character attributes.

Unspecified attributes are treated as disabled.

Parameters:: attributes – The new character attributes.

inline void setStyle(const CharStyle style) noexcept

Set the full terminal style.

Inherited colors are converted to defaults and unspecified attributes are treated as disabled.

Parameters:: style – The new combined style.

inline void setColor(const Foreground foregroundColor, const Background backgroundColor) noexcept

Set foreground and background color.

Note

Inherited colors are converted to Default colors.

Parameters:

foregroundColor – The new foreground color.
backgroundColor – The new background color.

virtual void setForeground(Foreground color) noexcept = 0

Set the foreground color.

Note

Inherited colors are converted to Default colors.

Parameters:: color – The new foreground color.

virtual void setBackground(Background color) noexcept = 0

Set the background color.

Note

Inherited colors are converted to Default colors.

Parameters:: color – The new background color.

inline void setDefaultColor() noexcept: Set the terminal default foreground and background colors.

virtual CharAttributes supportedCharAttributes() const noexcept = 0

Get the character attributes supported by this writer.

Returns:: The supported character attributes.

inline void setBold(const bool enabled) noexcept

Enable or disable the bold attribute.

Parameters:: enabled – true to enable bold, false to disable it.

inline void setDim(const bool enabled) noexcept

Enable or disable the dim attribute.

Parameters:: enabled – true to enable dim, false to disable it.

inline void setItalic(const bool enabled) noexcept

Enable or disable the italic attribute.

Parameters:: enabled – true to enable italic, false to disable it.

inline void setUnderline(const bool enabled) noexcept

Enable or disable the underline attribute.

Parameters:: enabled – true to enable underline, false to disable it.

inline void setBlink(const bool enabled) noexcept

Enable or disable the blink attribute.

Parameters:: enabled – true to enable blink, false to disable it.

inline void setReverse(const bool enabled) noexcept

Enable or disable the reverse attribute.

Parameters:: enabled – true to enable reverse, false to disable it.

inline void setHidden(const bool enabled) noexcept

Enable or disable the hidden attribute.

Parameters:: enabled – true to enable hidden, false to disable it.

inline void setStrikethrough(const bool enabled) noexcept

Enable or disable the strikethrough attribute.

Parameters:: enabled – true to enable strikethrough, false to disable it.

inline virtual void moveLeft(const Coordinate count) noexcept

Move the cursor to the left.