TerminalGUI

A header-only C++17 library for building terminal monitoring dashboards, inspired by the Immediate Mode GUI paradigm.

Features

• Header-only - Just include TerminalGUI.hpp
• High performance - Optimized for 60fps, zero allocations in the main loop
• Stable - Designed for 24/7 operation without memory leaks
• UTF-8 - Full Unicode support (borders and accents)
• Simple - Intuitive IMGUI-style API
• Linux-native - Built for Linux terminals

Installation

Copy include/TerminalGUI.hpp to your project and include it:

#include "TerminalGUI.hpp"

Quick Start

#include "TerminalGUI.hpp"
#include <thread>
#include <chrono>

int main() {
    tgui::init(tgui::Charset::Unicode);

    int frame = 0;
    while (true) {
        tgui::begin_frame();

        tgui::text("Monitoring Dashboard");
        tgui::new_line();

        tgui::textf("Frame: %d", frame++);
        tgui::textf_colored(tgui::Color::Green, "Status: %s", "OK");

        tgui::box_begin("CPU");
        tgui::textf("Usage: %d%%", 45);
        tgui::progress_bar(45, 100, 20);
        tgui::box_end();

        tgui::end_frame();
        std::this_thread::sleep_for(std::chrono::milliseconds(16));
    }

    tgui::shutdown();
}

API Reference

Initialization

Function	Description
init(Charset)	Initialize with Charset::ASCII or Charset::Unicode
shutdown()	Shutdown and free memory
begin_frame()	Start frame (clears buffer)
end_frame()	Render to terminal

Text

Function	Description
text(str)	Plain text
text(int)	Integer
text(float, decimals)	Float with N decimal places
textf(fmt, ...)	Formatted text (printf-style)
text_colored(str, color)	Colored text
textf_colored(color, fmt, ...)	Formatted + colored

Layout

Function	Description
same_line()	Next element on same line
new_line()	Force new line
separator(width)	Horizontal line
indent()	Increase indentation (+2 spaces)
unindent()	Decrease indentation
set_cursor(x, y)	Absolute position

Widgets

Function	Description
box_begin(title)	Start box (auto-sized)
box_begin(title, {w, h})	Fixed-size box (truncates with "...")
box_end()	End box
progress_bar(val, max, width)	Progress bar

Colors

Function	Description
set_color(fg, bg)	Set default color

tgui::Color::Black, Red, Green, Yellow, Blue, Magenta, Cyan, White
tgui::Color::BrightBlack, BrightRed, BrightGreen, BrightYellow,
             BrightBlue, BrightMagenta, BrightCyan, BrightWhite

Utilities

Function	Description
get_terminal_width()	Terminal width
get_terminal_height()	Terminal height

Building Examples

make all        # Build everything
make basic      # Basic example
make dashboard  # Full dashboard
make perf_test  # 60fps test

./bin/dashboard

Requirements

• Linux
• C++17
• No external dependencies

Performance

• Dirty checking - Only re-renders cells that changed
• Pre-allocated buffers - Zero allocations in main loop
• UTF-8 overlays - Multibyte characters with no overhead

License

MIT