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

`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

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/.

To install Termbox, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Termbox

CPAN shell

perl -MCPAN -e shell
install Termbox

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Note

Functions

tb_init( )

tb_init_file( $name )

tb_init_fd( $fileno )

tb_shutdown( )

tb_width( )

tb_height( )

tb_clear( )

tb_set_clear_attributes( $fg, $bg )

tb_present( )

tb_set_cursor( $x, $y )

tb_put_cell( $x, $y, $cell )

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

tb_cell_buffer( )

tb_select_input_mode( $mode )

tb_select_output_mode( $mode )

tb_peek_event( $event, $timeout )

tb_poll_event( $event )