NAME
Game::Terminal::Kit::Picker - a list the player chooses from with the arrow keys
VERSION
Version 0.05
SYNOPSIS
use Game::Terminal::Kit::Picker;
my $picker = Game::Terminal::Kit::Picker->new(
items => [ map { { label => $_->notation, about => describe($_), value => $_ } } @legal ],
head => [ @board_lines, '' ],
legend => [ '', 'up and down to choose, enter to play, ? for help, q to quit' ],
game_keys => { '?' => 'help', u => 'undo' },
log => $log,
screen => $screen,
);
my ($event, $value) = $picker->run($keys, $screen);
play($value) if $event eq 'chosen';
show_help() if $event eq 'key' && $value eq 'help';DESCRIPTION
The legal moves, the cards in a hand, the tiles that can be played: a list, a cursor, and enter. It is one of the kit's widgets; see Game::Terminal::Kit::Widget for lines, step and run.
The items are what is drawn
Give the items in the order they appear on the screen. If the screen shows a hand sorted into suits, sort the hand once, draw from that, and pass that. The cursor walks the list it is given and nothing else, so right means right for as long as the two are the same list.
An item is a string, or a hash reference with
label-
What is drawn.
value-
What comes back when it is chosen. The item itself when there is none.
about-
A few words drawn in a second column.
skip-
True for an item that is drawn and cannot be chosen, such as the card just picked up that may not be thrown straight back. The cursor steps over it.
The keys
Up and down move the cursor and go round at the ends; so do left and right, tab and shift-tab. Home and end go to the ends, and a digit goes to that row when the rows are numbered. Enter or space chooses. Escape or backspace goes back, and q quits.
Any key in game_keys is the game's: it comes back as the event key with the name the game gave it, before the picker considers it, so a game may take any letter it likes, q included.
What just happened
Give the picker the game's Game::Terminal::Kit::Log and it draws the log between the head and the rows, every frame. The opponent's move is then still on screen while the player chooses a reply to it.
Choosing several
With need set to a number the rows have boxes, enter ticks and unticks the row under the cursor, and the picker answers when that many are ticked, with their values in the order they are drawn.
A turn made of several moves
Do not list every combination. List the next move of every legal turn that begins with what has been chosen so far, let the player choose one, and ask again with "reset"; on back, take the last one off and ask again. The list stays short, and since every row is the next move of a turn the rules already allow, no path through it ends somewhere illegal.
ATTRIBUTES
items
The list, an array reference, in drawn order.
at
The index under the cursor. It starts where "resting" says.
prefer
A code reference called with an item and its index, true for one the cursor should start on: the card the player usually means. The first such item is the start; without one, the first that can be chosen.
window
The most rows drawn, 8 by default, so that a long list cannot push the board off the screen; the rest are counted above and below. 0 draws them all.
head
legend
Lines drawn above the list and below it, array references. The picker adds no blank lines of its own around them.
game_keys
A hash reference from a key to the name the game wants back for it.
need
How many rows to tick before the picker answers; 0, the default, is one choice and no boxes.
chosen
The indexes ticked so far.
numbered
True, the default, to number the rows and let a digit jump to one.
across
True when the list is drawn as a row, so that up goes the way right does and down the way left does. Up and down otherwise go the way left and right do.
log
A Game::Terminal::Kit::Log, drawn in every frame.
screen
A Game::Terminal::Kit::Screen, for colour: the row under the cursor is reverse video and a skipped row is dim. Without one the rows are plain, and the cursor is still the row that starts >.
METHODS
lines
The head, the log and a blank line if it has anything to say, the rows, the legend.
rows
The rows alone, for a game that lays the frame out itself.
step
my ($event, $value) = $picker->step($key);chosen with the value, or an array reference of values under "need"; back; quit; key with its name; moved; changed when a row was ticked or unticked; none for a key that does nothing, which is also noted in the log.
run
my ($event, $value) = $picker->run($keys, $screen);Draws and reads until the player chooses, goes back, quits or presses one of the game's keys.
reset
$picker->reset(\@items);New items, nothing ticked, and the cursor at rest. Returns the picker.
current
The value under the cursor, or undef when there is nothing to choose: what a game previews while the player is still deciding.
resting
The index the cursor starts on.
move
jump
take
What the keys do: move the cursor by one either way, put it on an index, and choose or tick what is under it. Each returns what "step" would.
skipped
label_of
value_of
Whether the item at an index is skipped, and its label and its value.
SEE ALSO
Game::Terminal::Kit::Widget, Game::Terminal::Kit::Steer, Game::Terminal::Kit::Choose.
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)