/ 
Termbox-PP-v0.4_5
/ Termbox::PP

NAME

Termbox::PP - minimalistic terminal UI library in pure Perl

SYNOPSIS

# Load pure-Perl implementation (provides Termbox.pm)
require Termbox::PP;

# Import API
use Termbox qw(:all);

# Initialize termbox
my $rv = tb_init();
die "Failed to initialize termbox" if $rv != TB_OK;

# Ensure cleanup on exit
END {
  tb_shutdown();
}

# Create event object
my $event = Termbox::Event->new();

# Main loop
while (1) {

  # Clear back buffer
  tb_clear();

  # Draw content
  tb_print(0, 0, TB_WHITE, TB_DEFAULT, "Hello Termbox");
  tb_print(0, 1, TB_CYAN,  TB_DEFAULT, "Press 'q' to quit");

  # Present to screen
  tb_present();

  # Wait for event
  my $rv = tb_poll_event($event);
  last if $rv != TB_OK;

  # Handle key events
  if ($event->type == TB_EVENT_KEY) {

    # Quit on 'q'
    last if $event->ch && chr($event->ch) eq 'q';
  }
}

DESCRIPTION

Termbox::PP is a lightweight, minimalistic library for building text-based user interfaces in Perl.

It provides a small and consistent API for working with terminal output, input events, and screen buffers, focusing on the common functionality shared across modern terminal emulators.

The module offers a simple abstraction layer for:

  • rendering text using a cell-based back buffer

  • handling keyboard, mouse, and resize events

  • working with colors and terminal attributes

Unlike the original C implementation, Termbox::PP is written entirely in pure Perl and does not require XS or external libraries. It depends only on core modules available since Perl 5.10.

Features

  • Portable abstraction

    Provides a consistent API across different terminal environments.

  • Small and simple API

    The limited API surface makes the module easy to learn, use, and maintain.

  • Pure Perl implementation

    No XS dependencies or external libraries required.

Usage Note

The module provides a pure Perl implementation of Termbox by registering itself as Termbox.pm at runtime.

Therefore, it must be loaded before using Termbox:

require Termbox::PP;
use Termbox qw(:all);

Status

This module is a Perl port of termbox2.h and is still relatively new. While it aims to be feature-complete, it should be considered experimental and may evolve based on real-world usage.

API OVERVIEW

require Termbox::PP;
use Termbox qw(:api);

The following list provides an overview of the public API, grouped by functionality:

# Initialize the termbox library
tb_init
tb_init_file
tb_init_fd
tb_init_rwfd
tb_shutdown

# Return the size of the internal back buffer
tb_width
tb_height

# Clear and update the screen
tb_clear
tb_set_clear_attrs
tb_present
tb_invalidate

# Cursor handling
tb_set_cursor
tb_hide_cursor

# Cell operations
tb_set_cell
tb_set_cell_ex
tb_extend_cell
tb_get_cell

# Input and output modes
tb_set_input_mode
tb_set_output_mode

# Event handling
tb_peek_event
tb_poll_event
tb_get_fds

# Printing functions
tb_print
tb_printf
tb_print_ex
tb_printf_ex

# Raw output
tb_send
tb_sendf

# UTF-8 utility functions
tb_utf8_char_length
tb_utf8_char_to_unicode
tb_utf8_unicode_to_char

# Utility functions
tb_last_errno
tb_strerror
tb_has_truecolor
tb_has_egc
tb_attr_width
tb_version
tb_iswprint
tb_wcwidth

# Deprecated
tb_cell_buffer
tb_set_func

PUBLIC API

tb_init

my $rv = tb_init();

Initializes the termbox library using /dev/tty.

This is the most common entry point and should be called before any other API function. Internally, it is equivalent to:

tb_init_file('/dev/tty');

Returns TB_OK on success or a negative error code on failure.

tb_init_file

my $rv = tb_init_file($path);

Initializes the termbox library using the specified tty device path.

Arguments:

  • $path (Str)

    Path to the tty device (e.g. /dev/tty).

Returns TB_OK on success or a negative error code on failure.

tb_init_fd

my $rv = tb_init_fd($ttyfd);

Initializes the termbox library using an existing file descriptor.

Arguments:

  • $ttyfd (Int)

    File descriptor referring to a tty device.

This is a convenience wrapper for tb_init_rwfd($ttyfd, $ttyfd).

Returns TB_OK on success or a negative error code on failure.

tb_init_rwfd

my $rv = tb_init_rwfd($rfd, $wfd);

Initializes the termbox library using separate read and write file descriptors.

Arguments:

  • $rfd (Int)

    File descriptor used for reading input.

  • $wfd (Int)

    File descriptor used for writing output.

