Curses::Widget::Tutorial::Creation -- Widget Creation Tutorial
$Id: Creation.pod,v 0.3 2002/11/04 00:45:06 corliss Exp corliss $
Creating a custom widget is as easy as creating a descendant class of
Curses::Widget and defining as few as four methods:
Method Purpose
====================================================
_conf Validates configurations options and
initialises the internal state/data
_content Renders the widget according to the
current state
_cursor Renders the widget cursor according to the
current state
input_key Updates the state information according
to the passed character input
A decent code template for custom widgets would start with the following (we'll
call our new widget
MyWidget):
package MyWidget;
use strict;
use vars qw($VERSION @ISA);
use Curses;
use Curses::Widget;
($VERSION) = (q$Revision: 0.3 $ =~ /(\d+(?:\.(\d+))+)/);
@ISA = qw(Curses::Widget);
Please note that the
use Curses::Widget; statment provides more than just
a base class to inherit methods from, it also imports standard functions for
use in the module:
Function Purpose
===========================================================
select_colour Initialises new colour pairs, and returns
the appropriate colour pair number, for use
with $wh->attrset(COLOR_PAIR($n)) calls.
select_color, the American English spelling,
also works.
scankey This blocks until a key is pressed, and that
key returned.
textwrap Splits the text given into lines no longer
than the column limit specified.
See the
Curses::Widget pod for the specific syntax.
Descendent classes will automatically know the following fields (as used by the
new or
get/setField methods):
Field Type Description
===========================================================
Y int Y coordinate of upper left corner of widget
X int X coordinate of upper left corner of widget
LINES int Number of lines in the content area of the widget
COLUMNS int Number of columsn inthe content area
BORDER boolean Whether to surround the widget with a box
CAPTION string Caption to display on top of border
FOREGROUND string Default foreground colour
BACKGROUND string Default background colour
BORDERCOL string Default border foreground colour
CAPTIONCOL string Default caption foreground colour
The colours, if not specified during widget instantiation, will default to the
colours in colour pair 0 (the terminal default). Borders will only be drawn if
BORDER is true, and that decision is made in the default
_border
method, not in the
draw method. The
_caption method also decides
internally whether or not to draw itself according to the value of BORDER.
The _conf method is called by the class constructor (provided by
Curses::Widget, unless you override it here as well). Widget objects
should be created with all configuration options passed in a hash ref:
$widget = Curses::Widget::MyWidget->new({
OPTION1 => $value1,
OPTION2 => $value2,
[. . .]
});
The configuration hash is dereferenced and passed as arguments to the _conf
method inside of the
new constructor:
$rv = $self->_conf(%$conf);
Because of this, the _conf method should probably begin along these lines:
sub _conf {
my $self = shift;
my %conf = (
OPTION1 => default1,
OPTION2 => default2,
[. . .],
@_
);
my $err = 0;
# Validate and initialise the widget's state
# and store in the %conf hash
# Always include the following
$err = 1 unless $self->SUPER::_conf(%conf);
return ($err == 0) ? 1 : 0;
}
You should perform any initialisation and validation of the configuration
options here. This routine is expected to return a true or false value,
depending on whether or not any critical errors were found. A false value will
prevent the
new constructor from returning an object reference, causing
the instantiation request to fail.
The last two lines of code should always be included in this subroutine. The
call to the parent class' _conf method stores the final initialised state
information in %conf in the object field
CONF, after initialising many
of the standard colour fields, should they have been left undefined. You can
retrieve and update the state information via $self->{CONF}. A copy of that
state information will be stored in $self->{OCONF}, and can be restored
with a call to
reset, a method provided by
Curses::Widgets.
The second method you should override is the
_content method. This
method, as mentioned above, is responsible for rendering the widget according
to its state information. This method should handle one arguments:
$widget->_content($cwh);
The argument will be a window handle to the
content area of the widget.
You should always layout your widget with the upper left corner as (0, 0),
since the
draw method is responsible for allocating any extra space
needed for borders and captions.
If your widget doesn't support borders and/or captions you can do one of two
things: override those methods (
_border and
_caption) to
immediately return without doing anything, or override the
draw method
to exclude those calls. Typically, the former method of handling this would be
preferred.
The third method you need to override is the
_cursor method. This accepts
the same window handle as the
_content method. The default
draw
method will only call this method if it was called with a true
active
argument.
Neither of these two methods will need to allocate, refresh, or destroy window
handles, just print the content. The windows will already be erased and
initialised to specified foreground/background pairs, and those settings saved
via the
_save method. If at any time you need to reset the window
handle's current cursor back to those settings you can call
_restore:
$self->_restore($dwh);
In fact, in order to make the state of the window handle more predictable for
descendent classes you should probably call _restore at the end of each of
these methods.
The final method that should be overridden is the input_key method. This expects
a single argument, that being the keystroke captured by the keyboard scanning
function. It uses that value to update (if it's not rejected) the widget's
state information. A rough skeleton for this function would be as follows:
sub input_key {
my $self = shift;
my $key = shift;
my $conf = $self->{CONF};
# validate/update state information
}
That, in a nutshell, is all there is to creating a custom widget. For a working
example which uses the structure noted above, look at the TextField or
ButtonSet widgets. Both consist of nothing more than the routines listed
above.
2001/07/07 -- First draft. 2002/11/01 -- Updated for reworked internals.
(c) 2001 Arthur Corliss (
[email protected]),