• NAME
• SYNOPSIS
• METHODS
• new()
• become_interactive()

NAME

Karma::Input::Menu - a versatile class designed to ease the creation of simple user interfaces..

SYNOPSIS

 my $menu = Karma::Input::Menu->new(
        Y => 11,
        X => 16,
        Format  => {
                    Normal   => {
                                  Key  => '^60^b%s ^B^70-',
                                  Name => " ^60^b%s.\n"
                    },
                    Selected => {
                                  Key  => '^60^B%s ^B^70+',
                                  Name => " ^60^B%s.\n"
                    }
        },
        Prompt  => '^00^B[and me]',
        Choices => [
                [ 'w', 'who\'s on',             sub { menu 'nodelist' }         ],
        ]
 );

 $menu->become_interactive;

METHODS

Objects of this package are granted the following methods.

new()

The constructor for new menu objects, this method takes its arguments as a list of key => value pairs.

Y

Starting line for the menu relative to stdscr.

X

Ditto for column.

Format

The value of Format should be an anonymous hash, which in turn contains two more such structures. There should be one named Normal and, optionally, a second called Selected.

These hashes must each have keys named Key and Name that contain scalar strings to later be used as printf() formats, and then displayed on the screen via printc(). Each of these values should, therefore, contain exactly one printf() conversion code.

If Selected is omitted, then the user will notice no difference between the currently selected menu item and all of the others. However, if defined, the format in Selected will be used to display the selected item in order for it to stand out among its brethren.

Prompt

This field is optional, and is simply shorthand for calling printc() of the value after having displayed the menu.

Choices

This field is the real meat of the menu description. It defines the keys, names, and action to be taken for each item in the menu. Items may be hidden from view by setting the name value to undef.

Choices should be an anonymous array, in which each element is an anonymous array of the following fields.

 eg. [ 'a', 'add something', sub { $something++ } ]

$key

This is will be the hot key for the menu entry. It is left up to the programmer to insure that each $key is unique.

$name

Should be a concise description of the function provided by this item in the menu.

\&code

Finally, the last element in the array should be a reference to a sub routine that should be called if the item is chosen.

become_interactive()

When called on a menu object already instantiated via new this method will give control to the user, so that they might choose an item. The user will be able to navigate the menu with the $keys, as well as with the arrow-keys on their terminal. The coderef passed to new() for this menu entry will be executed inside an eval once the user has selected an item. Items may be selected by pressing either the return key when the item is highlighted, or by the key bound to the item via new().

This method returns the value of the code executed, and will block until the user makes a decision.