This is the most flexible initialization method and is typically used when integrating termbox into custom I/O setups.

Returns TB_OK on success or a negative error code on failure.

tb_shutdown

my $rv = tb_shutdown();

Finalizes the termbox library and restores the terminal state.

This function must be called after successful initialization to ensure that the terminal is returned to its normal mode (cursor visibility, input mode, etc.).

Returns TB_OK on success or TB_ERR_NOT_INIT if termbox was not initialized.

tb_width

my $cols = tb_width();

Returns the width of the internal back buffer in columns (Int).

This value corresponds to the current terminal width. It is updated after initialization and whenever the terminal size changes (e.g. after a resize event).

Returns a negative error code (TB_ERR_NOT_INIT) if the library has not been initialized.

tb_height

my $rows = tb_height();

Returns the height of the internal back buffer in rows (Int).

This value corresponds to the current terminal height. It is updated after initialization and whenever the terminal size changes.

Returns a negative error code (TB_ERR_NOT_INIT) if the library has not been initialized.

tb_clear

my $rv = tb_clear();

Clears the internal back buffer using the currently configured foreground/background clear attributes.

This does not immediately update the terminal. Call tb_present() to flush the changes to the screen.

Returns TB_OK on success or a negative error code on failure.

tb_set_clear_attrs

my $rv = tb_set_clear_attrs($fg, $bg);

Sets the foreground and background attributes used by tb_clear().

Arguments:

  • $fg (PositiveOrZeroInt)

    Foreground color/attribute (bitmask of TB_* constants).

  • $bg (PositiveOrZeroInt)

    Background color/attribute (bitmask of TB_* constants).

Returns TB_OK on success or a negative error code if termbox is not initialized.

tb_present

my $rv = tb_present();

Flushes the internal back buffer to the terminal.

All changes made via functions like tb_set_cell() or tb_print() become visible only after calling this function.

Typically, applications perform rendering in a loop:

tb_clear();
# draw content
tb_present();

Returns TB_OK on success or a negative error code on failure.

tb_invalidate

my $rv = tb_invalidate();

Invalidates the internal front buffer and forces a full redraw on the next tb_present() call.

This is usually not required in normal operation but can be useful after terminal inconsistencies (e.g. external redraws or unsupported escape sequences).

Returns TB_OK on success or a negative error code on failure.

tb_set_cursor

my $rv = tb_set_cursor($cx, $cy);

Sets the position of the cursor.

Arguments:

  • $cx (Int)

    Column position (0-based).

  • $cy (Int)

    Row position (0-based).

The top-left corner of the terminal is (0, 0).

Passing negative values will clamp the cursor to (0, 0).

Returns TB_OK on success or a negative error code if termbox is not initialized.

tb_hide_cursor

my $rv = tb_hide_cursor();

Hides the terminal cursor.

Returns TB_OK on success or a negative error code if termbox is not initialized.

tb_set_cell

my $rv = tb_set_cell($x, $y, $ch, $fg, $bg);

Sets a single cell in the internal back buffer.

Arguments:

  • $x (Int)

    Column position (0-based).

  • $y (Int)

    Row position (0-based).

  • $ch (Str)

    UTF-8 string, only the first character is used.

  • $fg (PositiveOrZeroInt)

    Foreground color/attribute (bitmask of TB_* constants).

  • $bg (PositiveOrZeroInt)

    Background color/attribute (bitmask of TB_* constants).

This is a convenience wrapper around tb_set_cell_ex().

Returns TB_OK on success or a negative error code on failure.

tb_set_cell_ex

my $rv = tb_set_cell_ex($x, $y, $ch, $nch, $fg, $bg);

Sets a cell using one or more characters (extended grapheme cluster).

Arguments:

  • $x, $y (Int)

    Cell position (0-based).

  • $ch (Str)

    UTF-8 string containing one or more characters.

  • $nch (PositiveOrZeroInt)

    Number of codepoints in $ch.

  • $fg, $bg (PositiveOrZeroInt)

    Foreground/background attributes.

This function allows setting extended grapheme clusters when TB_OPT_EGC is enabled.

Returns TB_OK on success or a negative error code on failure.

tb_extend_cell

my $rv = tb_extend_cell($x, $y, $ch);

Appends a single character to an existing cell, extending its grapheme cluster.

This is used to build extended grapheme clusters incrementally.

Arguments:

  • $x, $y (Int)

    Cell position.

  • $ch (Str)

    UTF-8 string containing a single character to append.

This function requires TB_OPT_EGC support.

Returns TB_OK on success or a negative error code on failure.

tb_get_cell

my $rv = tb_get_cell($x, $y, $back, \$cell);

Returns a reference to a cell at the given position.

