Erbsland Color Terminal Library Documentation

The Erbsland Color Terminal library is a small and focused C++20 static library designed for building rich terminal applications.

It provides reliable building blocks for colorful terminal output, Unicode-aware text handling, key-based input, and geometry helpers that simplify the development of terminal user interfaces, tools, and games.

Get Started with the Tutorial →

Topics

Usage Guides

Learn how to install the library, integrate it into your application, and run its unit tests.

Usage

Step-by-Step Tutorial

Start with a compact introduction to the library and build your first terminal program step by step.

Getting Started

API Reference

Explore the public modules, classes, and functions that make up the color terminal API.

Reference

Implementation Notes

Read internal backend notes intended for contributors who extend or debug the library itself.

Implementation Notes

Demo Gallery

Browse the included demo applications with screenshots and notes about the showcased features.

Demos

Requirements

Review the compiler, CMake, and Python requirements used by the library and its tooling.

Requirements

Change Log

Track new features, improvements, and breaking changes between releases.

Changelog

Features

Low-Level Terminal Abstraction

The low-level layer provides portable building blocks for terminal interaction.

Cross-platform terminal backend for Linux, macOS, and Windows — write once and compile everywhere
Direct control over colors, cursor positioning, and screen management
Automatic terminal detection and initialization
Convenient colored text output using ANSI escape sequences
Optional text-only mode for non-interactive applications
Unicode-aware terminal strings with accurate display-width calculation
Automatic handling of wide and combined Unicode code points
Detection and rejection of invalid UTF-8 sequences
Interactive key input and traditional line-based input
Geometry utilities for positions, sizes, rectangles, anchors, alignment, margins, and bitmaps
Efficient line buffering for handling large amounts of terminal output
Automatic terminal state restoration on exit, including unexpected exits caused by signals

High-Level Terminal Utilities

The high-level layer builds on the low-level primitives to simplify the implementation of complex terminal interfaces.

Efficient cell buffer classes for preparing terminal output
Automatic back-buffering and delta screen updates
Automatic switching to the alternate screen and restoration on exit
View system to render sections of buffers on screen
Frame and rectangle drawing utilities
Character-combination framework for building block-based terminal graphics
Tile-9 fill and tile-16 frame drawing helpers
Custom font support
Text wrapping and alignment utilities
Bitmap font rendering for large terminal text
Color sequences and animated color effects
Bitmap utilities for generating masks and rendering bitmaps to the screen

ANSI Foreground/Background Colors

The library provides easy-to-use low-level functionality for colorful, Unicode-aware terminal output.

Convenient print helpers allow you to combine text and colors while keeping your code readable and expressive.

A dedicated String class makes it possible to work with colored text safely. Combined Unicode characters are grouped correctly, and each visible character can have its own foreground and background color.

Handling of Zero-Width and Full-Width Characters

Mixing East Asian full-width characters or combined Unicode characters often breaks terminal layouts.

The Erbsland Color Terminal library correctly calculates the display width of commonly used Unicode character sequences and automatically handles them during text output.

This allows you to mix different scripts and Unicode symbols without breaking the layout of your terminal interface.

Frame and Rectangle Drawing

The library includes utilities for drawing frames, rectangles, and lines in various styles.

When lines intersect, the library automatically selects the best matching line characters to produce visually consistent borders.

Text Wrapping and Alignment

Text wrapping and alignment are integrated directly into the library.

You can easily format text blocks within a defined area, apply alignment rules, and keep layouts stable even when working with Unicode text.

Bitmap Fonts

The library can render large bitmap fonts directly in the terminal.

You can use the built-in character set or provide your own custom bitmap font to create banners, headings, or decorative output.