/ 
Term-Fabulous-0.01
/ Term::Fabulous::Role::Terminal

NAME

Term::Fabulous::Role::Terminal - What Term::Fabulous needs from a terminal

SYNOPSIS

use Object::Pad 0.825;
use Term::Fabulous::Role::Terminal;

class My::Terminal :does(Term::Fabulous::Role::Terminal) {
	method open (%options)           { ... }
	method close ()                  { ... }
	method is_open ()                { ... }
	method size ()                   { ... }    # ( $columns, $rows )
	method apply_resize ( $w, $h )   { ... }    # ( $columns, $rows )
	method read_handles ()           { ... }
	method next_event ()             { ... }    # a Term::Fabulous::Termbox::Event or undef
	method input_ended ()            { ... }
	method kitty_keyboard_active ()  { ... }
	method cell_target ()            { ... }
}

my $ui = Term::Fabulous->new( root => $root, width => 80, height => 24, terminal => My::Terminal->new );

DESCRIPTION

Most programs never use this module directly. Term::Fabulous talks to the terminal only through an object that composes this role, its terminal. Two terminals come with the distribution:

Term::Fabulous::Terminal::Termbox

The real terminal, through termbox2. The default.

Term::Fabulous::Terminal::Memory

A terminal in memory, for tests: the test queues keys, clicks and resizes, drives the application with "step" in Term::Fabulous and reads back what the screen shows.

Term::Fabulous keeps everything that is not about the terminal itself: the IO::Async loop, its timers and signals, the routing of keys and the mouse to the widgets, focus, wheel scrolling and frame pacing. A terminal only opens and closes the session, reports input and receives the painted cells.

REQUIRED METHODS

A class composing the role provides all of the following. Errors are reported by dying with a message that starts with the class name.

open

$terminal->open( inline => undef, mouse => 1, kitty_keyboard => 1 );

Starts a session. inline is undef for the full screen, or the number of rows of a region below the shell's output (see "INLINE MODE" in Term::Fabulous). mouse says whether the terminal reports the mouse, including motion with no button held. kitty_keyboard says whether to ask the terminal for the kitty keyboard protocol, and to switch it on if the terminal speaks it. Term::Fabulous always passes all three. Dies when the session cannot start; the terminal is then left as it was. Dies when it is open already.

close

$terminal->close;

Ends the session and gives the terminal back as it was: the modes "open" switched on are off again, an inline region's last frame stays on the screen with the cursor below it. Does nothing when no session is open.

is_open

1 between "open" and "close", otherwise 0.

size

my ( $columns, $rows ) = $terminal->size;

The size of the layout, in cells, while the session is open: the terminal's size, or in inline mode its width and the rows of the region. Both are at least 1.

apply_resize

my ( $columns, $rows ) = $terminal->apply_resize( $width, $height );

Called with the size a resize event reported, once Term::Fabulous applies it. Returns the new size of the layout, like "size"; in inline mode the terminal finds its region again first.

read_handles

my @handles = $terminal->read_handles;

File handles that become readable when input waits, while the session is open. Term::Fabulous watches them with IO::Async during "run" in Term::Fabulous and calls "next_event" when one is readable. Term::Fabulous never reads from them and never closes them, and it switches them back to blocking mode after IO::Async has made them non-blocking. Handles the terminal owns must stay open until "close".

next_event

while ( defined( my $event = $terminal->next_event ) ) { ... }

Returns the next input event without waiting, as a Term::Fabulous::Termbox::Event of the type TB_EVENT_KEY, TB_EVENT_MOUSE or TB_EVENT_RESIZE, or undef when none waits. Dies when reading the input fails.

input_ended

1 when the input has ended for good (the terminal went away), so that no event will ever come again; otherwise 0. Term::Fabulous asks after reading the events of a readable handle.

kitty_keyboard_active

1 while the session uses the kitty keyboard protocol, otherwise 0.

cell_target

my $target = $terminal->cell_target;

The object Term::Fabulous::Render paints into: a cell target, see "CELL TARGET" in Term::Fabulous::Render. It is the same object for the lifetime of the terminal. A terminal that shows sixel graphics gives it the role Term::Fabulous::Render::Target::Sixel and keeps its cell size up to date while the session is open.

SEE ALSO

Term::Fabulous, Term::Fabulous::Terminal::Termbox, Term::Fabulous::Terminal::Memory, "CELL TARGET" in Term::Fabulous::Render.