BTUI - Bruce's Text User Interface Library

BTUI is a minimal, embeddable, single-header-file Text User Interface (TUI) library and alternative to bloatware like ncurses. BTUI aims to be less than 1% the size of ncurses, while also providing a better API for the programmer who is not afraid to roll up their sleeves and manage their own state. If you want a drop-in TUI library that lets you switch into TUI mode, write some strings to the screen with 24-bit color, and get user keypresses in real-time without line buffering, then this is the library for you!

Note: Currently, BTUI is somewhere between 0.5% and 0.1% the size of ncurses, but even counting the number of lines of code in ncurses is hard.

Cleanup by Default

Once BTUI is enabled, you can manually disable TUI Mode (e.g. if you want to temporarily drop back to the regular shell). However, BTUI will always automatically put the terminal back in a normal state when your program exits, even in the event of a segfault or other blockable signal. BTUI can't do anything about unblockable signals like SIGKILL though, so don't use killall -9 myprog unless you want a gunked up terminal (just use kill myprog instead). If your terminal does get gunked up, you can always run the reset shell command to reset it.

Easy 24-bit Colors

BTUI supports 24-bit colors. It's dead easy, just btui_set_fg(bt, r, g, b) (foreground color) or btui_set_bg(bt, r, g, b) (background color). Try make rainbow to see a demo of 24-bit colors in action. This has been supported by most terminals for aeons, but most TUI applications still default to using the same 8 colors. It doesn't have to be that way! (Although you can still use those colors with btui_set_attributes(bt, BTUI_BG_RED | BTUI_FG_BLACK) and so forth.)

User Input

BTUI lets you get keyboard input for all keypress events handled by your terminal, including mouse clicking and dragging. Warning: BTUI also hooks in to Ctrl-c, Ctrl-d, Ctrl-z, and other keyboard events that normally have very specific behavior in terminal programs. If you want that specific behavior, then you'll have to implement it manually. The upside is that you're able to handle it gracefully and do whatever cleanup you want. If you want to provide Ctrl-z suspend functionality, you can use btui_suspend(bt).

Warning: xterm control sequences do not support all key combinations (e.g. Ctrl-9) and some key combinations map to the same control sequences (e.g. Ctrl-m and Enter, or Ctrl-8 and Backspace). Escape in particular is a little bit odd, since it's only recognized as an escape keypress if some amount of time has passed after pressing it with no new bytes being sent. Most of this oddity is completely unavoidable, that's just the how terminals work. Escape key handling can be improved slightly by polling with zero timeout.

Tips and Tricks

• For best performance, try to structure your program to take advantage of terminal scrolling. It's much faster than redrawing every line on the screen.

• Don't assume a string's length (in bytes) is the same as its width on the screen. Unicode characters and terminal escape sequences violate this assumption.

• Don't clear the screen unless you need to. It causes a lot of unnecessary redrawing.

• A good pattern to follow is: draw things from left to right, clearing to the right after each item. Then, once everything has been drawn, clear to the bottom of the screen. If you follow this approach, you won't have to worry too much about the screen width of the things you're writing. Also, the terminal won't flicker, since you're never blanking the whole screen, only part of a line at a time.

• Text wrapping must be done manually, since many terminals do not support wrapping around to any point other than the first column, which is useless for any TUI uses other than text on the far left of the screen.

Language Bindings

BTUI comes with bindings for C, Python, and Lua.

C API

BTUI has the following C function definitions, as well as definitions for some constants, including terminal escape values and keycodes.

int     btui_clear(btui_t *bt, int mode);
void    btui_disable(btui_t *bt);
void    btui_draw_linebox(btui_t *bt, int x, int y, int w, int h);
void    btui_draw_shadow(btui_t *bt, int x, int y, int w, int h);
btui_t* btui_enable(void);
void    btui_fill_box(btui_t *bt, int x, int y, int w, int h);
int     btui_flush(btui_t *bt);
int     btui_getkey(btui_t *bt, int timeout, int *mouse_x, int *mouse_y);
char    *btui_keyname(int key, char *buf);
int     btui_keynamed(const char *name);
int     btui_move_cursor(btui_t *bt, int x, int y);
#define btui_printf(bt, ...) fprintf((bt)->out, __VA_ARGS__)
int     btui_puts(btui_t *bt, const char *s);
int     btui_scroll(btui_t *bt, int firstline, int lastline, int scroll_amount);
int     btui_set_attributes(btui_t *bt, attr_t attrs);
int     btui_set_bg(btui_t *bt, unsigned char r, unsigned char g, unsigned char b);
int     btui_set_bg_hex(btui_t *bt, int hex);
int     btui_set_fg(btui_t *bt, unsigned char r, unsigned char g, unsigned char b);
int     btui_set_fg_hex(btui_t *bt, int hex);
int     btui_suspend(btui_t *bt);

