Terminal

The terminal classes provide the runtime connection between your rendered content and the real console. Terminal manages the application lifecycle, refresh strategy, cursor control, direct text output, and the platform backend that ultimately emits text and control sequences.

This section focuses on application-level terminal control. For the shared streaming output API used by both Terminal and CursorBuffer, see Cursor Output. For custom backend implementations and capability fallback behavior, see Backend.

Usage

Preparing and Rendering a Screen

Terminal is the high-level entry point for full-screen terminal applications. It owns the platform backend, manages the visible screen state, and renders ReadableBuffer objects with clipping and optional crop marks.

auto terminal = Terminal{Size{90, 28}};
terminal.initializeScreen();
terminal.setRefreshMode(Terminal::RefreshMode::Overwrite);

auto buffer = Buffer{terminal.size()};
buffer.fill(Char{" ", Color{fg::Default, bg::Black}});
buffer.drawText(
    "Frame and buffer rendering",
    Rectangle{2, 2, buffer.size().width() - 4, 5},
    Alignment::Center,
    Color{fg::BrightWhite, bg::Blue});

auto settings = UpdateSettings{};
settings.setSwitchToAlternateBuffer(false);

terminal.updateScreen(buffer, settings);
terminal.flush();
terminal.restoreScreen();

Terminal::size() returns the drawable size used by updateScreen(). By default, this includes a one-column and one-row compatibility margin so full-screen buffers work out of the box.

Disable that margin with setSafeMarginEnabled(false) if you want to use the full detected terminal size and rely purely on cursor-based updates.

For short-lived tools that should leave their output in the normal terminal history, disable alternate-screen switching via UpdateSettings as shown above.

Render Loop for Interactive Applications

The following example shows a minimal render loop for an interactive terminal application.

struct MyApp {
    void renderFrame() {
        _terminal.testScreenSize();
        _buffer.resize(_terminal.size());
        _buffer.fill(Char{" ", bg::Black});

        // Draw the current frame into the buffer.
        _terminal.updateScreen(_buffer, _updateSettings);
    }

    void handleKey(Key key) {
        if (key == Key{Key::Character, U'q'}) {
            _quitRequested = true;
        }
    }

    void run() {
        _terminal.initializeScreen();
        _terminal.input().setMode(Input::Mode::Key);

        _updateSettings.setMinimumSize(Size{40, 20});
        _updateSettings.setMinimumSizeMessage(String("Too Small!"));

        while (!_quitRequested) {
            const auto key = _terminal.input().read(std::chrono::milliseconds{90});
            if (key.valid()) {
                handleKey(key);
            }
            renderFrame();
        }

        _terminal.restoreScreen();
    }

    Terminal _terminal;
    Buffer _buffer;
    UpdateSettings _updateSettings;
    bool _quitRequested;
};

Call Terminal::initializeScreen() once when your application starts, and Terminal::restoreScreen() once just before it exits.

After initialization, use Terminal::isInteractive() to detect whether a real terminal is attached. This allows you to switch to a plain-text fallback when output is redirected.

If your application is interrupted (for example via Ctrl+C), the library restores the terminal state automatically before returning control to the shell.

Create exactly one Terminal instance for the lifetime of your application. While multiple instances are possible, they share the same underlying backend, so a single instance is simpler and safer.

For interactive programs, switch the input mode to Input::Mode::Key. This hides the cursor and lets your application react to individual key presses via input().read(). The timeout also serves as a natural frame rate control.

Keep a persistent Buffer instance, resize it to the current terminal size, and reuse it for each frame. After drawing into the buffer, call updateScreen() to present the new frame.

By default, rendering is optimized to update only the parts of the screen that actually changed. This makes frequent refresh rates practical, as only modified regions are written to the terminal.

Direct Writes, Line Buffering, and Refresh Modes

For simpler tools and status output, you can use Terminal without a full-screen buffer. print(), printLine(), and write() send text directly to the terminal while still applying color handling.