Arguments:

  • $x, $y (Int)

    Cell position.

  • $back (Bool)

    If true, access the back buffer; otherwise the front buffer.

  • \$cell (Ref)

    Output parameter receiving the cell object reference.

Returns TB_OK on success or a negative error code on failure.

tb_set_input_mode

my $rv = tb_set_input_mode($mode);

Sets the input mode for keyboard and mouse handling.

Arguments:

  • $mode (Int)

    Bitmask of input mode flags.

    Supported flags:

    TB_INPUT_ESC
TB_INPUT_ALT
TB_INPUT_MOUSE

Behavior:

  • TB_INPUT_ESC

    Escape (\x1b) is returned as a standalone key event.

  • TB_INPUT_ALT

    Escape prefixes are interpreted as ALT-modified key events.

  • TB_INPUT_MOUSE

    Enables mouse input events.

Notes:

  • If neither TB_INPUT_ESC nor TB_INPUT_ALT is set, TB_INPUT_ESC is used.

  • If both TB_INPUT_ESC and TB_INPUT_ALT are set, only TB_INPUT_ESC is used.

  • Pass TB_INPUT_CURRENT to query the current mode.

Returns the current mode if TB_INPUT_CURRENT is passed, otherwise TB_OK on success or a negative error code on failure.

tb_set_output_mode

my $rv = tb_set_output_mode($mode);

Sets the rendering output mode (color capabilities).

Arguments:

  • $mode (Int)

    One of:

    TB_OUTPUT_NORMAL
TB_OUTPUT_256
TB_OUTPUT_216
TB_OUTPUT_GRAYSCALE

    Optional (depending on build):

    TB_OUTPUT_TRUECOLOR

Behavior:

  • TB_OUTPUT_NORMAL

    8 basic colors + attributes.

  • TB_OUTPUT_256

    256-color palette.

  • TB_OUTPUT_216

    216-color subset.

  • TB_OUTPUT_GRAYSCALE

    24 grayscale levels.

  • TB_OUTPUT_TRUECOLOR

    24-bit RGB color (if supported).

Notes:

  • Pass TB_OUTPUT_CURRENT to retrieve the current mode.

  • Color interpretation depends on terminal capabilities.

  • Switching modes does not automatically re-render existing cells.

Returns the current mode if TB_OUTPUT_CURRENT is passed, otherwise TB_OK on success or TB_ERR on invalid mode.

tb_peek_event

my $rv = tb_peek_event($event, $timeout_ms);

Waits for an event with a timeout.

Arguments:

  • $event (Object)

    Event object that will be populated.

  • $timeout_ms (Int)

    Timeout in milliseconds.

Returns:

  • TB_OK if an event was received

  • TB_ERR_NO_EVENT if the timeout expired

  • negative error code on failure

tb_poll_event

my $rv = tb_poll_event($event);

Waits indefinitely for the next event.

Arguments:

  • $event (Object)

    Event object that will be populated.

This is equivalent to:

tb_peek_event($event, -1);

Returns TB_OK on success or a negative error code on failure.

tb_get_fds

my $rv = tb_get_fds($ttyfd, $resizefd);

Returns internal file descriptors used by termbox.

Arguments:

  • $ttyfd (ScalarRef)

    Receives the tty file descriptor.

  • $resizefd (ScalarRef)

    Receives the resize event file descriptor.

These descriptors can be used with select(), poll() or similar mechanisms for integrating termbox into custom event loops.

Returns TB_OK on success or TB_ERR_NOT_INIT if termbox is not initialized.

tb_print

my $rv = tb_print($x, $y, $fg, $bg, $str);

Writes a string to the internal back buffer at the given position.

Arguments:

  • $x, $y (Int)

    Starting position (0-based).

  • $fg (PositiveOrZeroInt)

    Foreground color/attribute (bitmask of TB_* constants).

  • $bg (PositiveOrZeroInt)

    Background color/attribute (bitmask of TB_* constants).

  • $str (Str)

    String to render.

This is a convenience wrapper around tb_print_ex().

The text is written into the back buffer and becomes visible only after calling tb_present().

Returns TB_OK on success or a negative error code on failure.

tb_printf

my $rv = tb_printf($x, $y, $fg, $bg, $fmt, @args);

Formatted print function (like sprintf).

Arguments:

  • $fmt (Str)

    Format string.

  • @args

    Arguments for formatting.

This is a convenience wrapper around tb_print_ex().

Returns TB_OK on success or a negative error code on failure.

tb_print_ex

my $rv = tb_print_ex($x, $y, $fg, $bg, \$out_width|undef, $str);

Extended print function with optional width output.

