EXPORTS
Nothing per default, but can export the following per request:
:all
:api
tb_init
tb_shutdown
tb_width
tb_height
tb_clear
tb_present
tb_invalidate
tb_set_cursor
tb_hide_cursor
tb_set_cell
tb_set_input_mode
tb_set_output_mode
tb_peek_event
tb_poll_event
tb_print
tb_printf
tb_utf8_char_length
tb_utf8_char_to_unicode
tb_utf8_unicode_to_char
tb_last_errno
tb_strerror
tb_cell_buffer
tb_version
:const
TB_VERSION_STR
:keys
TB_KEY_CTRL_TILDE
TB_KEY_CTRL_2
TB_KEY_CTRL_A
TB_KEY_CTRL_B
TB_KEY_CTRL_C
TB_KEY_CTRL_D
TB_KEY_CTRL_E
TB_KEY_CTRL_F
TB_KEY_CTRL_G
TB_KEY_BACKSPACE
TB_KEY_CTRL_H
TB_KEY_TAB
TB_KEY_CTRL_I
TB_KEY_CTRL_J
TB_KEY_CTRL_K
TB_KEY_CTRL_L
TB_KEY_ENTER
TB_KEY_CTRL_M
TB_KEY_CTRL_N
TB_KEY_CTRL_O
TB_KEY_CTRL_P
TB_KEY_CTRL_Q
TB_KEY_CTRL_R
TB_KEY_CTRL_S
TB_KEY_CTRL_T
TB_KEY_CTRL_U
TB_KEY_CTRL_V
TB_KEY_CTRL_W
TB_KEY_CTRL_X
TB_KEY_CTRL_Y
TB_KEY_CTRL_Z
TB_KEY_ESC
TB_KEY_CTRL_LSQ_BRACKET
TB_KEY_CTRL_3
TB_KEY_CTRL_4
TB_KEY_CTRL_BACKSLASH
TB_KEY_CTRL_5
TB_KEY_CTRL_RSQ_BRACKET
TB_KEY_CTRL_6
TB_KEY_CTRL_7
TB_KEY_CTRL_SLASH
TB_KEY_CTRL_UNDERSCORE
TB_KEY_SPACE
TB_KEY_BACKSPACE2
TB_KEY_CTRL_8
TB_KEY_F1
TB_KEY_F2
TB_KEY_F3
TB_KEY_F4
TB_KEY_F5
TB_KEY_F6
TB_KEY_F7
TB_KEY_F8
TB_KEY_F9
TB_KEY_F10
TB_KEY_F11
TB_KEY_F12
TB_KEY_INSERT
TB_KEY_DELETE
TB_KEY_HOME
TB_KEY_END
TB_KEY_PGUP
TB_KEY_PGDN
TB_KEY_ARROW_UP
TB_KEY_ARROW_DOWN
TB_KEY_ARROW_LEFT
TB_KEY_ARROW_RIGHT
TB_KEY_BACK_TAB
TB_KEY_MOUSE_LEFT
TB_KEY_MOUSE_RIGHT
TB_KEY_MOUSE_MIDDLE
TB_KEY_MOUSE_RELEASE
TB_KEY_MOUSE_WHEEL_UP
TB_KEY_MOUSE_WHEEL_DOWN
:color
TB_DEFAULT
TB_BLACK
TB_RED
TB_GREEN
TB_YELLOW
TB_BLUE
TB_MAGENTA
TB_CYAN
TB_WHITE
:attr
TB_BOLD
TB_UNDERLINE
TB_REVERSE
TB_ITALIC
TB_BLINK
TB_DIM
TB_INVISIBLE
:event
TB_EVENT_KEY
TB_EVENT_RESIZE
TB_EVENT_MOUSE
:mode
TB_MOD_ALT
TB_MOD_MOTION
:input
TB_INPUT_CURRENT
TB_INPUT_ESC
TB_INPUT_ALT
TB_INPUT_MOUSE
:output
TB_OUTPUT_CURRENT
TB_OUTPUT_NORMAL
TB_OUTPUT_256
TB_OUTPUT_216
TB_OUTPUT_GRAYSCALE
TB_OUTPUT_TRUECOLOR
:types
tb_cells
tb_event
:return
TB_OK
TB_ERR
TB_ERR_NEED_MORE
TB_ERR_INIT_ALREADY
TB_ERR_INIT_OPEN
TB_ERR_MEM
TB_ERR_NO_EVENT
TB_ERR_NO_TERM
TB_ERR_NOT_INIT
TB_ERR_OUT_OF_BOUNDS
TB_ERR_READ
TB_ERR_RESIZE_IOCTL
TB_ERR_RESIZE_PIPE
TB_ERR_RESIZE_SIGACTION
TB_ERR_POLL
TB_ERR_TCGETATTR
TB_ERR_TCSETATTR
TB_ERR_UNSUPPORTED_TERM
TB_ERR_RESIZE_WRITE
TB_ERR_RESIZE_POLL
TB_ERR_RESIZE_READ
TB_ERR_RESIZE_SSCANF
TB_ERR_CAP_COLLISION
TB_ERR_SELECT
TB_ERR_RESIZE_SELECTsub Termbox::Cell::new { # $cell ($class, \%cell) my $class = _CLASSISA(shift, 'Termbox::Cell') // croak ''.($! = EINVAL); my $args = !@_ ? {} : _HASH(shift) // croak ''.($! = EINVAL); !@_ or croak ''.($! = E2BIG);
my $self = {
ch => 0,
fg => 0,
bg => 0,
};
if ($args) {
# croak ''.($! = EINVAL) if !all { exists $args->{$_} } keys %$self;
croak ''.($! = EINVAL) if !all { exists $self->{$_} } keys %$args;
croak ''.($! = EINVAL) if !all { defined _NONNEGINT($_) } values %$args;
map { $self->{$_} = $args->{$_} } keys %$args;
}
return bless $self, $class;
}BEGIN { no strict 'refs'; foreach my $name (qw{ch fg bg}) { *{"Termbox::Cell::$name"} = sub { my $self = _INSTANCE(shift, 'Termbox::Cell') // croak ''.($! = EINVAL); my $attr = !@_ ? undef : _NONNEGINT(shift) // croak ''.($! = EINVAL); !@_ or croak ''.($! = E2BIG); $self->{$name} = $attr if defined $attr; return $self->{$name}; } } }
sub Termbox::Event::new { # $event ($class, \%event) my $class = _CLASSISA(shift, 'Termbox::Event') // croak ''.($! = EINVAL); my $args = !@_ ? {} : _HASH(shift) // croak ''.($! = EINVAL); !@_ || croak ''.($! = E2BIG);
my $self = {
type => 0,
mod => 0,
key => 0,
ch => 0,
w => 0,
h => 0,
x => 0,
y => 0,
};
if ($args) {
# croak ''.($! = EINVAL) if !all { exists $args->{$_} } keys %$self;
croak ''.($! = EINVAL) if !all { exists $self->{$_} } keys %$args;
croak ''.($! = EINVAL) if !all { defined _NONNEGINT($_) } values %$args;
map { $self->{$_} = $args->{$_} } keys %$args;
}
return bless $self, $class;
}BEGIN { no strict 'refs'; foreach my $name (qw{type mod key ch w h x y}) { *{"Termbox::Event::$name"} = sub { my $self = _INSTANCE(shift, 'Termbox::Event') // croak ''.($! = EINVAL); my $attr = !@_ ? undef : _NONNEGINT(shift) // croak ''.($! = EINVAL); !@_ or croak ''.($! = E2BIG); $self->{$name} = $attr if defined $attr; return $self->{$name}; } } }
NAME
Termbox::Go::Legacy - Legacy Termbox Interface implementation
DESCRIPTION
Legacy Interface of Termbox based on termbox2 v2.5.0-dev, 9. Feb 2024.
COPYRIGHT AND LICENCE
This file is part of the port of Termbox.
Copyright (C) 2012 by termbox-go authors
2010-2020 nsf <no.smile.face@gmail.com>
2015-2024,2025 Adam Saponara <as@php.net>
The content of the library was taken from termbox-go and the interface was
taken from the termbox2 implementation of Termbox, which is licensed under
the MIT license.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.AUTHORS
2024,2025 by J. Schneider https://github.com/brickpool/
DISCLAIMER OF WARRANTIES
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.REQUIRES
SEE ALSO
SUBROUTINES
TB_VERSION_STR
TB_VERSION_STR();use constant TB_VERSION_STR => $version->normal;
Termbox::Cell::new
my $cell = Termbox::Cell::new($class, \%cell);Termbox::Event::new
my $event = Termbox::Event::new($class, \%event);back::cells::FETCH
my $cell = back::cells::FETCH($self, $index);This method is always executed when a single element of the back buffer is to be accessed. A (newly created) "tb_cell" object selected via index is returned. Equivalent to termbox::CellBuffer()->[$index].
back::cells::FETCHSIZE
my $size = back::cells::FETCHSIZE();This method returns the total number of elements in the array connected to the back buffer. Equivalent to scalar(@{ termbox::CellBuffer() }).
back::cells::TIEARRAY
my $object = back::cells::TIEARRAY($class);Constructor for the derived class Tie::Array. It will return a blessed variable that emulates the "tb_cell" array from the back buffer.
tb_cell
my \%hashref = tb_cell( | \%hashref | @array);The terminal screen is represented as 2d array of cells.The structure is optimized for dealing with single-width Unicode codepoints.
tb_cell {
ch => Int, # a Unicode codepoint
fg => Int, # bitwise foreground attributes
bg => Int, # bitwise background attributes
};tb_cell_buffer
my \@arrayref = tb_cell_buffer();Library utility function: returns a slice into the termbox's back buffer
tb_clear
my $result = tb_clear();Clears the internal back buffer using TB_DEFAULT color.
tb_event
my \%hashref = tb_event( | \%hashref | @array);An incoming event from the console/tty.
Given the event type, the following fields are relevant:
when TB_EVENT_KEY: (key XOR ch, one will be zero), mod. Note there is
overlap between TB_MOD_CTRL and TB_KEY_CTRL_*.
TB_MOD_CTRL and TB_MOD_SHIFT are only set as
modifiers to TB_KEY_ARROW_*.
when TB_EVENT_RESIZE: w, h
when TB_EVENT_MOUSE: key (TB_KEY_MOUSE_*), x, ytb_height
my $columns = tb_height();Returns the height 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. Both dimensions have an unspecified negative value when called before "tb_init" or after "tb_shutdown".
tb_hide_cursor
my $result = tb_hide_cursor();The shortcut for tb_set_cursor(-1, -1).
tb_init
my $result = tb_init();Initializes the termbox library. This function should be called before any other functions.
tb_invalidate
my $result = 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_last_errno
my $errno = tb_last_errno();Library utility function: returns the last error code
tb_peek_event
my $result = 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 call may be interrupted, yielding a return code of TB_ERR_POLL. In this case, you may check errno via $!. If it's EINTR, you can safely ignore that and call tb_peek_event() again.
tb_poll_event
my $result = tb_poll_event($event);tb_present
my $result = tb_present();Synchronizes the internal back buffer with the terminal by writing to STDOUT.
tb_print
my $result = tb_print($x, $y, $fg, $bg, $str);Print function. For finer control, use "tb_set_cell".
tb_printf
my $result = tb_printf($x, $y, $fg, $bg, $fmt, @array);Printf function. For finer control, use "tb_set_cell".
tb_set_cell
my $result = tb_set_cell($x, $y, $ch, $fg, $bg);Set cell contents in the internal back buffer at the specified position.
tb_set_cursor
my $result = tb_set_cursor($cx, $cy);Sets the position of the cursor. Upper-left character is (0, 0).
tb_set_input_mode
my $result = tb_set_input_mode($mode);Sets the input mode. Termbox has two input modes:
* 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.
* 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
my $result = tb_set_output_mode($mode);Sets the termbox output mode. Termbox has multiple output modes:
1. TB_OUTPUT_NORMAL => [1..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,
TB_DIM
The following style attributes are also available:
TB_INVISIBLE
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. The rest of the attributes apply to fg only and are
ignored as bg attributes.
Example usage:
tb_set_cell(x, y, '@', TB_BLACK | TB_BOLD, TB_RED);
2. TB_OUTPUT_256 => [1..256]
In this mode you get 256 distinct colors (plus default):
0x00 (1): TB_DEFAULT
0x01..0x08 (8): the next 8 colors as in TB_OUTPUT_NORMAL
0x09..0x10 (8): bright versions of the above
0x11..0xe8 (216): 216 different colors
0xe9..0x100 (24): 24 different shades of gray
All TB_* style attributes may be bitwise OR'd as in TB_OUTPUT_NORMAL.
3. TB_OUTPUT_216 => [1..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 => [1..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 grayIf 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. The same advice applies to style attributes.
tb_shutdown
my $result = tb_shutdown();After successful initialization, the library must be finalized using the tb_shutdown() function.
tb_strerror
my $str = tb_strerror($err);Library utility function: get error message
tb_utf8_char_length
my $length = tb_utf8_char_length($c);Returns the byte length of the code point from the UTF-8 character (1-6)
tb_utf8_char_to_unicode
my $length = tb_utf8_char_to_unicode(\$out, $c);Convert UTF-8 one unicode character string to UTF-32 codepoint.
If $c is an empty string, return 0. $out is left unchanged.
If an error occurs during the encoding, a negative number is returned. $out is left unchanged.
Otherwise, return byte length of codepoint (1-6).
tb_utf8_unicode_to_char
my $length = tb_utf8_unicode_to_char(\$out, $c);Convert UTF-32 codepoint to UTF-8 string.
$out must be scalar reference. Return byte length of codepoint (1-6).
tb_version
my $str = tb_version();Library utility function: returns the stringified termbox's $version V-String
tb_width
my $rows = tb_width();Returns the width of the internal back buffer (which is the same as terminal's window size in rows).
The internal buffer can be resized after "tb_clear" or "tb_present" function calls. Both dimensions have an unspecified negative value when called before "tb_init" or after "tb_shutdown".