These direct-write functions are part of the shared CursorWriter interface. This page focuses on how they behave on a real terminal; the reusable streaming API itself is documented on Cursor Output.

terminal.setOutputMode(Terminal::OutputMode::FullControl);
terminal.printLine(fg::BrightGreen, "Service started");
terminal.print("Current mode: ", fg::BrightYellow, "interactive");
terminal.writeLineBreak();
terminal.flush();

Line buffering keeps partial lines in memory until a newline is written or flush() is called. This keeps incremental output clean and avoids fragmented lines.

For full-screen applications:

RefreshMode::Clear clears the entire screen before each frame.
RefreshMode::Overwrite moves to the home position and works with the back buffer for efficient updates.

Controlling Screen Update Settings

UpdateSettings controls how Terminal::updateScreen() behaves when content does not fit the terminal or the terminal is too small.

auto settings = UpdateSettings{};
settings.setMinimumSize(Size{60, 18});
settings.setMinimumSizeBackground(Char{" ", Color{fg::Inherited, bg::Red}});
settings.setMinimumSizeMessage(String{"Please enlarge the terminal"});
settings.setShowCropMarks(true);

terminal.updateScreen(buffer, settings);

Use this to define minimum sizes, customize fallback backgrounds, and control crop indicators when the layout cannot be rendered as intended.

Output Modes

Terminal supports two output modes:

Terminal::OutputMode::FullControl (default) enables colored output, cursor control, refresh handling, back-buffer updates, and terminal-size detection.
Terminal::OutputMode::Text keeps the terminal in plain-text mode. In this mode, write() and print() still work, but cursor control, refresh handling, screen clearing, size detection, and the back buffer are disabled.

The terminal always owns a backend internally, but most applications can treat it as an implementation detail and rely on the high-level API.

If you need to inject a custom backend or understand capability fallback behavior, continue with Backend.

Interface

class UpdateSettings

Settings controlling how Terminal::updateScreen() renders a buffer.

Public Functions

UpdateSettings() = default: Create default screen update settings.

Size minimumSize() const noexcept

Get the minimum terminal size required for rendering the buffer.

Returns:: The minimum supported terminal size.

void setMinimumSize(Size minimumSize) noexcept

Set the minimum terminal size required for rendering the buffer.

Parameters:: minimumSize – The minimum supported terminal size.

const Char &minimumSizeBackground() const noexcept: Get the background character used if the terminal is too small.

void setMinimumSizeBackground(Char character) noexcept

Set the background fill character when the terminal is too small.

Parameters:: character – The background character

const String &minimumSizeMessage() const noexcept: Get the message displayed if the terminal size is too small.

void setMinimumSizeMessage(String message) noexcept

Set the message displayed if the terminal is too small.

Parameters:: message – The displayed message.

bool showCropMarks() const noexcept: Check if crop marks are enabled.

void setShowCropMarks(bool showCropMarks) noexcept

Enable or disable crop marks.

Parameters:: showCropMarks – true to render crop marks for truncated content.

const Char &cropMarkRight() const noexcept: Get the mark rendered when content is cropped on the right.

void setCropMarkRight(Char cropMarkRight) noexcept

Set the mark rendered if the content is cropped on the right.

Parameters:: cropMarkRight – The right crop mark.

const Char &cropMarkBottomRight() const noexcept: Get the mark rendered in the bottom right corner when content is cropped.

void setCropMarkBottomRight(Char cropMarkBottomRight) noexcept

Set the mark in the bottom right corner if content is cropped on the bottom and right.

Parameters:: cropMarkBottomRight – The bottom-right crop mark.

const Char &cropMarkBottom() const noexcept: Get the mark rendered when content is cropped at the bottom.

void setCropMarkBottom(Char cropMarkBottom) noexcept

Set the mark rendered if the content is cropped at the bottom.

Parameters:: cropMarkBottom – The bottom crop mark.

bool switchToAlternateBuffer() const noexcept: Test if the update shall switch to the alternate screen buffer.

