/ 
Game-Terminal-Kit-0.05
/ Game::Terminal::Kit::Widget

NAME

Game::Terminal::Kit::Widget - what every widget of the kit has in common

VERSION

Version 0.05

SYNOPSIS

# the short way: the widget owns the screen until it is answered
my ($event, $value) = $picker->run($keys, $screen);

# the long way: the game owns the loop, and can do other things in it
while ($playing) {
    $screen->show([ @board, $picker->lines ]);
    my $key = $keys->read_key($ticker->remaining);
    if (defined $key) {
        my ($event, $value) = $picker->step($key);
        play($value) if $event eq 'chosen';
    }
    advance() if $ticker->due;
}

DESCRIPTION

A widget is something on the screen the player answers with the keyboard: a Game::Terminal::Kit::Picker, a Game::Terminal::Kit::Choose, a Game::Terminal::Kit::Form, a Game::Terminal::Kit::Line. Each has the same three methods.

lines

What to draw now, as a list of strings.

step($key)

Takes one key, as Game::Terminal::Kit::Keys names it, and returns an event and perhaps a value.

run($keys, $screen)

Draws, reads a key, steps, and goes round until an event that ends it, which it returns with its value.

lines and step touch nothing but the widget, so a widget can be drawn as part of a larger frame and stepped from a loop that is doing other things, and can be tested without a keyboard or a screen. run is the only method that reads or writes.

Events

chosen    the player answered; the value is the answer
back      the player backed out of this, one step
quit      the player wants to stop, or the input ended
key       a key the game asked to be told about; the value is its name
edit      a form wants a line of text; the value is the field
moved     the cursor moved
changed   something on the widget changed
none      the key does nothing here

The last three do not end run.

FUNCTIONS

None is exported. They are for writing a widget; a game calls the widget.

run

my ($event, $value) = Game::Terminal::Kit::Widget::run($widget, $keys, $screen);

The loop behind every widget's run.

draw

Game::Terminal::Kit::Widget::draw($widget, $screen);

One frame: the widget's lines shown, and its log told they were.

goes_on

True for an event that does not end run.

paint

my $text = Game::Terminal::Kit::Widget::paint($widget, $text, $sgr);

The text coloured by the widget's screen, or as it was when the widget has none.

SEE ALSO

Game::Terminal::Kit.

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)