mitchellwrosen / termbox2

suckless terminal rendering library

termbox2

termbox2 is a terminal rendering library that retains the suckless spirit of the original termbox (simple API, no dependencies beyond libc) and adds some improvements (strict error checking, more efficient escape sequence parsing, code gen for built-in escape sequences, opt-in support for 32-bit color, extended grapheme clusters, test suite). termbox2 is organized as a single file header library, though it is possible to compile it as a stand-alone shared or static library.

Synopsis

#define TB_IMPL
#include "termbox2.h"

int main(int argc, char **argv) {
    struct tb_event ev;
    int y = 0;

    tb_init();

    tb_printf(0, y++, TB_GREEN, 0, "hello from termbox");
    tb_printf(0, y++, 0, 0, "width=%d height=%d", tb_width(), tb_height());
    tb_printf(0, y++, 0, 0, "press any key...");
    tb_present();

    tb_poll_event(&ev);

    y++;
    tb_printf(0, y++, 0, 0, "event type=%d key=%d ch=%c", ev.type, ev.key, ev.ch);
    tb_printf(0, y++, 0, 0, "press any key to quit...");
    tb_present();

    tb_poll_event(&ev);
    tb_shutdown();

    return 0;
}

API

The basic API should be pretty self-explanatory. Consult the header file itself for the complete API and documentation.

int tb_init();
int tb_shutdown();

int tb_width();
int tb_height();

int tb_clear();
int tb_present();

int tb_set_cursor(int cx, int cy);
int tb_hide_cursor();

int tb_set_cell(int x, int y, uint32_t ch, uintattr_t fg, uintattr_t bg);

int tb_peek_event(struct tb_event *event, int timeout_ms);
int tb_poll_event(struct tb_event *event);

int tb_print(int x, int y, uintattr_t fg, uintattr_t bg, const char *str);
int tb_printf(int x, int y, uintattr_t fg, uintattr_t bg, const char *fmt, ...);

How to use termbox2

As mentioned above, there are two options:

1. Copy (or git submodule) termbox2.h into your C project. As normal, include the header file wherever you want to use tb_* functions, but also be sure to #define TB_IMPL in exactly one of your source files. (This is a common pattern for single file header libraries.)
2. Build termbox2 as a library (either make libtermbox2.so or make libtermbox2.a) and link as normal.

Language bindings

Basic FFI examples in the languages below are in the demo/ directory. (Feel free to submit PRs for other languages.)

• D
• Go
• Nim
• PHP
• Python
• Ruby
• Rust
• Zig

Other wrapper libraries:

• termbox.cr (Crystal)
• termbox2.cr (Crystal)
• Termbox.pm (Perl)
• termbox2-hs (Haskell)

Examples

• mle - flexible terminal-based text editor
• ictree - like tree but interactive
• lavat - lava lamp for the terminal
• termbox-tetris - Tetris clone
• dvd-screensaver - a terminal screensaver
• matrix-tui - Matrix client
• Vgmi - Gemini client
• poe - .po file editor