Arguments:

  • $x, $y (Int)

    Starting position.

  • $fg, $bg (PositiveOrZeroInt)

    Foreground/background attributes.

  • \$out_width (ScalarRef or undef)

    Optional output parameter receiving the rendered width.

  • $str (Str)

    String to render.

This function converts the string into Unicode codepoints and writes them into the back buffer.

If $out_width is provided, it will be set to the number of columns used.

Returns TB_OK on success or a negative error code on failure.

tb_printf_ex

my $rv = tb_printf_ex($x, $y, $fg, $bg, \$out_width|undef, $fmt, @args);

Extended formatted print function.

Arguments:

  • $x, $y (Int)

    Starting position.

  • $fg, $bg (PositiveOrZeroInt)

    Foreground/background attributes.

  • \$out_width (ScalarRef or undef)

    Optional output parameter receiving the rendered width.

  • $fmt (Str)

    Format string.

  • @args

    Arguments for formatting.

This function behaves like tb_printf() but allows retrieving the output width via $out_width.

Returns TB_OK on success or a negative error code on failure.

tb_send

my $rv = tb_send($buf, $len);

Sends raw bytes directly to the terminal.

Arguments:

  • $buf (Str)

    Buffer containing raw bytes.

  • $len (PositiveOrZeroInt)

    Number of bytes to send.

This function bypasses the cell buffer and writes directly to the output buffer.

Use with care, as it may interfere with termbox's internal state.

Returns TB_OK on success or a negative error code on failure.

tb_sendf

my $rv = tb_sendf($fmt, @args);

Formatted version of tb_send().

Arguments:

  • $fmt (Str)

    Format string.

  • @args

    Arguments for formatting.

The formatted string is sent directly to the terminal as raw bytes.

The output length must not exceed the internal buffer size (TB_OPT_PRINTF_BUF), otherwise an error is returned.

Returns TB_OK on success or TB_ERR on failure.

tb_utf8_char_length

my $len = tb_utf8_char_length($str);

Returns the byte length of the first UTF-8 character in the given string.

Arguments:

  • $str (Str)

    Input string.

If the string is empty, returns 0.

The result is between 1 and 6 bytes.

Returns 0 on empty input.

tb_utf8_char_to_unicode

my $len = tb_utf8_char_to_unicode(\$out, $str);

Converts a UTF-8 encoded character into a Unicode codepoint.

Arguments:

  • \$out (ScalarRef)

    Output parameter receiving the Unicode codepoint.

  • $str (Str)

    Input string containing at least one UTF-8 character.

Behavior:

  • Returns 0 if the input string is empty.

  • Returns a negative value on decoding error.

  • Otherwise returns the number of bytes consumed.

tb_utf8_unicode_to_char

my $len = tb_utf8_unicode_to_char(\$out, $codepoint);

Converts a Unicode codepoint into a UTF-8 encoded string.

Arguments:

  • \$out (ScalarRef)

    Output parameter receiving the UTF-8 encoded string.

  • $codepoint (PositiveOrZeroInt)

    Unicode codepoint.

Returns the number of bytes written (1-6 bytes).

Supports standard Unicode range as well as extended UTF-8 encoding.

tb_last_errno

my $err = tb_last_errno();

Returns the last error number produced by termbox.

This value can be used together with tb_strerror() to obtain a human-readable error message.

tb_strerror

my $msg = tb_strerror($err);

Returns a string describing the given error code.

Arguments:

  • $err (Int)

    Error code returned by a termbox function.

For system-level errors, the underlying $! value is used.

tb_has_truecolor

my $bool = tb_has_truecolor();

Returns whether truecolor (24-bit color) is supported by the build.

Returns 1 if available, otherwise 0

tb_has_egc

my $bool = tb_has_egc();

Returns whether extended grapheme cluster (EGC) support is enabled.

Returns 1 if enabled, otherwise 0.

tb_attr_width

my $bits = tb_attr_width();

Returns the bit width used for attribute encoding.

Typical values are 16, 32, or 64 depending on build configuration.

tb_iswprint

my $bool = tb_iswprint($codepoint);

Checks whether a Unicode codepoint is printable.

Arguments:

  • $codepoint (PositiveOrZeroInt)

    Unicode codepoint.

Returns a boolean value.

tb_wcwidth

my $width = tb_wcwidth($codepoint);

Returns the display width of a Unicode codepoint.

Arguments:

  • $codepoint (PositiveOrZeroInt)

    Unicode codepoint.

Returns:

  • -1 for non-printable characters

  • 0 for zero-width characters

  • 1 or 2 for printable characters

Width calculation depends on Unicode properties and locale settings.

tb_cell_buffer

my $cells = tb_cell_buffer();

DEPRECATED

