Skip to content
BranchesTags

Repository files navigation

AntUI

A lightweight, cross-platform, zero-dependency Terminal UI library for C++23.

轻量级、跨平台、零依赖的 C++23 终端 UI 库。

English | 中文

Features

  • Cross-platform: Windows (Win32 Console API) and POSIX (termios)
  • C++23 Modern: Uses latest C++ features
  • Zero Dependencies: Only standard library and platform native APIs
  • True Color: 24-bit RGB with automatic 256-color fallback
  • Double Buffering: Incremental rendering — only changed cells are output
  • Declarative UI: Element tree describes layout, Component manages interaction
  • Gradient Support: Horizontal, vertical, and diagonal linear gradients

Quick Start

Installation

git clone https://github.com/yourusername/antui.git
cd antui
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .

Basic Usage

#include <antui/antui.h>
#include <iostream>

int main() {
  using namespace antui;

  auto screen = ScreenInteractive::Fullscreen();
  screen.Run([&]() {
    Screen& s = screen.GetScreen();
    s.Clear();
    s.DrawWindow(2, 2, 40, 10, "Hello");
    s.DrawString(4, 4, "Hello, AntUI!");
    s.Present();
  });

  return 0;
}

AntConch — Conversational CLI

#include <antui/antui.h>

int main() {
  using namespace antui;

  auto conch = Conch::Builder()
      .title("MyCLI")
      .model_name("demo-v1")
      .placeholder("Type a message...")
      .on_submit([](ConchComponent& c, const std::string& input) {
        c.AddMessage(ConchMessage::Assistant("Echo: " + input));
      })
      .build();

  auto screen = ScreenInteractive::Fullscreen();
  conch->Run(screen);
  return 0;
}

CMake Integration

find_package(antui REQUIRED)
target_link_libraries(myapp PRIVATE antui::antui)

Or as subdirectory:

add_subdirectory(third_party/antui)
target_link_libraries(myapp PRIVATE antui::antui)

API Overview

Terminal

Terminal terminal;
terminal.Initialize(true);       // raw mode
auto size = terminal.Size();     // get terminal dimensions
auto key = terminal.ReadKey();   // read key input
terminal.Shutdown();             // restore and cleanup

Screen

Screen screen(terminal);
screen.Initialize();
screen.Clear();
screen.DrawChar(10, 5, 'X');
screen.DrawString(10, 6, "Hello");
screen.DrawWindow(5, 5, 20, 10, "Title");
screen.Present();                // double-buffered incremental output

Elements — Declarative UI

Elements are stateless, render-only objects that describe what to draw.

// Text
auto text = Text("Hello World");

// Layout containers
auto vbox = VBox({Text("Line 1"), Text("Line 2")});
auto hbox = HBox({Text("Left"), Filler(), Text("Right")});

// Window with border
auto window = Window("Title", Text("Content"));

// Flex layout — takes remaining space
auto layout = VBox({
    Text("Header"),
    Flex(VBox({Text("Content area")})),  // fills remaining space
    Separator(),
    Text("Footer")
});

// Styling with pipe operator
auto styled = Text("Important") | Bold | FgColor(Color::kRed);

// True color and gradient
auto gradient = Text("Title")
    | GradientFg(ColorValue::RGB(220, 30, 30),
                 ColorValue::RGB(255, 165, 0),
                 GradientDirection::kVertical);

// Scrollable area
auto scrollable = ScrollArea(vbox, 0, true);  // auto-scroll to bottom

Components — Interactive UI

Components are stateful, event-driven objects that produce Elements.

// Input field
std::string content;
auto input = Input(&content, "Type here...");
input->OnEnter([] { std::cout << "Entered!\n"; });

// Button
auto button = Button("Click Me", [] { std::cout << "Clicked!\n"; });

// Container layout with focus navigation
auto container = ContainerLayout::Vertical({input, button});

Events

