NAME

Termbox - Create Text-based User Interfaces Without ncurses

SYNOPSIS

        use Termbox qw[:all];
        my @chars = split //, 'hello, world!';
        my $code  = tb_init();
        die sprintf "termbox init failed, code: %d\n", $code if $code;
        tb_select_input_mode(TB_INPUT_ESC);
        tb_select_output_mode(TB_OUTPUT_NORMAL);
        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 $colors (0 .. $#rows) {
                my $j = 0;
                for my $char (@chars) {
                        tb_change_cell($j, $colors, ord $char, @{ $rows[$colors] });
                        $j++;
                }
        }
        tb_present();
        while (1) {
                my $ev = Termbox::Event->new();
                tb_poll_event($ev);
                if ($ev->key == TB_KEY_ESC) {
                        tb_shutdown();
                        exit 0;
                }
        }

DESCRIPTION

Termbox is a library that provides minimalistic API which allows the programmer to write text-based user interfaces. The library is crossplatform and has both terminal-based implementations on *nix operating systems and a winapi console based implementation for windows operating systems. The basic idea is an abstraction of the greatest common subset of features available on all major terminals and other terminal-like APIs in a minimalistic fashion. Small API means it is easy to implement, test, maintain and learn it, that's what makes the termbox a distinct library in its area.

Note

This is a first draft to get my feet wet with FFI::Platypus. It'll likely be prone to tipping over. For now, libtermbox is built by this package during installation but that'll change when I wrap my mind around Alien::Base, et. al.

This module's API will likely change to be more Perl and less C.

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 termbox 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 termbox library on the file name provided.

tb_init_fd( $fileno )

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

tb_shutdown( )

Causes the termbox 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 characters).

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 characters).

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_clear( )

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

tb_set_clear_attributes( $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.

tb_set_cursor( $x, $y )

Sets the position of the cursor. Upper-left character is (0, 0). If you pass TB_HIDE_CURSOR as both coordinates, then the cursor will be hidden. Cursor is hidden by default.

tb_put_cell( $x, $y, $cell )

Changes cell's parameters in the internal back buffer at the specified position.

tb_change_cell( $x, $y, $char, $fg, $bg)

Changes cell's parameters in the internal back buffer at the specified position, with the specified character, and with the specified foreground and background colors.

tb_cell_buffer( )

Returns a Termbox::Cell object containing a pointer to internal cell back buffer. You can get its dimensions using tb_width( ) and tb_height( ) methods. The pointer stays valid as long as no tb_clear( ) and tb_present( ) calls are made. The buffer is one-dimensional buffer containing lines of cells starting from the top.

tb_select_input_mode( $mode )

Sets the termbox input mode. Termbox has two input modes:

1. Esc input mode.

When ESC sequence is in the buffer and it doesn't match any known ESC sequence where ESC means TB_KEY_ESC.

2. Alt input mode.

When ESC sequence is in the buffer and it doesn't match any known sequence ESC enables TB_MOD_ALT modifier for the next keyboard event.

You can also apply TB_INPUT_MOUSE via bitwise OR operation to either of the modes (e.g. TB_INPUT_ESC | TB_INPUT_MOUSE). 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, it returns the current input mode.

Default termbox input mode is TB_INPUT_ESC.

tb_select_output_mode( $mode )

Sets the termbox output mode. Termbox has three output options:

1. TB_OUTPUT_NORMAL - 1 .. 8

This mode provides 8 different colors: black, red, green, yellow, blue, magenta, cyan, white

Shortcut: TB_BLACK, TB_RED, etc.

Attributes: TB_BOLD, TB_UNDERLINE, TB_REVERSE

Example usage:

        tb_change_cell(x, y, '@', TB_BLACK | TB_BOLD, TB_RED);
2. TB_OUTPUT_256 - 0 .. 256

In this mode you can leverage the 256 terminal mode:

        0x00 - 0x07: the 8 colors as in TB_OUTPUT_NORMAL
        0x08 - 0x0f: TB_* | TB_BOLD
        0x10 - 0xe7: 216 different colors
        0xe8 - 0xff: 24 different shades of grey

Example usage:

        tb_change_cell(x, y, '@', 184, 240);
        tb_change_cell(x, y, '@', 0xb8, 0xf0);
3. TB_OUTPUT_216 - 0 .. 216

This mode supports the 3rd range of the 256 mode only. But you don't need to provide an offset.

4. TB_OUTPUT_GRAYSCALE - 0 .. 23

This mode supports the 4th range of the 256 mode only. But you dont need to provide an offset.

If 'mode' is TB_OUTPUT_CURRENT, it returns the current output mode.

Default termbox output mode is TB_OUTPUT_NORMAL.

tb_peek_event( $event, $timeout )

Wait for an event up to 'timeout' milliseconds and fill the 'event' object with it, when the event is available. Returns the type of the event (one of TB_EVENT_* constants) or -1 if there was an error or 0 in case there were no event during 'timeout' period.

Current usage:

        my $ev = Termbox::Event->new( );
        tb_peek_event( $evl, 1 ); # $ev is filled by the API; yes, this will change before v1.0

tb_poll_event( $event )

Wait for an event forever and fill the 'event' object with it, when the event is available. Returns the type of the event (one of TB_EVENT_* constants) or -1 if there was an error.

Current usage:

        my $ev = Termbox::Event->new( );
        tb_peek_event( $evl, 1 ); # $ev is filled by the API; yes, this will change before v1.0

Constants

TODO: These aren't fleshed out yet, I'm thinking of grabbing them from the C side of FFI::Platypus.

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.

TODO: For now, please see https://github.com/nsf/termbox/blob/master/src/termbox.h for the list

:modifier

Modifier constants. See Termbox::Event's mod( ) method and the tb_select_input_mode( ) function.

TB_MOD_ALT - Alt key modifier.
TB_MOD_MOTION - Mouse motion modifier

:color

See Termbox::Cell's fg( ) and bg( ) values.

TB_DEFAULT
TB_BLACK
TB_RED
TB_GREEN
TB_YELLOW
TB_BLUE
TB_MAGENTA
TB_CYAN
TB_WHITE

:font

Attributes, it is possible to use multiple attributes by combining them using bitwise OR (|). Although, colors cannot be combined. But you can combine attributes and a single color. See also Termbox::Cell's fg( ) and bg( ) methods.

TB_BOLD
TB_UNDERLINE
TB_REVERSE

:event

TB_EVENT_KEY
TB_EVENT_RESIZE
TB_EVENT_MOUSE

:error

Error codes returned by tb_init( ). A claim is made that all of them are self-explanatory except the pipe trap error. Termbox uses unix pipes in order to deliver a message from a signal handler (SIGWINCH) to the main event reading loop. Honestly in most cases you should just check the returned code as << 0>.

TB_EUNSUPPORTED_TERMINAL
TB_EFAILED_TO_OPEN_TTY
TB_EPIPE_TRAP_ERROR

:cursor

TB_HIDE_CURSOR - Pass this to tb_set_cursor( $x, $y ) to hide the cursor

:input

Pass one of these to tb_select_input_mode( $mode ):

TB_INPUT_CURRENT
TB_INPUT_ESC
TB_INPUT_ALT
TB_INPUT_MOUSE

:output

Pass one of these to tb_select_output_mode( $mode ):

TB_OUTPUT_CURRENT
TB_OUTPUT_NORMAL
TB_OUTPUT_256
TB_OUTPUT_216
TB_OUTPUT_GRAYSCALE

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

Copyright (C) 2020 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.

When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.