/ 
Game-Terminal-Kit-0.05
/ Game::Terminal::Kit::Form

NAME

Game::Terminal::Kit::Form - a game's options, set before it starts

VERSION

Version 0.05

SYNOPSIS

use Game::Terminal::Kit::Form;

my $form = Game::Terminal::Kit::Form->new(
    title  => 'checkers: English draughts',
    fields => Game::Checkers::Terminal->options,
    values => \%remembered,
    log    => $log,
    screen => $screen,
);

my ($event) = $form->run($keys, $screen);
Game::Checkers::Terminal->run($form->argv) if $event eq 'chosen';

DESCRIPTION

A screen of the fields a game says it has (see Game::Terminal::Kit::Options), each with its value, and a last row that starts the game. The player moves up and down the rows and changes the one under the cursor.

checkers: English draughts

   level       the game's own     the strength of the bot
 > side        white              your side; black moves first
   hotseat     off                two people at one keyboard, no bot
   extra       (none)             anything else, as on the command line

   Play

A value nobody set is shown as the game's own, and nothing is sent for it, so the form never has to know a default. The cursor starts on the last row: enter straight away plays the game as it comes.

It is one of the kit's widgets; see Game::Terminal::Kit::Widget.

The keys

Up and down, k and j, tab and shift-tab move between rows and go round. Left and right step a number, a choice, a flag or a bool. Enter or space steps a choice, a flag or a bool, and for a number or text asks for a line. Backspace or delete puts a row back to the game's own. Enter on the last row, or p anywhere, answers. Escape or q goes back.

ATTRIBUTES

title

A line above the fields, with a blank line after it.

fields

The fields, an array reference as Game::Terminal::Kit::Options describes.

values

A hash reference from a field's name to its value, changed in place. Pass the same one again and the form opens as the player left it.

extra

True, the default, for a last field of free text that is split like a shell and added to the command line: the way to an option the game did not list.

action

The label of the last row; Play by default.

at

The row under the cursor; the last by default.

legend

Lines below the form. By default the keys, in two lines.

log

A Game::Terminal::Kit::Log, drawn under the last row. The form notes a refused value and a key that does nothing there; without a log they are simply not said.

screen

A Game::Terminal::Kit::Screen, for colour.

METHODS

lines

The title, the rows, the action, the log, the legend.

step

my ($event, $value) = $form->step($key);

chosen with the values when the player starts the game; edit with a field when a line of text is wanted for it, to be answered with "set"; back; quit; moved; changed; none.

run

my ($event, $values) = $form->run($keys, $screen);

Draws and reads until the player starts the game or goes back. A line of text is asked for with a Game::Terminal::Kit::Line under the form.

set

$form->set($name, $text) or redraw();

Gives a field typed text. The text is checked against the field; when it is refused the reason is noted, the value is left as it was and the result is false. Blank text puts the field back to the game's own.

argv

The command line for the values as they stand.

rows

The fields and, with "extra", the extra one, as an array reference.

show_value

my $text = $form->show_value($field, $value);

How a value is drawn: on or off, the value, the game's own.

SEE ALSO

Game::Terminal::Kit::Options, Game::Terminal::Kit::Widget, Game::Terminal.

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)