See C/test.c and C/rainbow.c for example usage. You can run make testc to run the C test demo and make rainbow to run the rainbow C demo.

Lua API

The Lua library returns a function that takes one argument: a function that will be called with a BTUI object, which can be used to do TUI actions. Errors will be propagated out of the function, but the terminal will be cleaned up nicely before the error is printed. Here's a simple example program:

require("btui")(function(bt)
    -- Run this code within the TUI, using "bt" as the TUI object
    ...
end)

bt:clear(type="screen") -- Clear the terminal. Options are: "screen", "right", "left", "above", "below", "line"
bt:disable() -- Disables btui
bt:enable() -- Enables btui (if previously disabled)
bt:fillbox(x,y,w,h) -- Fill the given rectangle with space characters
bt:flush() -- Flush the terminal output. Most operations do this anyways.
bt:getkey(timeout=-1) -- Returns a keypress (and optionally, mouse x and y coordinates). The optional timeout argument specifies how long, in tenths of a second, to wait for the next keypress.
bt:height() -- Return the screen height
bt:linebox(x,y,w,h) -- Draw an outlined box around the given rectangle
bt:move(x, y) -- Move the cursor to the given position. (0,0) is the top left corner.
bt:setattributes(attrs...) -- Set the given attributes
bt:shadow(x,y,w,h) -- Draw a shaded shadow to the bottom right of the given rectangle
bt:suspend() -- Suspend the current process and drop back into normal terminal mode
bt:unsetattributes(attrs...) -- Unset the given attributes
bt:width() -- Return the scren width
bt:withattributes(attrs..., fn) -- Set the given attributes, call fn, then unset them
-- R,G,B values are in the range [0.0, 1.0]:
bt:withbg(r,g,b, fn) -- Set the background color to (r,g,b), call fn, then reset the background color to default
bt:withdisabled(fn) -- Calls "fn" with btui disabled, then re-enables btui
bt:withfg(r,g,b, fn) -- Set the foreground color to (r,g,b), call fn, then reset the foreground color to default
bt:write() -- Write text to the terminal

See Lua/test.lua for example usage. Run make lua to build the Lua library, and make testlua to run the Lua BTUI demo.

Python API

The Python library has only one value: open_btui(). This is a context manager, which can be used to safely wrap TUI applications.

import btui

with btui.open_btui() as bt:
    # Your code here...

The returned object has the following methods:

class BTUI:
    @contextmanager
    def attributes(self, *attrs):
    @contextmanager
    def bg(self, r, g, b): # R,G,B values are [0.0, 1.0]
    def clear(self, mode='screen'):
    def disable(self):
    @contextmanager
    def disabled(self):
    def draw_shadow(self, x, y, w, h):
    def enable(self):
    @contextmanager
    def fg(self, r, g, b): # R,G,B values are [0.0, 1.0]
    def fill_box(self, x, y, w, h):
    def flush(self):
    def getkey(self, timeout=None): # returns key, mouse_x, mouse_y
    @property
    def height(self):
    def move(self, x, y):
    def outline_box(self, x, y, w, h):
    def set_attributes(self, *attrs):
    def set_bg(self, r, g, b): # R,G,B values are [0.0, 1.0]
    def set_fg(self, r, g, b): # R,G,B values are [0.0, 1.0]
    def suspend(self):
    def unset_attributes(self, *attrs):
    @property
    def width(self):
    def write(self, *args, sep=''):
    def write_bytes(self, b):

See Python/test.py for example code, which can be run with make testpython.

FAQ

Why not use ncurses? It's already installed almost everywhere!

Ncurses is pretty ubiquitous among amateur TUI developers, however it's a really messy paradigm to work with, and it comes with hundreds of thousands of lines of code bloat. There's also tons of compatibility problems across different versions of ncurses. Using ncurses is a headache, and writing a wrapper around ncurses just adds more bloat on top of a mountain of bloat. So, if you want to write a really nice TUI library for your language of choice, BTUI is a good option for a foundation to build off of. BTUI handles all the low-level C stuff like setting terminal attributes and interrupt handlers, but after that, it mostly just gets out of the way and lets you write the bytes you want, with just a few helper functions that make writing the right bytes easy.

Why not use termbox?

Termbox is an okay library, but its API is built around modifying terminal cells one-at-a-time using function calls. This approach has two major flaws: it's very bad for performance and it makes the API very awkward to use if you want to write strings to the screen. Termbox uses its own custom internal write-buffering to reduce write calls and help performance, but in my experience, there is still noticeable lag when doing large amounts of writes compared to just using plain ol' C fprintf() buffering.

Also, termbox is intended to be used as a system-installed library, but BTUI is much simpler to use: just drop the .h file into your project and #import "btui.h"!

License

BTUI is released under the MIT license. See LICENSE for details.