NAME
Game::Terminal::Kit::Screen - what a terminal game writes to
VERSION
Version 0.05
SYNOPSIS
use Game::Terminal::Kit::Screen;
my $screen = Game::Terminal::Kit::Screen->new;
$screen->utf8->flush_on->hide_cursor;
if (defined(my $why = $screen->too_small(40, 20))) {
$screen->say($why);
}
$screen->show([
$screen->paint('Checkers', '1'),
'',
@board_lines,
]);
$screen->restore;DESCRIPTION
The output half of a terminal game: one handle, and whether it is a terminal, takes colour, and takes anything but ASCII. Every method that writes an escape sequence writes none when the handle is not a terminal, so the same game piped to a file is plain lines.
Drawing a frame
"show" takes the whole screen as a list of lines and draws it over the last one: home, each line and an erase to the end of it, then an erase of everything below. Nothing is cleared first, so a frame drawn twenty times a second does not flicker. Off a terminal it prints the lines.
"clear" is for the first frame, and for a game that prints as it goes.
Colour
Colour is on when the handle is a terminal and NO_COLOR is unset or empty. "paint" takes the text and the parameters of an SGR sequence, '1;7' or '38;5;208', and returns the text alone when colour is off. A game should never tell two things apart by colour only; see Game::Terminal::Kit::Frame.
Size
"size" is the window in columns and lines: from the terminal when Term::ReadKey is installed, else from COLUMNS and LINES, else 80 by 24. "too_small" answers with a sentence for the player when the window is known and is smaller than a game needs, and with undef when it is big enough or cannot be known.
ATTRIBUTES
out
The handle written to. STDOUT by default.
interactive
True when escape sequences may be written. By default, whether "out" is a terminal.
colour
True when "paint" colours. By default "interactive", and off under NO_COLOR.
ascii
True when the game should draw in ASCII only. The screen does not draw; it keeps the answer for the things that do, and "utf8" respects it.
columns
rows
A size to believe in place of the terminal's, for a test or an option.
cursor_hidden
True after "hide_cursor" until the cursor is shown again.
METHODS
Every method but "paint", "size", "measured", "too_small" and "no_colour" returns the screen.
say
$screen->say('one line', 'and another');Each line and a newline; one empty line when given none.
show
$screen->show(\@lines);The whole frame, drawn over the last; see "Drawing a frame".
clear
$screen->clear;
$screen->clear(scrollback => 1);Erases the window and homes the cursor, and with scrollback erases what has scrolled off as well. Nothing off a terminal.
rewind
$screen->rewind(12);Moves up that many lines to the first column, to draw again over a block just printed without taking the whole window.
at
$screen->at($row, $column);Moves to a row and column, both counted from 1.
paint
my $text = $screen->paint('your move', '1;32');The text in that SGR and a reset after it, or the text as it was when colour is off.
hide_cursor
show_cursor
Hide the cursor on a terminal, and show it again if this screen hid it.
restore
Puts back what the screen changed: the cursor if it was hidden, and the colours with it. Safe to call twice, and from a signal handler.
utf8
Makes "out" encode to UTF-8 unless it already does or "ascii" is set.
flush_on
Turns buffering off on "out" and leaves the selected handle alone.
size
my ($columns, $rows) = $screen->size;measured
The same, but an empty list when the size is not known, and 0 for the rows when only the columns are.
too_small
my $why = $screen->too_small($columns, $rows);A sentence saying what the window is and what is needed, or undef. The rows may be left out.
no_colour
True when NO_COLOR is set to anything but the empty string. A function.
SEE ALSO
Game::Terminal::Kit, Game::Terminal::Kit::Keys, https://no-color.org.
AUTHOR
LNATION, <email at lnation.org>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)