Returns a reference to the internal back buffer.

This function is deprecated and may be removed in a future release.

Instead, use:

tb_get_cell()

and related APIs to access cell data.

Returns an array reference of Termbox::Cell objects.

tb_set_func

my $rv = tb_set_func($fn_type, $fn);

DEPRECATED

Sets a custom callback for escape sequence processing.

Arguments:

  • $fn_type (Int)

    One of:

    TB_FUNC_EXTRACT_PRE
TB_FUNC_EXTRACT_POST

  • $fn (CodeRef)

    Callback function.

This function is deprecated and may be removed in a future release.

Returns TB_OK on success or a negative error code on failure.

Termbox::Cell

Represents a single cell in the terminal.

Fields:

  • ch (Int)

    Unicode codepoint.

  • fg (Int)

    Foreground attributes.

  • bg (Int)

    Background attributes.

Extended Grapheme Cluster Methods

The following methods are available when TB_OPT_EGC is enabled:

  • ech (ArrayRef)

    my $aref = $cell->ech();

    Returns an array reference containing the Unicode codepoints of the extended grapheme cluster stored in the cell.

    Returns undef if the cell does not contain a multi-codepoint cluster.

    Example usage:

    my $cell;
tb_get_cell(0, 0, 1, \$cell);

if (my $cluster = $cell->ech()) {
  print "Cluster size: ", scalar(@$cluster), "\n";
}

  • nech (Int)

    my $n = $cell->nech();

    Returns the length of the extended grapheme cluster if it contains more than one codepoint, otherwise returns 0.

  • cech (Int)

    my $count = $cell->cech();

    Returns the number of codepoints in the extended grapheme cluster.

    Returns 0 if no cluster is present.

Constructor

my $cell = Termbox::Cell->new();

Creates a new cell object.

A cell represents a single position in the terminal and contains:

  • character (UTF-8 string / codepoint)

  • foreground attributes

  • background attributes

The returned object can be used internally by termbox functions or retrieved via tb_get_cell().

Returns a new Termbox::Cell instance.

Termbox::Event

Represents an input event from the terminal.

Event objects are populated by tb_peek_event() and tb_poll_event().

Fields:

  • type (Int)

    Event type:

    TB_EVENT_KEY
TB_EVENT_RESIZE
TB_EVENT_MOUSE

  • key (Int)

    Key constant (TB_KEY_*). Used for special keys.

  • ch (Int)

    Unicode codepoint (for character input).

  • mod (Int)

    Modifier flags (bitmask of TB_MOD_*):

    TB_MOD_ALT
TB_MOD_CTRL
TB_MOD_SHIFT

  • w (Int)

    Width of the terminal after resize (only valid for resize events).

  • h (Int)

    Height of the terminal after resize.

  • x (Int)

    Mouse X position (for mouse events).

  • y (Int)

    Mouse Y position (for mouse events).

Constructor

my $event = Termbox::Event->new();

Creates a new event object.

The event structure is used with tb_peek_event() and tb_poll_event() to receive input events.

Depending on the event type, the following fields are populated:

  • type (Int)

    One of:

    TB_EVENT_KEY
TB_EVENT_RESIZE
TB_EVENT_MOUSE

  • key (Int)

    Key constant (TB_KEY_*).

  • ch (Int)

    Unicode codepoint (for character input).

  • mod (Int)

    Modifier flags (TB_MOD_*).

  • w,h (Int)

    New terminal size (resize events).

  • x,y (Int)

    Mouse coordinates.

Returns a new Termbox::Event instance.

COMPILE-TIME OPTIONS

Termbox::PP provides several compile-time options that influence its behavior. These options are typically controlled via environment variables and are evaluated when the module is loaded.

Note: Most applications do not need to modify these settings. The defaults are suitable for typical terminal applications.

STRICT

PERL_STRICT=1 perl your_script.pl

Enables strict argument validation for internal API calls.

If enabled, function arguments are checked more rigorously and invalid input may cause exceptions.

By default, STRICT mode is enabled automatically when one of the following environment variables is set:

PERL_STRICT
EXTENDED_TESTING
AUTHOR_TESTING
RELEASE_TESTING

TB_OPT_EGC

TB_OPT_EGC=0 perl your_script.pl

Controls support for extended grapheme clusters (EGC).

  • Enabled (default)

    Cells may contain multi-codepoint grapheme clusters (e.g. emoji, combining characters).

  • Disabled

    Cells are restricted to a single codepoint.

TB_OPT_PRINTF_BUF

TB_OPT_PRINTF_BUF=8192 perl your_script.pl

Defines the maximum buffer size used by tb_printf() and tb_sendf().

If the formatted output exceeds this size, the operation will fail.

