NAME

Termbox - Create Text-based User Interfaces Without ncurses

SYNOPSIS

    use Termbox 2 qw[:all];
    #
    my @chars = split //, 'hello, world!';
    my $code  = tb_init();
    tb_clear();
    my @rows = (
        [ TB_WHITE,   TB_BLACK ],
        [ TB_BLACK,   TB_DEFAULT ],
        [ TB_RED,     TB_GREEN ],
        [ TB_GREEN,   TB_RED ],
        [ TB_YELLOW,  TB_BLUE ],
        [ TB_MAGENTA, TB_CYAN ]
    );
    for my $row ( 0 .. $#rows ) {
        for my $col ( 0 .. $#chars ) {
            tb_set_cell( $col, $row, $chars[$col], @{ $rows[$row] } );
        }
    }
    tb_present();
    sleep 3;
    tb_shutdown();

DESCRIPTION

Termbox 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

Note

This module wraps libtermbox2, an incompatible fork of the now abandoned libtermbox. I'm not sure why you would but if you're looking for the original, try any version of Termbox.pm before 2.0.

Functions

Termbox's API is very small. You can build most UIs with just a few functions. Import them by name or with :all.

`tb_init( )`

Initializes the termbox2 library. This function should be called before any other functions. Calling this is the same as tb_init_file('/dev/tty'). After successful initialization, the library must be finalized using the tb_shutdown( ) function.

If this returns anything other than 0, it didn't work.

`tb_init_file( $name )`

This function will init the termbox2 library on the file name provided.

`tb_init_fd( $fileno )`

This function will init the termbox2 library on the provided filehandle. This is untested.

`tb_init_rwfd( $rfileno, $wfileno )`

This function will init the termbox2 library on the provided filehandles. This is untested.

`tb_shutdown( )`

Causes the termbox2 library to attempt to clean up after itself.

`tb_width( )`