void setSwitchToAlternateBuffer(bool switchToAlternateBuffer) noexcept

Enable or disable switching to the alternate screen buffer.

Parameters:: switchToAlternateBuffer – true to switch to the alternate screen buffer.

void applyTo(BufferViewBase &view) const noexcept: Apply these settings to a BufferView.

void setMinimumSizeMark(Char minimumSizeMark) noexcept

Set the minimum-size background character through the legacy name.

Deprecated:: Use setMinimumSizeBackground() instead.

Parameters:: minimumSizeMark – The background character shown when the terminal is too small.

const Char &minimumSizeMark() const noexcept

Get the minimum-size background character through the legacy name.

Deprecated:: Use minimumSizeBackground() instead.

Returns:: The background character shown when the terminal is too small.

UpdateSettings(Size minimumSize, Char minimumSizeBackground, bool showCropMarks, Char cropMarkRight, Char cropMarkBottom) noexcept

Construct update settings using the deprecated aggregate-style compatibility constructor.

Deprecated:: Construct UpdateSettings{} and configure it with setters instead.

Parameters:

minimumSize – The minimum terminal size required for normal rendering.
minimumSizeBackground – The fill character for the size-too-small background.
showCropMarks – true to show crop marks for truncated content.
cropMarkRight – The crop mark to draw at the right edge.
cropMarkBottom – The crop mark to draw at the bottom edge.

Public Static Functions

static const UpdateSettings &defaultSettings() noexcept: Shared default value.

class Terminal : public erbsland::cterm::CursorWriter 

High-level terminal interface for screen control, color output, and key input.

Public Types

enum class RefreshMode : uint8_t

Screen clearing strategy used between rendered frames.

Values:

enumerator Keep: Do not emit cursor or clear-screen control sequences automatically.

enumerator Clear: Clear the full screen before rendering the next frame.

enumerator Overwrite: Move the cursor to the top-left corner before rendering the next frame.

enum class OutputMode : uint8_t

The output mode for the terminal.

Values:

enumerator Text: Only output plain text with no colors and no cursor control.

enumerator FullControl: Full control over the terminal, including colors and cursor control.

using ScreenSizeChangedCallback = std::function<void(Size)>: Callback invoked when the drawable terminal size changes or is initialized.

Public Functions

explicit Terminal(): Create a new terminal instance with default values.

explicit Terminal(TerminalFlags flags = {})

Create a new terminal instance.

Parameters:: flags – The terminal flags to use.

explicit Terminal(Size size = {80, 25}, TerminalFlags flags = {})

Create a new terminal instance.

The size is automatically bounded to the minimum and maximum supported sizes.

Parameters:

size – The fallback terminal size used when automatic detection is unavailable.
flags – The terminal flags to use.

explicit Terminal(BackendPtr backend, Size size = {80, 25})

Create a new terminal instance with a custom backend.

The size is automatically bounded to the minimum and maximum supported sizes.

Parameters:

backend – The backend to use for the terminal.
size – The fallback terminal size used when automatic detection is unavailable.

inline virtual Size size() const noexcept override: Get the size of the screen/writing area.

virtual Color color() const noexcept override

Get the current color.

Returns:: The currently tracked terminal color state.

virtual CharAttributes charAttributes() const noexcept override

Get the current character attributes.

Returns:: The currently tracked character attribute state.

virtual void setColor(Color color) noexcept override

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 override

Set all character attributes.

Unspecified attributes are treated as disabled.

Parameters:: attributes – The new character attributes.

virtual void setForeground(Foreground color) noexcept override

Set the foreground color.

Note

Inherited colors are converted to Default colors.

Parameters:: color – The new foreground color.

virtual void setBackground(Background color) noexcept override

Set the background color.

Note

Inherited colors are converted to Default colors.

Parameters:: color – The new background color.

virtual CharAttributes supportedCharAttributes() const noexcept override

Get the character attributes supported by this writer.

Returns:: The supported character attributes.

virtual void moveLeft(Coordinate count) noexcept override

Move the cursor to the left.