Default: 4096 bytes.

TB_OPT_READ_BUF

TB_OPT_READ_BUF=128 perl your_script.pl

Defines the size of the input buffer used when reading from the terminal.

Increasing this value may improve performance for high-throughput input scenarios.

Default: 64 bytes.

TB_OPT_LIBC_WCHAR

TB_OPT_LIBC_WCHAR=0 perl your_script.pl

Selects the backend used for Unicode width calculations.

  • Enabled (default, if available)

    Uses Unicode::UCD-based width calculation when Unicode::UCD::prop_invmap is available.

  • Disabled

    Uses the bundled fallback implementation.

TB_OPT_ATTR_W

Controls the bit width used for attribute encoding.

Typical values are:

16   (basic attributes)
32   (extended / truecolor)
64   (additional style attributes)

This value is determined automatically based on the configuration and cannot be directly overridden in normal use.

TB_TERMINFO_DIR

TB_TERMINFO_DIR=/custom/path perl your_script.pl

Specifies a custom directory for terminfo database lookup.

If not set, standard system locations are used.

TB_RESIZE_FALLBACK_MS

TB_RESIZE_FALLBACK_MS=500 perl your_script.pl

Defines the timeout (in milliseconds) used for fallback terminal size detection.

Default: 1000 ms.

TB_OPT_TRUECOLOR

DEPRECATED

Legacy option for enabling truecolor support.

This option is retained for backward compatibility and should not be used in new code.

CONSTANTS

The following constants may be imported individually by name or by using one of the export tags.

For example:

use Termbox qw(:keys :color :event :return :func);

Some constants are aliases for the same numeric value. This mirrors the underlying terminal input model where different key names may produce the same byte value.

:keys

Imports key constants used with $tb_event->key.

This includes ASCII control-key constants, printable ASCII key constants, terminal-dependent key constants, and terminfo capability constants.

ASCII key constants

These constants represent ASCII control characters and selected printable ASCII keys.

Several names intentionally share the same value. For example, TB_KEY_CTRL_H and TB_KEY_BACKSPACE both represent 0x08.

TB_KEY_CTRL_TILDE (0x00)

Control-tilde.

TB_KEY_CTRL_2 (0x00)

Alias for TB_KEY_CTRL_TILDE.

TB_KEY_CTRL_A (0x01)

Control-A.

TB_KEY_CTRL_B (0x02)

Control-B.

TB_KEY_CTRL_C (0x03)

Control-C.

TB_KEY_CTRL_D (0x04)

Control-D.

TB_KEY_CTRL_E (0x05)

Control-E.

TB_KEY_CTRL_F (0x06)

Control-F.

TB_KEY_CTRL_G (0x07)

Control-G.

TB_KEY_BACKSPACE (0x08)

Backspace.

TB_KEY_CTRL_H (0x08)

Alias for TB_KEY_BACKSPACE.

TB_KEY_TAB (0x09)

Tab.

TB_KEY_CTRL_I (0x09)

Alias for TB_KEY_TAB.

TB_KEY_CTRL_J (0x0a)

Control-J.

TB_KEY_CTRL_K (0x0b)

Control-K.

TB_KEY_CTRL_L (0x0c)

Control-L.

TB_KEY_ENTER (0x0d)

Enter.

TB_KEY_CTRL_M (0x0d)

Alias for TB_KEY_ENTER.

TB_KEY_CTRL_N (0x0e)

Control-N.

TB_KEY_CTRL_O (0x0f)

Control-O.

TB_KEY_CTRL_P (0x10)

Control-P.

TB_KEY_CTRL_Q (0x11)

Control-Q.

TB_KEY_CTRL_R (0x12)

Control-R.

TB_KEY_CTRL_S (0x13)

Control-S.

TB_KEY_CTRL_T (0x14)

Control-T.

TB_KEY_CTRL_U (0x15)

Control-U.

TB_KEY_CTRL_V (0x16)

Control-V.

TB_KEY_CTRL_W (0x17)

Control-W.

TB_KEY_CTRL_X (0x18)

Control-X.

TB_KEY_CTRL_Y (0x19)

Control-Y.

TB_KEY_CTRL_Z (0x1a)

Control-Z.

TB_KEY_ESC (0x1b)

Escape.

TB_KEY_CTRL_LSQ_BRACKET (0x1b)

Alias for TB_KEY_ESC.

TB_KEY_CTRL_3 (0x1b)

Alias for TB_KEY_ESC.

TB_KEY_CTRL_4 (0x1c)

Control-4.

TB_KEY_CTRL_BACKSLASH (0x1c)

Alias for TB_KEY_CTRL_4.

TB_KEY_CTRL_5 (0x1d)