Returns the horizontal size of the internal back buffer (which is the same as terminal's window size in columns).

The internal buffer can be resized after tb_clear( ) or tb_present( ) function calls. This function returns an unspecified negative value when called before tb_init( ) or after tb_shutdown( ).

`tb_height( )`

Returns the vertical size of the internal back buffer (which is the same as terminal's window size in rows).

`tb_clear( )`

Clears the internal back buffer using TB_DEFAULT color or the color/attributes set by tb_set_clear_attrs( ) function.

`tb_set_clear_attrs( $fg, $bg )`

Overrides the use of TB_DEFAULT to clear the internal back buffer when tb_clear( ) is called.

`tb_present( )`

Synchronizes the internal back buffer with the terminal by writing to tty.

`tb_invalidate( )`

Clears the internal front buffer effectively forcing a complete re-render of the back buffer to the tty. It is not necessary to call this under normal circumstances.

`tb_set_cursor( $x, $y )`

Sets the position of the cursor. Upper-left character is (0, 0).

`tb_hide_cursor( )`

Hides the cursor.

`tb_set_cell( $x, $y, $ch, $fg, $bg )`

Set cell contents in the internal back buffer at the specified position.

Function tb_set_cell($x, $y, $ch, $fg, $bg)is equivalent to tb_set_cell_ex($x, $y, $ch, 1, $fg, $bg).

`tb_set_cell_ex( $x, $y, $ch, $nch, $fg, $bg )`

Set cell contents in the internal back buffer at the specified position. Use this function for rendering grapheme clusters (e.g., combining diacritical marks).

`tb_extend_cell( $x, $y, $ch )`

Shortcut to append 1 code point to the given cell.

`tb_set_input_mode( $mode )`

Sets the input mode. Termbox has two input modes:

1. TB_INPUT_ESC: When escape (\x1b) is in the buffer and there's no match for an escape sequence, a key event for TB_KEY_ESC is returned.
2. TB_INPUT_ALT: When escape (\x1b) is in the buffer and there's no match for an escape sequence, the next keyboard event is returned with a TB_MOD_ALT modifier.

You can also apply TB_INPUT_MOUSE via bitwise OR operation to either of the modes (e.g., TB_INPUT_ESC | TB_INPUT_MOUSE) to receive TB_EVENT_MOUSE events. If none of the main two modes were set, but the mouse mode was, TB_INPUT_ESC mode is used. If for some reason you've decided to use (TB_INPUT_ESC | TB_INPUT_ALT) combination, it will behave as if only TB_INPUT_ESC was selected.

If mode is TB_INPUT_CURRENT, the function returns the current input mode.

The default input mode is TB_INPUT_ESC.

`tb_set_output_mode( $mode )`

Sets the termbox2 output mode. Termbox has multiple output modes:

1. TB_OUTPUT_NORMAL => [0..8]

This mode provides 8 different colors: TB_BLACK, TB_RED, TB_GREEN, TB_YELLOW, TB_BLUE, TB_MAGENTA, TB_CYAN, TB_WHITE

Plus TB_DEFAULT which skips sending a color code (i.e., uses the terminal's default color).

Colors (including TB_DEFAULT) may be bitwise OR'd with attributes: TB_BOLD, TB_UNDERLINE, TB_REVERSE, TB_ITALIC, TB_BLINK

As in all modes, the value 0 is interpreted as TB_DEFAULT for convenience.

Some notes: TB_REVERSE can be applied as either fg or bg attributes for the same effect. TB_BOLD, TB_UNDERLINE, TB_ITALIC, TB_BLINK apply as fg attributes only, and are ignored as bg attributes.

Example usage:

    tb_set_cell($x, $y, '@', TB_BLACK | TB_BOLD, TB_RED);

2. TB_OUTPUT_256 => [0..255] + TB_256_BLACK

In this mode you get 256 distinct colors (plus default):

                0x00   (1): TB_DEFAULT
        TB_256_BLACK   (1): TB_BLACK in TB_OUTPUT_NORMAL
          0x01..0x07   (7): the next 7 colors as in TB_OUTPUT_NORMAL
          0x08..0x0f   (8): bright versions of the above
          0x10..0xe7 (216): 216 different colors
          0xe8..0xff  (24): 24 different shades of gray

Attributes may be bitwise OR'd as in TB_OUTPUT_NORMAL.

Note TB_256_BLACK must be used for black, as 0x00 represents default.

3. TB_OUTPUT_216 => [0..216]

This mode supports the 216-color range of TB_OUTPUT_256 only, but you don't need to provide an offset:

                0x00   (1): TB_DEFAULT
          0x01..0xd8 (216): 216 different colors

4. TB_OUTPUT_GRAYSCALE => [0..24]

This mode supports the 24-color range of TB_OUTPUT_256 only, but you don't need to provide an offset:

                0x00   (1): TB_DEFAULT
          0x01..0x18  (24): 24 different shades of gray

5. TB_OUTPUT_TRUECOLOR => [0x000000..0xffffff] + TB_TRUECOLOR_BLACK

This mode provides 24-bit color on supported terminals. The format is 0xRRGGBB. Colors may be bitwise OR'd with TB_TRUECOLOR_* attributes.

Note TB_TRUECOLOR_BLACK must be used for black, as 0x000000 represents default.

If mode is TB_OUTPUT_CURRENT, the function returns the current output mode.

The default output mode is TB_OUTPUT_NORMAL.

To use the terminal default color (i.e., to not send an escape code), pass TB_DEFAULT. For convenience, the value 0 is interpreted as TB_DEFAULT in all modes.

Note, cell attributes persist after switching output modes. Any translation between, for example, TB_OUTPUT_NORMAL's TB_RED and TB_OUTPUT_TRUECOLOR's 0xff0000 must be performed by the caller. Also note that cells previously rendered in one mode may persist unchanged until the front buffer is cleared (such as after a resize event) at which point it will be re-interpreted and flushed according to the current mode. Callers may invoke tb_invalidate( ) if it is desirable to immediately re-interpret and flush the entire screen according to the current mode.

Note, not all terminals support all output modes, especially beyond TB_OUTPUT_NORMAL. There is also no very reliable way to determine color support dynamically. If portability is desired, callers are recommended to use TB_OUTPUT_NORMAL or make output mode end-user configurable.

`tb_peek_event( $event, $timeout_ms )`

Wait for an event up to $timeout_ms milliseconds and fill the $event structure with it. If no event is available within the timeout period, TB_ERR_NO_EVENT is returned. On a resize event, the underlying select(2) call may be interrupted, yielding a return code of TB_ERR_POLL. In this case, you may check errno via tb_last_errno( ). If it's EINTR, you can safely ignore that and call tb_peek_event( ) again.

`tb_poll_event( $event )`

Same as tb_peek_event( $event, $timeout_ms ) except no timeout.

`tb_get_fds( \$ttyfd, \$resizefd )`

Internal termbox2 FDs that can be used with poll() / select(). Must call tb_poll_event( $event ) / tb_peek_event( $event, $timeout_ms ) if activity is detected.

`tb_print( $x, $y, $fg, $bg, $str )`

It prints text.

`tb_send( $buf, $nbuf )`

Send raw bytes to terminal.

`tb_set_func( $fn_type, $fn )`

Set custom functions. $fn_type is one of TB_FUNC_* constants, fn is a compatible function pointer, or undef to clear.

TB_FUNC_EXTRACT_PRE: If specified, invoke this function BEFORE termbox2 tries to extract any escape sequences from the input buffer.
TB_FUNC_EXTRACT_POST: If specified, invoke this function AFTER termbox2 tries (and fails) to extract any escape sequences from the input buffer.

`tb_utf8_char_length( $c )`

Returns the length of a utf8 encoded character.

`tb_utf8_char_to_unicode( \$out, $c )`

Converts a utf8 encoded character to Unicode.

`tb_utf8_unicode_to_char( \$out, $c )`

Converts a Unicode character to utf8.

`tb_last_errno( )`

Returns the last errno.

`tb_strerror( $err )`

Returns a string describing the given error.

`tb_cell_buffer( )`

Returns the current cell buffer.

`tb_has_truecolor( )`

Returns a true value if truecolor values are supported.

`tb_has_egc( )`

Returns a true value if Unicode's extended grapheme clusters are supported.

Ctb_version( )>

Returns the version string of the wrapped libtermbox2.

Constants

You may import these by name or with the following tags:

`:keys`

These are a safe subset of terminfo keys which exist on all popular terminals. Termbox only uses them to stay truly portable. See also Termbox::Event's key( ) method.