Provided by: libcurses-widgets-perl_1.997-8_all bug

NAME

       Curses::Widget::Tutorial::Creation -- Widget Creation Tutorial

POD VERSION

       $Id: Creation.pod,v 0.3 2002/11/04 00:45:06 corliss Exp corliss $

DESCRIPTION

       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

   BASIC MODULE STRUCTURE
       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.

   METHOD SEMANTICS
       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
         }

   CONCLUSION
       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.

HISTORY

       2001/07/07 -- First draft.  2002/11/01 -- Updated for reworked internals.

AUTHOR/COPYRIGHT

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