Control-5.

TB_KEY_CTRL_RSQ_BRACKET (0x1d)

Alias for TB_KEY_CTRL_5.

TB_KEY_CTRL_6 (0x1e)

Control-6.

TB_KEY_CTRL_7 (0x1f)

Control-7.

TB_KEY_CTRL_SLASH (0x1f)

Alias for TB_KEY_CTRL_7.

TB_KEY_CTRL_UNDERSCORE (0x1f)

Alias for TB_KEY_CTRL_7.

TB_KEY_SPACE (0x20)

Space.

TB_KEY_BACKSPACE2 (0x7f)

Alternative Backspace value.

TB_KEY_CTRL_8 (0x7f)

Alias for TB_KEY_BACKSPACE2.

Terminal-dependent key constants

These constants are used with $tb_event->key for keys that are not represented by simple ASCII values.

The numeric values are allocated from the upper end of the 16-bit range.

TB_KEY_F1 .. TB_KEY_F12

Function keys F1 through F12.

TB_KEY_INSERT

Insert key.

TB_KEY_DELETE

Delete key.

TB_KEY_HOME

Home key.

TB_KEY_END

End key.

TB_KEY_PGUP

Page Up key.

TB_KEY_PGDN

Page Down key.

TB_KEY_ARROW_UP

Arrow Up key.

TB_KEY_ARROW_DOWN

Arrow Down key.

TB_KEY_ARROW_LEFT

Arrow Left key.

TB_KEY_ARROW_RIGHT

Arrow Right key.

TB_KEY_BACK_TAB

Back Tab key, usually Shift-Tab.

TB_KEY_MOUSE_LEFT

Left mouse button.

TB_KEY_MOUSE_RIGHT

Right mouse button.

TB_KEY_MOUSE_MIDDLE

Middle mouse button.

TB_KEY_MOUSE_RELEASE

Mouse button release.

TB_KEY_MOUSE_WHEEL_UP

Mouse wheel up.

TB_KEY_MOUSE_WHEEL_DOWN

Mouse wheel down.

Terminfo capability constants

These constants identify terminal capabilities.

They are mostly useful internally or when working directly with lower-level capability handling.

TB_CAP_F1 .. TB_CAP_F12

Capabilities for function keys F1 through F12.

TB_CAP_INSERT

Insert key capability.

TB_CAP_DELETE

Delete key capability.

TB_CAP_HOME

Home key capability.

TB_CAP_END

End key capability.

TB_CAP_PGUP

Page Up key capability.

TB_CAP_PGDN

Page Down key capability.

TB_CAP_ARROW_UP

Arrow Up key capability.

TB_CAP_ARROW_DOWN

Arrow Down key capability.

TB_CAP_ARROW_LEFT

Arrow Left key capability.

TB_CAP_ARROW_RIGHT

Arrow Right key capability.

TB_CAP_BACK_TAB

Back Tab key capability.

TB_CAP__COUNT_KEYS

Number of key capabilities.

TB_CAP_ENTER_CA

Enter cursor addressing mode.

TB_CAP_EXIT_CA

Exit cursor addressing mode.

TB_CAP_SHOW_CURSOR

Show the terminal cursor.

TB_CAP_HIDE_CURSOR

Hide the terminal cursor.

TB_CAP_CLEAR_SCREEN

Clear the screen.

TB_CAP_SGR0

Reset terminal attributes.

TB_CAP_UNDERLINE

Enable underline attribute.

TB_CAP_BOLD

Enable bold attribute.

Enable blink attribute.

TB_CAP_ITALIC

Enable italic attribute.

TB_CAP_REVERSE

Enable reverse-video attribute.

TB_CAP_ENTER_KEYPAD

Enter keypad mode.

TB_CAP_EXIT_KEYPAD

Exit keypad mode.

TB_CAP_DIM

Enable dim attribute.

TB_CAP_INVISIBLE

Enable invisible attribute.

TB_CAP__COUNT

Number of known capabilities.

For the upstream definition see termbox2.h.

:color

Imports foreground and background color constants as well as text attribute constants.

Color constants can be combined with attribute constants using bitwise or.

For example:

my $fg = TB_RED | TB_BOLD;
my $bg = TB_DEFAULT;

Basic colors

TB_DEFAULT

Default terminal color.

TB_BLACK

Black.

TB_RED

Red.

TB_GREEN

Green.

TB_YELLOW

Yellow.

TB_BLUE

Blue.

TB_MAGENTA

Magenta.

TB_CYAN

Cyan.

TB_WHITE

White.

Text attributes

TB_BOLD

Bold text.

TB_UNDERLINE

Underlined text.

TB_REVERSE

Reverse-video text.

TB_ITALIC

