Library for writing text-based user interfaces

Related tags

Utilities termbox
Overview

IMPORTANT

This library is no longer maintained. It's pretty small if you have a big project that relies on it, just maintain it yourself. Or look for forks. Or look for alternatives. Or better - avoid using terminals for UI. Never the less, thanks to all who ever contributed.

Termbox

Termbox is a library that provides minimalistic API which allows the programmer to write text-based user interfaces.

It is based on a very simple abstraction. The main idea is viewing terminals as a table of fixed-size cells and input being a stream of structured messages. Would be fair to say that the model is inspired by windows console API. The abstraction itself is not perfect and it may create problems in certain areas. The most sensitive ones are copy & pasting and wide characters (mostly Chinese, Japanese, Korean (CJK) characters). When it comes to copy & pasting, the notion of cells is not really compatible with the idea of text. And CJK runes often require more than one cell to display them nicely. Despite the mentioned flaws, using such a simple model brings benefits in a form of simplicity. And KISS principle is important.

At this point one should realize, that CLI (command-line interfaces) aren't really a thing termbox is aimed at. But rather pseudo-graphical user interfaces.

Installation

Termbox comes with a waf-based build scripts. In order to configure, build and install it, do the following::

./waf configure --prefix=/usr                                (configure)
./waf                                                        (build)
./waf install --destdir=DESTDIR                              (install)

By default termbox will install the header file and both shared and static libraries. If you want to install a shared library or static library alone, use the following as an install command::

./waf install --targets=termbox_shared --destdir=PREFIX      (shared library)

or::

./waf install --targets=termbox_static --destdir=PREFIX      (static library)
Python

In order to install the python module, use the following command (as root or via sudo)::

python setup.py install

for Python 3::

python3 setup.py install

Getting started

Termbox's interface only consists of 12 functions::

tb_init() // initialization
tb_shutdown() // shutdown

tb_width() // width of the terminal screen
tb_height() // height of the terminal screen

tb_clear() // clear buffer
tb_present() // sync internal buffer with terminal

tb_put_cell()
tb_change_cell()
tb_blit() // drawing functions

tb_select_input_mode() // change input mode
tb_peek_event() // peek a keyboard event
tb_poll_event() // wait for a keyboard event

See src/termbox.h header file for full detail.

Links

If you want me to add your Termbox project here, send me a pull request or drop a note via email, you can find my email below.

Language bindings
Other implementations
Applications

Bugs & questions

Report bugs to the https://github.com/nsf/termbox issue tracker. Send rants and questions to me: [email protected].

Changes

v1.1.2:

  • Properly include changelog into the tagged version commit. I.e. I messed up by tagging v1.1.1 and describing it in changelog after tagged commit. This commit marked as v1.1.2 includes changelog for both v1.1.1 and v1.1.2. There are no code changes in this minor release.

v1.1.1:

v1.1.0:

  • API: tb_width() and tb_height() are guaranteed to be negative if the termbox wasn't initialized.
  • API: Output mode switching is now possible, adds 256-color and grayscale color modes.
  • API: Better tb_blit() function. Thanks, Gunnar Zötl [email protected].
  • API: New tb_cell_buffer() function for direct back buffer access.
  • API: Add new init function variants which allow using arbitrary file descriptor as a terminal.
  • Improvements in input handling code.
  • Calling tb_shutdown() twice is detected and results in abort() to discourage doing so.
  • Mouse event handling is ported from termbox-go.
  • Paint demo port from termbox-go to demonstrate mouse handling capabilities.
  • Bug fixes in code and documentation.

v1.0.0:

  • Remove the Go directory. People generally know about termbox-go and where to look for it.
  • Remove old terminfo-related python scripts and backport the new one from termbox-go.
  • Remove cmake/make-based build scripts, use waf.
  • Add a simple terminfo database parser. Now termbox prefers using the terminfo database if it can be found. Otherwise it still has a fallback built-in database for most popular terminals.
  • Some internal code cleanups and refactorings. The most important change is that termbox doesn't leak meaningless exported symbols like 'keys' and 'funcs' now. Only the ones that have 'tb_' as a prefix are being exported.
  • API: Remove unsigned ints, use plain ints instead.
  • API: Rename UTF-8 functions 'utf8_' -> 'tb_utf8_'.
  • API: TB_DEFAULT equals 0 now, it means you can use attributes alones assuming the default color.
  • API: Add TB_REVERSE.
  • API: Add TB_INPUT_CURRENT.
  • Move python module to its own directory and update it due to changes in the termbox library.