EventHandler handler = [](const Event& event) {
  if (event.IsKey() && event.GetKeyCode() == Key::kEscape) {
    return true;   // event handled
  }
  if (event.IsCharacter()) {
    char c = event.GetCharacter();
    return true;
  }
  return false;    // event not handled
};

Colors

// Named colors (16-color)
auto red = ColorValue::Named(1);
auto cyan = ColorValue::Named(6);

// 256-color palette
auto orange = ColorValue::Palette256(208);

// True color (24-bit RGB)
auto custom = ColorValue::RGB(255, 128, 0);

// Automatic fallback: RGB -> 256-color when terminal doesn't support true color
uint8_t idx = custom.ToPalette256();

// Linear interpolation
auto blended = ColorValue::Lerp(ColorValue::RGB(255, 0, 0),
                                 ColorValue::RGB(0, 0, 255), 0.5f);

// Convenience functions
auto green = Color::Green();
auto bright_white = Color::BrightWhite();

Building

Requirements

  • CMake 3.25+
  • C++23 compatible compiler:
    • GCC 13+
    • Clang 16+
    • MSVC 2022 17.8+

Options

Option Description Default
ANTUI_BUILD_EXAMPLES Build example programs ON
ANTUI_BUILD_TESTS Build unit tests ON
ANTUI_INSTALL Enable installation targets ON

Build Commands

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
ctest  # Run tests

Architecture

AntUI follows a five-layer architecture:

Application Layer  → ScreenInteractive (event loop)
Component Layer    → Component subclasses (interactive, stateful)
Element Layer      → Element subclasses (declarative, stateless)
Screen Layer       → Screen + ScreenBuffer (double-buffered rendering)
Terminal Layer     → Terminal (platform abstraction)

The core design principle is the Component/Element two-layer pattern:

  • Elements are declarative and stateless — they describe what to draw via Requirement() + Render()
  • Components are interactive and stateful — they handle events and produce Element trees via Render()

Documentation

License

MIT License — See LICENSE file for details.

Contributing

Contributions are welcome! Please follow the Google C++ Style Guide.

特性

  • 跨平台：Windows (Win32 Console API) 和 POSIX (termios)
  • C++23 现代标准：使用最新 C++ 特性
  • 零依赖：仅依赖标准库和平台原生 API
  • 真彩色：24-bit RGB 颜色，自动降级到 256 色
  • 双缓冲：增量渲染 — 仅输出变化的单元格
  • 声明式 UI：Element 树描述界面布局，Component 管理交互状态
  • 渐变支持：水平、垂直、对角方向的线性渐变

快速开始

安装

git clone https://github.com/yourusername/antui.git
cd antui
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .

基础用法

#include <antui/antui.h>
#include <iostream>

int main() {
  using namespace antui;

  auto screen = ScreenInteractive::Fullscreen();
  screen.Run([&]() {
    Screen& s = screen.GetScreen();
    s.Clear();
    s.DrawWindow(2, 2, 40, 10, "Hello");
    s.DrawString(4, 4, "Hello, AntUI!");
    s.Present();
  });

  return 0;
}

AntConch — 对话式 CLI

#include <antui/antui.h>

int main() {
  using namespace antui;

  auto conch = Conch::Builder()
      .title("MyCLI")
      .model_name("demo-v1")
      .placeholder("输入消息...")
      .on_submit([](ConchComponent& c, const std::string& input) {
        c.AddMessage(ConchMessage::Assistant("回显: " + input));
      })
      .build();

  auto screen = ScreenInteractive::Fullscreen();
  conch->Run(screen);
  return 0;
}

CMake 集成

find_package(antui REQUIRED)
target_link_libraries(myapp PRIVATE antui::antui)

或作为子目录：

add_subdirectory(third_party/antui)
target_link_libraries(myapp PRIVATE antui::antui)

API 概览

Terminal

Terminal terminal;
terminal.Initialize(true);       // 原始模式
auto size = terminal.Size();     // 获取终端尺寸
auto key = terminal.ReadKey();   // 读取按键输入
terminal.Shutdown();             // 恢复并清理