Italic text.

Blinking text.

Extended color support

TB_256_BLACK

Base value for 256-color mode.

Truecolor attributes

These constants are only available when truecolor support is enabled.

TB_TRUECOLOR_BOLD

Bold text in truecolor mode.

TB_TRUECOLOR_UNDERLINE

Underlined text in truecolor mode.

TB_TRUECOLOR_REVERSE

Reverse-video text in truecolor mode.

TB_TRUECOLOR_ITALIC

Italic text in truecolor mode.

Blinking text in truecolor mode.

TB_TRUECOLOR_BLACK

Base value for truecolor black.

For the upstream definition see termbox2.h.

:event

Imports event type constants, key modifier constants, input mode constants, and output mode constants.

Event types

These constants are used with tb_event.type.

TB_EVENT_KEY

Keyboard event.

TB_EVENT_RESIZE

Terminal resize event.

TB_EVENT_MOUSE

Mouse event.

Key modifiers

These constants are bit flags used with tb_event.mod.

TB_MOD_ALT

Alt modifier.

TB_MOD_CTRL

Control modifier.

TB_MOD_SHIFT

Shift modifier.

TB_MOD_MOTION

Mouse motion modifier.

Input modes

These constants are used with tb_set_input_mode.

TB_INPUT_CURRENT

Return or keep the current input mode.

TB_INPUT_ESC

Use escape-based input mode.

TB_INPUT_ALT

Use Alt-key input mode.

TB_INPUT_MOUSE

Enable mouse input.

Output modes

These constants are used with tb_set_output_mode.

TB_OUTPUT_CURRENT

Return or keep the current output mode.

TB_OUTPUT_NORMAL

Normal 8-color output mode.

TB_OUTPUT_256

256-color output mode.

TB_OUTPUT_216

216-color output mode.

TB_OUTPUT_GRAYSCALE

Grayscale output mode.

TB_OUTPUT_TRUECOLOR

Truecolor output mode.

This constant is only available when truecolor support is enabled.

For the upstream definition see termbox2.h.

:return

Imports common function return values.

Most Termbox functions return TB_OK on success or a negative TB_ERR_* value on failure unless documented otherwise.

Library behavior is undefined after receiving TB_ERR_MEM. Callers may attempt to recover, calling tb_shutdown, and then calling tb_init again.

Return values

TB_OK

Operation completed successfully.

TB_ERR

Generic error.

TB_ERR_NEED_MORE

More input is required.

TB_ERR_INIT_ALREADY

Termbox has already been initialized.

TB_ERR_INIT_OPEN

Failed to open the terminal.

TB_ERR_MEM

Memory allocation failed.

TB_ERR_NO_EVENT

No event is available.

TB_ERR_NO_TERM

No terminal is available.

TB_ERR_NOT_INIT

Termbox has not been initialized.

TB_ERR_OUT_OF_BOUNDS

Coordinates are outside the valid screen area.

TB_ERR_READ

Read operation failed.

TB_ERR_RESIZE_IOCTL

Resize ioctl operation failed.

TB_ERR_RESIZE_PIPE

Resize pipe operation failed.

TB_ERR_RESIZE_SIGACTION

Resize signal handler setup failed.

TB_ERR_POLL

Poll operation failed.

TB_ERR_TCGETATTR

Failed to read terminal attributes.

TB_ERR_TCSETATTR

Failed to set terminal attributes.

TB_ERR_UNSUPPORTED_TERM

Unsupported terminal.

TB_ERR_RESIZE_WRITE

Resize write operation failed.

TB_ERR_RESIZE_POLL

Resize poll operation failed.

TB_ERR_RESIZE_READ

Resize read operation failed.

TB_ERR_RESIZE_SSCANF

Resize parsing failed.

TB_ERR_CAP_COLLISION

Capability collision detected.

Compatibility aliases

TB_ERR_SELECT

Alias for TB_ERR_POLL.

TB_ERR_RESIZE_SELECT

Alias for TB_ERR_RESIZE_POLL.

For the upstream definition see termbox2.h.

:func

Imports function hook type constants for use with tb_set_func($fn_type, $func).

TB_FUNC_EXTRACT_PRE

Function hook called before extraction.

TB_FUNC_EXTRACT_POST

Function hook called after extraction.

AUTHOR

J. Schneider <http://github.com/brickpool>

COPYRIGHT AND LICENCE

Copyright (C) 2012 by termbox-go authors
              2010-2020 nsf <no.smile.face@gmail.com>
              2015-2024,2025 Adam Saponara <as@php.net>
              2024-2026 J. Schneider <http://github.com/brickpool>

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.

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

5.010.

SEE ALSO

Termbox

termbox2.h