Issues
  • Documentation of C functions missing

    Documentation of C functions missing

    Maybe I simply don’t see it, but there is no function documentation in the C headers and hardly any comments in the source files.

    The Python bindings are documented, though.

    How come?

    opened by Profpatsch 25
  • 24 bit colors support (true colors)

    24 bit colors support (true colors)

    See more info here https://gist.github.com/XVilka/8346728

    opened by XVilka 19
  • Add a get_ch function

    Add a get_ch function

    This function returns the uint32_t utf8 character value at a particular cell coordinate in the back buffer.

    opened by jondoveston 18
  • keyboard input broken on OSX Terminal

    keyboard input broken on OSX Terminal

    Hi,

    I ran into some other problems, this time the wait_fill_event() function would hang on a keypress. Window resize worked fine. I traced the problem to fread() in termbox.c on line 428. It would always return 0 and control would jump back to while(1), going on forever. Turns out, some previous operation on *in descriptor had caused an EOF error and therefor all subsequent freads fail. Placing clearerr(in) before fread() solved the problem for me.

    G.

    opened by guncha 18
  • Added support for 216 colors

    Added support for 216 colors

    \033[38;5;Xm and \033[48;5;Xm are used.

    test: ./build/src/demo/output

    opened by robem 17
  • Add CMake build option and include it in the readme

    Add CMake build option and include it in the readme

    Some people probably want to use CMake to include termbox in their project. Waf is also not used a lot throughout the C/C++ community, but I'm leaving that as is.

    opened by rikvdh 12
  • Crash on terminal resize when waiting for events.

    Crash on terminal resize when waiting for events.

    I'm not sure precisely what's going on, though I've managed to narrow it down to what I believe to be the smallest crashing piece of code (if it was real code I'd probably issue a close() at the end, but it never gets there anyway in this demonstration).

    If I run the following script:

    import termbox
    
    tb = termbox.Termbox()
    
    while True:
        tb.poll_event()
    

    and then attempt to resize my terminal (both when resizing panes in tmux and resizing an xterm that it's running directly under), more often than not python will abort, simply dumping out this message:

    python3.2: src/termbox.c:521: wait_fill_event: Assertion `r > 0' failed.
    

    This also happens when using peek_event, and does not seem to be affected by the timeout passed to peek_event. It does not occur on key events, at least so far as I can tell.

    As I said before, I'm really not sure what's going on here, and I don't imagine what I've got so far is all that helpful, so any advice on how to get a more useful crash dump would be much appreciated.

    opened by jesskay 10
  • Pressing ESC after setting the mode to TB_MOUSE_INPUT triggers assertion error

    Pressing ESC after setting the mode to TB_MOUSE_INPUT triggers assertion error

    It triggers this assertion.

    The program is:

    #include "termbox.h"
    
    int main(int argc, char **argv) {
        tb_init();
        tb_select_input_mode(TB_INPUT_MOUSE);
    
        struct tb_event ev;
        tb_poll_event(&ev);
    
        tb_shutdown();
        return 0;
    }
    

    See also: gchp/rustbox#32

    Bug 
    opened by sru 9
  • add sys/select.h to includes

    add sys/select.h to includes

    add sys/select.h to includes

    opened by dcat 8
  • Cygwin peek/poll_event asserts wait_fill_event first read

    Cygwin peek/poll_event asserts wait_fill_event first read

    Using the same sequence of steps as keyboard.c, I get an assert in the very first block of reading code of wait_fill_event (currently line 581).

    I'm using the latest 32-bit Cygwin on Win7/64. Since I'm using CMake I made a static library for termbox.c and utf8.c to live in.

    I tried disabling the initial reading section of wait_fill_event, and that worked, until a resize occurred. Upon resizing the block of reading code in the while loop (currently line 613) would assert on errno==EAGAIN.

    opened by cardiffman 7
  • tb_peek_event() buffers inputs with sleep_for() c++11

    tb_peek_event() buffers inputs with sleep_for() c++11

    I'm not sure if this behavior of tb_peek_event() is intentional or not. I encountered it while attempting to make Tetris using termbox and trying to implement a time function and any inputs would stack rather than update on loop.

    It can be replicated like this:

    simply hold space and release when it shows 1.

    #include <termbox.h> #include <thread> #include <chrono> int main(void) { int i; tb_init(); tb_cell c = {}; tb_event e = {}; while(i < 4) { tb_clear(); std::this_thread::sleep_for(std::chrono::milliseconds(2000)); tb_peek_event(&e, 0); if(e.key == TB_KEY_SPACE) { i++; } c.ch = 48 + i; tb_put_cell(0,0,&c); tb_present(); } tb_shutdown(); return(0); }

    opened by Mutaru16bit 1
  • Allow reading the front buffer?

    Allow reading the front buffer?

    Feature request/idea: reading the front buffer

    A function like tb_cell_buffer for the front buffer would be nice to have. I realize it comes with some amount of risk. If there is interest, I'd be happy to prototype something.

    My use case is below, but I think this could be helpful in a more generic sense:

    I've made a mini termbox based window manager of sorts and would like to implement some type of modal functionality. I'd like to be able to push the contents of the front buffer on a stack, show a modal, and then display the previous front buffer again after the modal is closed.

    Since each section of my terminal is managed by an arbitrary number of window objects, it is impractical and inefficient to track their states manually.

    opened by josharenson 0
  • Are extended terminfo files being correctly parsed?

    Are extended terminfo files being correctly parsed?

    Code contains #define TI_ALT_MAGIC 542, which is the alternative header for terminfo "extended storage format". This is ultimately used to correctly calculate the strings offset into the compiled terminfo database.

    However, term(5) states that the alt magic is 0542, which is octal. TI_ALT_MAGIC should be set to (int)354, or prefixed with a zero.

    I don't have any extended storage format terminfo files handy, but I am happy to test if you point me to where I can get some.

    opened by mlabbe 2
  • Is this a C library?

    Is this a C library?

    I'm asking because the library isn't available in Gentoo and the README mentions setup.py.

    opened by psprint 2
  • Documentation of the API could be more helpful

    Documentation of the API could be more helpful

    The README says "Termbox's interface only consists of 12 functions", which is not really accurate (there's 21 functions), and lists just the function names. I think it would be helpful to give argument names (e.g. tb_change_cell(x, y, ch, fg, bg) instead of just tb_change_cell()) and either list all 21 functions, or explicitly say that the listed functions are only the most commonly used ones, but the API has a some other functions too.

    opened by bruce-hill 1
  • Add tb_poll_fds() to obtain file descriptors for polling

    Add tb_poll_fds() to obtain file descriptors for polling

    This adds a function to obtain file descriptors from termbox that can be be polled for IO-readiness. This can be used to integrate termbox into an event loop like asyncio or curio in python, or libuv in C, so the program can process other things (like network sockets) asynchronously with UI events.

    The idea is to use tb_poll_fds() to get a set of descriptors, register them for polling (e.g. with EPOLLIN), and when any events arrive, the next tb_poll_event() can be expected to complete quickly.

    (edit: markdown formatting and C usage example)

    opened by tobyp 2
  • Confution about output mode 216

    Confution about output mode 216

    #include <assert.h>
    #include "termbox.h"
    
    int main() {
      struct tb_event event;
    
      assert ( tb_init() == 0 );
    
      tb_select_output_mode(TB_OUTPUT_216);
    
      tb_clear();
      tb_change_cell(0, 0, 'x', TB_DEFAULT, 20);
      tb_present();
    
      tb_poll_event(&event);
      tb_shutdown();
    }
    

    The above program draws a single x at coords 0,0, then exits when a key is pressed. Notice that the foreground attribute is TB_DEFAULT and the background is 20. When I run this program, I see an orange x on a blue background. This seems to suggest that my default foreground color is orange.

    However, when I set both the foreground and background to TB_DEFAULT, I see a white x on a blackish (unaltered from my normal terminal) background.

    Why is this? Thanks :)

    opened by mitchellwrosen 0
  • Improper select() error handling

    Improper select() error handling

    https://github.com/nsf/termbox/blob/bbb64e9da7c5590dc7657eb1bece562089656dc1/src/termbox.c#L653-L655

    select returns -1 on error, which is never checked. This makes the function unresponsive to OS signals (EINTR), among other things.

    opened by mitchellwrosen 3
  • TB_OUTPUT_256: Cannot use black / write CSI 38;5;0

    TB_OUTPUT_256: Cannot use black / write CSI 38;5;0

    The current implementation treats the value 0 (=TB_DEFAULT) for fg/bg special in write_sgr(). This leads to much unexpected behavior, for once, one cannot use the TB_* constants with this mode anymore.

    Color | TB_OUTPUT_NORMAL | TB_OUTPUT_256 | |-|-|-| | clear | 0 | 0 | | black | 1 | - | | red | 2 | 1 | | ... | ... | ... |

    What seems to be the most sensible but also most radical solution to me would be:

    1. Make the TB_* constants line up with the actual values used ain SGR, ie. 0 for black etc.
    2. Set TB_DEFAULT to a different magic value that's not used anywhere and catch that, if we are breaking, we could actually use -1 and use int16_t instead.
    3. In fact, if we wanted to at some point support truecolor, we should perhaps even make it a bigger value.

    Also I've found that the code uses the TB_BOLD constant for bg to encode "blinking", which should be documented.

    opened by ljrk0 0
  • demo doesnt work on Beaglebone

    demo doesnt work on Beaglebone

    Hi

    I am running the demo application on Beaglebone and checking the output at serial console. The output at terminal software is all black. I am using the gcc version 4.6.

    opened by hayview 0
libnpy is a simple C++ library for reading and writing of numpy's .npy files.

C++ library for reading and writing of numpy's .npy files

Leon Merten Lohse 99 Nov 16, 2021
Group project: writing our own printf function

0x11. C - printf By Julien Barbier, co-founder & CEO Concepts For this project, students are expected to look at these concepts: Group Projects Pair P

Pericles ADJOVI 2 Oct 22, 2021
Writing our own printf function, this is a project done under ALX Low Level Programming.

0x11. C - printf Writing our own printf function, this is a project done under ALX Low Level Programming. Resource secrets of printf Implementing prin

Ephantus Mwangi 2 Oct 5, 2021
a cpp lib for csv reading and writing

CSV Reader and Writer Author : csl E-Mail : [email protected] OverView Comma separated values (CSV, sometimes called character separated values, becau

null 1 Oct 21, 2021
An easy-to-use C library for displaying text progress bars.

What is this thing? progressbar is a C-class (it's a convention, dammit) for displaying attractive progress bars on the command line. It's heavily inf

Trevor Fountain 419 Oct 31, 2021
The libxo library allows an application to generate text, XML, JSON, and HTML output using a common set of function calls. The application decides at run time which output style should be produced.

libxo libxo - A Library for Generating Text, XML, JSON, and HTML Output The libxo library allows an application to generate text, XML, JSON, and HTML

Juniper Networks 218 Nov 18, 2021
Rich text library supporting customizable Markdown formatting

Rich text library supporting customizable Markdown formatting

Brace Yourself Games 60 Dec 3, 2021
A header only C++ library that provides type safety and user defined literals for physical units

SI - Type safety for physical units A header only c++ library that provides type safety and user defined literals for handling pyhsical values defined

Dominik Berner 282 Dec 4, 2021
Mustache text templates for modern C++

About Mustache implementation for modern C++ (requires C++11) Header only Zero dependencies Templated string type for compatibility with any STL-like

Kevin Wojniak 263 Nov 5, 2021
Windows user-land hooks manipulation tool.

MineSweeper Windows user-land hooks manipulation tool. Highlights Supports any x64/x86 Windows DLL (actually, any x64/x86 Windows PE for that matter)

Arsenii Pustovit 89 Sep 27, 2021
Immediate Human User Interface

ImHui Immediate Human User Interface Inspired by Dear ImGui. The purpose of this project is to learn more about how Immedate Mode GUIs actually work.

Tsoding 30 Dec 1, 2021
Read Non-Rectangular Text Data

meltr The goal of ‘meltr’ is to provide a fast and friendly way to read non-rectangular data (like ragged forms of ‘csv’, ‘tsv’, and ‘fwf’). Standard

R infrastructure 22 Nov 20, 2021
A c++ file just to show how can we change color of Background and Text in C++...

A c++ file just to show how can we change color of Background and Text in C++...

null 1 Nov 2, 2021
libparser is a small C library that parses input based on a precompiled context-free grammar.

libparser is a small C library that parses input based on a precompiled context-free grammar.

Mattias Andrée 8 Aug 18, 2021
A fast character conversion and transliteration library based on the scheme defined for Japan National Tax Agency (国税庁) 's corporate number (法人番号) system.

jntajis-python Documentation: https://jntajis-python.readthedocs.io/ What's JNTAJIS-python? JNTAJIS-python is a transliteration library, specifically

Open Collector, Inc. 5 Sep 7, 2021
C string library based on string ends

C string library based on string ends

Leah Neukirchen 13 Nov 26, 2021
WAFer is a C language-based software platform for scalable server-side and networking applications. Think node.js for C programmers.

WAFer WAFer is a C language-based ultra-light scalable server-side web applications framework. Think node.js for C programmers. Because it's written i

Riolet Corporation 690 Nov 23, 2021
Fast comparison-based sort algorithm

nanosort Algorithm nanosort aims to be a fast comparison-based sorting algorithm, tuned for POD types of reasonably small sizes. nanosort implements a

Arseny Kapoulkine 33 Nov 1, 2021
Applications based on Wi-Fi CSI (Channel state information), such as indoor positioning, human detection

ESP-CSI The main purpose of this project is to show the use of ESP-WIFI-CSI. The human body detection algorithm is still being optimized. You can get

Espressif Systems 63 Nov 29, 2021