Curses::UI::Widget - The base class for all widgets



NAME

Curses::UI::Widget - The base class for all widgets


CLASS HIERARCHY

 Curses::UI::Widget - base class


SYNOPSIS

This class is not used directly by somebody who is building an application using Curses::UI. It's a base class that is expanded by the Curses::UI widgets. See WIDGET STRUCTURE below for a basic widget framework.

    use Curses::UI::Widget;
    my $widget = new Curses::UI::Widget(
        -width  => 15,
        -height => 5,
        -border => 1,
    );


STANDARD OPTIONS

The standard options for (most) widgets are the options that are enabled by this class. So this class doesn't really have standard options.


WIDGET-SPECIFIC OPTIONS

GENERAL:

POSITIONING:

 +---------------------------------------------------+
 | parent                     ^                      |
 |                            |                      |
 |                            y                      |
 |                            |                      |
 |                            v                      |
 |                            ^                      |
 |                            |                      |
 |                          padtop                   |
 |                            |                      |
 |                            v                      |
 |                    +- TITLE -------+              |
 |                    | widget   ^    |              |
 |                    |          |    |              |
 |                    |          |    |              |
 |<--x--><--padleft-->|<----width---->|<--padright-->|
 |                    |          |    |              |
 |                    |          |    |              |
 |                    |        height |              |
 |                    |          v    |              |
 |                    +---------------+              |
 |                               ^                   |
 |                               |                   |
 |                           padbottom               |
 |                               |                   |
 |                               v                   |
 +---------------------------------------------------+

PADDING:

TITLE:

Remark:

A title is drawn in the border of a widget. So a title will only be available if -border is true.

SCROLLBARS:

Remark:

Since the user of a Curses::UI program has no real control over the so called ``scrollbars'', they aren't really scrollbars. A better name would be something like ``document location indicators''. But since they look so much like scrollbars I decided I could get away with this naming convention.

EVENTS


METHODS


WIDGET STRUCTURE

Here's a basic framework for creating a new widget. You do not have to follow this framework. As long as your widget has the methods new(), layout(), draw() and focus(), it can be used in Curses::UI.

    package Curses::UI::YourWidget
    use Curses;
    use Curses::UI::Widget;  
    use Curses::UI::Common; # some common widget routines
    use vars qw($VERSION @ISA);
    $VERSION = '0.01';
    @ISA = qw(Curses::UI::Widget Curses::UI::Common);
    # For a widget that can get focus, you should define
    # the routines that are used to control the widget.
    # Each routine has a name. This name is used in 
    # the definition of the bindings. 
    # The value can be a string or a subroutine reference. 
    # A string will make the widget return from focus.
    #
    my %routines = (
        'return'    => 'LOSE_FOCUS',
        'key-a'     => \&key_a,
        'key-other' => \&other_key
    );
    # Using the bindings, the routines can be binded to key-
    # presses. If the keypress is an empty string, this means
    # that this is the default binding. If the key is not 
    # handled by any other binding, it's handled by this
    # default binding.
    #
    my %bindings = (
        KEY_DOWN()  => 'return',   # down arrow will make the 
                                   # widget lose it's focus
        'a'         => 'key-a',    # a-key will trigger key_a()
        ''          => 'key-other' # any other key will trigger other_key()
    );
    # The creation of the widget. When doing it this way,
    # it's easy to make optional and forced arguments 
    # possible. A forced argument could for example be 
    # -border => 1, which would mean that the widget
    # always has a border, which can't be disabled by the
    # programmer. The arguments can of course be used 
    # for storing the current state of the widget.
    #
    sub new () {
        my $class = shift;
        my %args = (
            -optional_argument_1 => "default value 1",
            -optional_argument_2 => "default value 2",
            ....etc....
            @_,
            -forced_argument_1   => "forced value 1", 
            -forced_argument_2   => "forced value 2", 
            ....etc....
            -bindings            => {%bindings},
            -routines            => {%routines},
        );
        # Create the widget and do the layout of it.
        my $this = $class->SUPER::new( %args );
    $this->layout;
    return $this;
    }
    # Each widget should have a layout() routine. Here,
    # the widget itself and it's contents can be layouted.
    # In case of a very simple widget, this will only mean
    # that the Widget has to be layouted (in which case the
    # routine could be left out, since it's in the base
    # class already). In other cases you will have to add
    # your own layout code. This routine is very important,
    # since it will enable the resizeability of the widget!
    #
    sub layout () {
        my $this = shift;
        $this->SUPER::layout;
    return $this if $Curses::UI::screen_too_small;
        ....your own layout stuff....
        # If you decide that the widget does not fit on the
        # screen, then set $Curses::UI::screen_too_small
        # to a true value and return.    
        if ( ....the widget does not fit.... ) {
            $Curses::UI::screen_too_small++;
            return $this;
        }
        return $this;
    }
    # The widget is drawn by the draw() routine. The
    # $no_update part is used to disable screen flickering
    # if a lot of widgets have to be drawn at once (for
    # example on resizing or redrawing). The curses window
    # which you can use for drawing the widget's contents
    # is $this->{-canvasscr}.
    #
    sub draw(;$) {
        my $this = shift;
        my $no_doupdate = shift || 0;
        return $this if $this->hidden;
        $this->SUPER::draw(1);
        ....your own draw stuff....
        $this->{-canvasscr}->addstr(0, 0, "Fixed string");
        ....your own draw stuff....
        $this->{-canvasscr}->noutrefresh;
        doupdate() unless $no_doupdate;
    return $this;
    }
    # Focus the widget. If you do not override this routine
    # from Curses::UI::Widget, the widget will not be 
    # focusable. Mostly you will use the generic_focus() method.
    #
    sub focus()
    {
        my $this = shift;
        $this->show; # makes the widget visible if it was invisible
        return $this->generic_focus(
            undef,             # delaytime, default = 2 (1/10 second).
            NO_CONTROLKEYS,    # disable controlkeys like CTRL+C. To enable
                               # them use CONTROLKEYS instead.
            CURSOR_INVISIBLE,  # do not show the cursor (if supported). To
                               # show the cursor use CURSOR_VISIBLE.
            \&pre_key_routine, # optional callback routine to execute
                               # before a key is read. Mostly unused.
        );
    }
    ....your own widget handling routines....


SEE ALSO

Curses::UI


AUTHOR

Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.

Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)

This package is free software and is provided ``as is'' without express or implied warranty. It may be used, redistributed and/or modified under the same terms as perl itself.

 Curses::UI::Widget - The base class for all widgets