NAME
Game::Terminal::Kit::Canvas - a grid of characters to draw a board on
VERSION
Version 0.05
SYNOPSIS
use Game::Terminal::Kit::Canvas;
use Game::Terminal::Kit::Frame;
my $canvas = Game::Terminal::Kit::Canvas->new(width => 40, height => 12);
$canvas->fill(0, 0, 40, 12, ' ', ground => '48;5;22');
$canvas->box(2, 1, 5, 3, Game::Terminal::Kit::Frame::box('cursor', $ascii));
$canvas->put(3, 2, 'K', ink => '1;31');
$canvas->put(10, 2, 'your move', ink => '1');
$screen->show([ $canvas->lines($screen) ]);DESCRIPTION
A board whose pieces sit at places, drawn by putting each thing where it goes and then asking for the rows. It saves a game from building each row of the screen out of pieces of string in the right order.
A place is a column and a row counted from 0 at the top left. Anything put outside the canvas is dropped, a piece at a time, so a thing half off the edge shows the half that is on.
Colour
A cell has an ink and a ground, each the parameters of an SGR sequence such as '1;31' or '48;5;22'. "lines" writes a sequence only where the style changes along a row and resets at the end of the row, and writes none at all for a screen without colour, so a canvas is as cheap to print plain as it is coloured.
Wide characters
Some glyphs take two columns: the Mahjong tiles, a Chinese chess piece. Put them with wide => 1 and each takes two cells, so what is put after them lands where it will be seen. A wide glyph with only one column left at the edge is dropped, and one that is half overwritten is cleared.
ATTRIBUTES
width
height
The size, in columns and rows.
cells
The grid itself, rows of cells. Read it if you must; write it with "put".
METHODS
Each but "lines" and "text" returns the canvas.
put
$canvas->put($x, $y, $text, ink => '1;31', ground => '44', wide => 0);The text, left to right from that place, a column a character or two with wide.
fill
$canvas->fill($x, $y, $width, $height, $glyph, %style);A rectangle of one character, a space when none is given.
box
$canvas->box($x, $y, $width, $height, $glyphs, %style);The outline of a rectangle, from the eight glyphs "box" in Game::Terminal::Kit::Frame returns. What is inside is left alone. Nothing is drawn for a box less than two wide or two high.
wipe
Every cell back to a space with no style.
lines
my @lines = $canvas->lines($screen);One string a row. Coloured when given a Game::Terminal::Kit::Screen whose colour is on. Spaces at the end of a row are left off unless they have a ground to show.
text
The rows with no colour, whatever the screen: what a test compares.
SEE ALSO
Game::Terminal::Kit, Game::Terminal::Kit::Frame, Game::Terminal::Kit::Screen.
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)