Screen

Screen screen(terminal);
screen.Initialize();
screen.Clear();
screen.DrawChar(10, 5, 'X');
screen.DrawString(10, 6, "Hello");
screen.DrawWindow(5, 5, 20, 10, "Title");
screen.Present();                // 双缓冲增量输出

Element — 声明式 UI

Element 是无状态、纯渲染的对象，描述要绘制的内容。

// 文本
auto text = Text("Hello World");

// 布局容器
auto vbox = VBox({Text("第一行"), Text("第二行")});
auto hbox = HBox({Text("左侧"), Filler(), Text("右侧")});

// 带边框的窗口
auto window = Window("标题", Text("内容"));

// Flex 布局 — 占据剩余空间
auto layout = VBox({
    Text("头部"),
    Flex(VBox({Text("内容区域")})),  // 填充剩余空间
    Separator(),
    Text("底部")
});

// 使用管道操作符链式装饰
auto styled = Text("重要") | Bold | FgColor(Color::kRed);

// 真彩色和渐变
auto gradient = Text("标题")
    | GradientFg(ColorValue::RGB(220, 30, 30),
                 ColorValue::RGB(255, 165, 0),
                 GradientDirection::kVertical);

// 可滚动区域
auto scrollable = ScrollArea(vbox, 0, true);  // 自动滚动到底部

Component — 交互式 UI

Component 是有状态、事件驱动的对象，生成 Element 树。

// 输入框
std::string content;
auto input = Input(&content, "在此输入...");
input->OnEnter([] { std::cout << "已输入!\n"; });

// 按钮
auto button = Button("点击我", [] { std::cout << "已点击!\n"; });

// 带焦点导航的容器布局
auto container = ContainerLayout::Vertical({input, button});

事件

EventHandler handler = [](const Event& event) {
  if (event.IsKey() && event.GetKeyCode() == Key::kEscape) {
    return true;   // 事件已处理
  }
  if (event.IsCharacter()) {
    char c = event.GetCharacter();
    return true;
  }
  return false;    // 事件未处理
};

颜色

// 命名色（16 色）
auto red = ColorValue::Named(1);
auto cyan = ColorValue::Named(6);

// 256 色调色板
auto orange = ColorValue::Palette256(208);

// 真彩色（24-bit RGB）
auto custom = ColorValue::RGB(255, 128, 0);

// 自动降级：终端不支持真彩色时 RGB -> 256 色
uint8_t idx = custom.ToPalette256();

// 线性插值
auto blended = ColorValue::Lerp(ColorValue::RGB(255, 0, 0),
                                 ColorValue::RGB(0, 0, 255), 0.5f);

// 便捷函数
auto green = Color::Green();
auto bright_white = Color::BrightWhite();

构建

环境要求

  • CMake 3.25+
  • C++23 兼容编译器：
    • GCC 13+
    • Clang 16+
    • MSVC 2022 17.8+

构建选项

选项 说明 默认值
ANTUI_BUILD_EXAMPLES 构建示例程序 ON
ANTUI_BUILD_TESTS 构建单元测试 ON
ANTUI_INSTALL 启用安装目标 ON

构建命令

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
ctest  # 运行测试

架构

AntUI 采用五层架构：

应用层   → ScreenInteractive（事件循环）
组件层   → Component 子类（交互式、有状态）
元素层   → Element 子类（声明式、无状态）
屏幕层   → Screen + ScreenBuffer（双缓冲渲染）
终端层   → Terminal（平台抽象）

核心设计原则是 Component/Element 双层模式：

  • Element 是声明式、无状态的 — 通过 Requirement() + Render() 描述要绘制的内容
  • Component 是交互式、有状态的 — 处理事件并通过 Render() 生成 Element 树

文档

许可证

MIT License — 详见 LICENSE 文件。

贡献

欢迎贡献代码！请遵循 Google C++ 代码风格指南。

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages