Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Widgets::Tutorial::CreUsernContributed Perl DocuWidgets::Tutorial::Creation(3)

       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

	 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


       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:


       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

       (c) 2001	Arthur Corliss (,

perl v5.32.1			  2002-11-14	Widgets::Tutorial::Creation(3)


Want to link to this manual page? Use this URL:

home | help