The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
CursesWidgets-1.992
River stage zero No dependents
++
/ Curses::Widgets

NAME

Curses::Widgets - Base widget class for use with the Curses::Application framework

MODULE VERSION

$Id: Widgets.pm,v 1.100 2001/12/10 10:56:20 corliss Exp $

SYNOPSIS

        use Curses::Widgets;

        $colpr = select_colour($fore, $back);
        $colpr = select_color($fore, $back);

        $key = scankey($mwh);

        @lines = textwrap($text, 40);

        # The following are provided for use with descendent
        # classes, or are expected to be overridden.
        $obj = Curses::Widgets->new({ KEY => 'value' });
        $obj->_conf(%conf);
        $obj->reset;

        $obj->_input($ch);
        $obj->input($string);

        $obj->execute($mwh);
        $obj->draw($mwh, 1);

        $value = $obj->getField('VALUE');
        $obj->setField(
                'FIELD1'        => 1,
                'FIELD2'        => 'value'
                );

REQUIREMENTS

Curses

DESCRIPTION

This module serves two purposes: to provide a framework for creating custom widget classes, and importing a few useful functions for global use.

Widget specific methods are documented in each Widget's pod, of which the following widgets are currently available:

Button Set (Curses::Widgets::ButtonSet)
Calendar (Curses::Widgets::Calendar)
Combo-Box (Curses::Widgets::ComboBox)
List Box (Curses::Widgets::ListBox)
Progress Bar (Curses::Widgets::ProgressBar)
Text Field (Curses::Widgets::TextField)
Text Memo (Curses::Widgets::TextMemo)

The following tutorials are available:

Widget Usage -- General Usage & Tips (Curses::Widgets::Tutorial)
Widget Creation (Curses::Widgets::Tutorial::Creation)
Widget Creation -- ComboBox Example (Curses::Widgets::Tutorial::ComboBox)

EXPORTED FUNCTIONS

select_colour/select_color

        $colpr = select_colour($fore, $back);
        $colpr = select_color($fore, $back);

This function returns the number of the specified colour pair. In doing so, it saves quite a few steps. First, the first time it's called, it tests the console for colour capability. If found, it then calls the (n)curses start_color function for you.

After the initial colour test, this function will safely (and quietly) return on all subsequent calls if no colour support is found. It returns '0', which is hardwired to 'black:white', the default for most terminals. If colour support is present, it allocates the colour pair using (n)curses init_pair for you, if it hasn't been done already.

Finally, the background colour is option, but if not specified, it defaults to 'black'.

As a final note, yes, both the British and American spellings of 'colo(u)r' are supported.

scankey

        $key = scankey($mwh);

The scankey function returns the key pressed, when it does. All it does is loop over a (n)curses getch call until something other than -1 is returned. Whether or not the getch call is (half)-blocking or cooked output is determined by how the (n)curses environment was initialised by your application. This is provided only to provide the most basic input functionality to your application, should you decide not to implement your own.

The only argument is a handle to a curses/window object.

textwrap

        @lines = textwrap($text, 40);

The textwrap function takes a string and splits according to the passed column limit, splitting preferrably along whitespace.

METHODS

new

        $obj = Curses::Widgets->new({ KEY => 'value' });

The new class method provides a basic constructor for all descendent widget classes. Internally, it assumes any configuration information to be passed in a hash ref as the sole argument. It dereferences that ref and passes it to the internal method _conf, which is expected to do any input validation/initialisation required by your widget. That method should return a 1 or 0, which will determine if new returns a handle to the new object.

If _conf returns a 1, the _copy is called to back up the initial state information.

_conf

        $self->_conf(%conf);

This method should be overridden in your descendant class. As mentioned above, it should do any initialisation and validation required, based on the passed configuration hash. It should return a 1 or 0, depending on whether any critical errors were encountered during instantiation.

Note: your _conf method should call, as a last act, $self-SUPER::_conf>. If you don't do this, then you should include the following code at the end of your method:

        $self->{CONF} = { %conf };
        $self->{OCONF} = {};

As a final note, here are some rules regarding the structure of your configuration hash. You *must* save your state information in this hash. Another subroutine will copy that information after object instantiation in order to support the reset method. Also note that everything stored in this should *not* be more than one additional level deep (in other words, values can be hash or array refs, but none of the values in *that* structure should be refs), otherwise those refs will be copied over, instead of the data inside the structure. This essentially destroys your backup.

If you have special requirements, override the _copy method as well.

reset

        $obj->reset;

The reset method resets the object back to the original state by copying the original configuration information into the working hash.

_input

        $self->_input($ch);

The _input method should be overridden in all descendent classes. This method should accept character input and update it's internal state information appropriately. This method will be used in both interactive and non-interactive modes to send keystrokes to the widget.

input

        $obj->input($string);

The input method provides a non-interactive method for sending input to the widget. This is essentially just a wrapper for the _input method, but will accept any number of string arguments at once. It splits all of the input into separate characters for feeding to the _input method.

execute

        $obj->execute($mwh);

This method puts the widget into interactive mode, which consists of calling the draw method, scanning for keyboard input, feeding it to the _input method, and redrawing.

execute uses the widget's configuration information to allow easy modification of its behavoiur. First, it checks for the existance of a INPUTFUNC key. Setting its value to a subroutine reference allows you to substitute any custom keyboard scanning/polling routine in leiu of the default scankey provided by this module.

Second, it checks the return value of the input function against the regular expression stored in FOCUSSWITCH, if any. Any matches against that expression will tell this method to exit, returning the key that matches it. This effectively causes the widget to 'lose focus'.

The only argument is a handle to a valid curses window object.

draw

        $obj->draw($mwh, 1);

The draw method should be overridden in each descendant class. It is reponsible for the rendering of the widget, and only that. The first argument is mandatory, being a valid window handle with which to create the widget's derived window. The second is optional, but if set to true, will tell the widget to draw itself in an 'active' state. For instance, the TextField widget will also render a cursor, while a ButtonSet widget will render the selected button in standout mode.

getField

        $value = $obj->getField('VALUE');

The getField method retrieves the value(s) for every field requested that exists in the configuration hash.

setField

        $obj->setField(
                'FIELD1'        => 1,
                'FIELD2'        => 'value'
                );

The setField method sets the value for every key/value pair passed.

HISTORY

2001/07/05 -- First implementation of the base class.

AUTHOR/COPYRIGHT

(c) 2001 Arthur Corliss (corliss@digitalmages.com)