/ 
Termbox-0.10
⭐ Starred 2 / README.md

Build Status MetaCPAN Release

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:

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:

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.

:color

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

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

:event

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

:cursor

:input

Pass one of these to tb_select_input_mode( $mode ):

:output

Pass one of these to tb_select_output_mode( $mode ):

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