/ 
Tickit-0.15
River stage two • 35 direct dependents • 41 total dependents
/ Tickit::Widget

NAME

Tickit::Widget - abstract base class for on-screen widgets

DESCRIPTION

This class acts as an abstract base class for on-screen widget objects. It provides the lower-level machinery required by most or all widget types.

Objects cannot be directly constructed in this class. Instead, a subclass of this class which provides a suitable implementation of the render and other provided methods is derived. Instances in that class are then constructed.

See the EXAMPLES section below.

CONSTRUCTOR

$widget = Tickit::Widget->new( %args )

Constructs a new Tickit::Widget object. Must be called on a subclass that implements the required methods; see the SUBCLASS METHODS section below.

Any pen attributes present in %args will be used to set the default values on the widget's pen object.

METHODS

$widget->set_window( $window )

Sets the Tickit::Window for the widget to draw on. Setting undef removes the window.

If a window is associated to the widget, that window's pen is set to the current widget pen. The widget is then drawn to the window by calling the render method. If a window is removed (by setting undef) then no cleanup of the window is performed; the new owner of the window is expected to do this.

This method may invoke the window_gained and window_lost methods.

$window = $widget->window

Returns the current window of the widget, if one has been set using set_window.

$widget->set_parent( $parent )

Sets the parent widget; pass undef to remove the parent.

$parent, if defined, must be a subclass of Tickit::ContainerWidget.

$parent = $widget->parent

Returns the current container widget

$widget->resized

Provided for subclasses to call when their size requirements have or may have changed. Informs the parent that the widget may require a differently-sized window.

$widget->redraw

Clears the widget's window then invokes the render method. This should completely redraw the widget.

This redraw doesn't happen immediately. The widget is marked as needing to redraw, and its parent is marked that it has a child needing redraw, recursively to the root widget. These will then be flushed out down the widget tree using an Tickit later call. This allows other widgets to register a requirement to redraw, and have them all flushed in a fairly efficient manner.

$pen = $widget->pen

Returns the current widget pen. Modifying an attribute of the returned object results in the widget being redrawn if the widget has a window associated.

$widget->set_pen( $pen )

Set a new Tickit::Pen object. This is stored by reference; changes to the pen will be reflected in the rendered look of the widget. The same pen may be shared by more than one widget; updates will affect them all.

SUBCLASS METHODS

Because this is an abstract class, the constructor must be called on a subclass which implements the following methods.

$widget->render( %args )

Called to redraw the widget's content to its window. Methods can be called on the contained Tickit::Window object obtained from $widget->window.

Will be passed hints on the region of the window that requires rendering; the method implementation may choose to use this information to restrict drawing, or it may ignore it entirely.

Before this method is called, the window area will be cleared if the (optional) object method CLEAR_BEFORE_RENDER returns true. Subclasses may wish to override this and return false if their render method will completely redraw the window expose area anyway, for better performance and less display flicker.

use constant CLEAR_BEFORE_RENDER => 0;
rect => Tickit::Rect

A Tickit::Rect object representing the region of the screen that requires rendering, relative to the widget's window.

Also provided by the following four named integers:

top => INT
left => INT

The top-left corner of the region that requires rendering, relative to the widget's window.

lines => INT
cols => INT

The size of the region that requires rendering.

$widget->reshape

Optional. Called after the window geometry is changed. Useful to distribute window change sizes to contained child widgets.

$lines = $widget->lines

$cols = $widget->cols

Called to enquire on the requested window for this widget. It is possible that the actual allocated window may be larger, or smaller than this amount.

$widget->window_gained( $window )

Optional. Called by set_window when a window has been set for this widget.

$widget->window_lost( $window )

Optional. Called by set_window when undef has been set as the window for this widget. The old window object is passed in.

$handled = $widget->on_key( $type, $str, $key )

Optional. If provided, this method will be set as the on_key callback for any window set on the widget. By providing this method a subclass can implement widgets that respond to user input.

$handled = $widget->on_mouse( $ev, $button, $line, $col )

Optional. If provided, this method will be set as the on_mouse callback for any window set on the widget. By providing this method a subclass can implement widgets that respond to user input.

EXAMPLES

A Trivial "Hello, World" Widget

The following is about the smallest possible Tickit::Widget implementation, containing the bare minimum of functionallity. It displays the fixed string "Hello, world" at the top left corner of its window.

package HelloWorldWidget;
use base 'Tickit::Widget';

sub lines {  1 }
sub cols  { 12 }

sub render
{
   my $self = shift;
   my $win = $self->window;

   $win->clear;
   $win->goto( 0, 0 );
   $win->print( "Hello, world" );
}

1;

The lines and cols methods tell the container of the widget what its minimum size requirements are, and the render method actually draws it to the window.

A slight improvement on this would be to obtain the size of the window, and position the text in the centre rather than the top left corner.

sub render
{
   my $self = shift;
   my $win = $self->window;

   $win->clear;
   $win->goto( ( $win->lines - 1 ) / 2, ( $win->cols - 12 ) / 2 );
   $win->print( "Hello, world" );
}

Reacting To User Input

If a widget subclass provides an on_key method, then this will receive keypress events if the widget's window has the focus. This example uses it to change the pen foreground colour.

package ColourWidget;
use base 'Tickit::Widget';

my $text = "Press 0 to 7 to change the colour of this text";

sub lines { 1 }
sub cols  { length $text }

sub render
{
   my $self = shift;
   my $win = $self->window;

   $win->clear;
   $win->goto( ( $win->lines - $self->lines ) / 2, ( $win->cols - $self->cols ) / 2 );
   $win->print( $text );

   $win->focus( 0, 0 );
}

sub on_key
{
   my $self = shift;
   my ( $type, $str ) = @_;

   if( $type eq "text" and $str =~ m/[0-7]/ ) {
      $self->pen->chattr( fg => $str );
      $self->redraw;
      return 1;
   }

   return 0;
}

1;

The render method sets the focus at the window's top left corner to ensure that the window always has focus, so the widget will receive keypress events. (A real widget implementation would likely pick a more sensible place to put the cursor).

The on_key method then gets invoked for keypresses. It returns a true value to indicate the keys it handles, returning false for the others, to allow parent widgets or the main Tickit object to handle them instead.

Similarly, by providing an on_mouse method, the widget subclass will receive mouse events within the window of the widget. This example saves a list of the last 10 mouse clicks and renders them with an X.

package ClickerWidget;
use base 'Tickit::Widget';

# In a real Widget this would be stored in an attribute of $self
my @points;

sub lines { 1 }
sub cols  { 1 }

sub render
{
   my $self = shift;
   my $win = $self->window;

   $win->clear;
   foreach my $point ( @points ) {
      $win->goto( $point->[0], $point->[1] );
      $win->print( "X" );
   }
}

sub on_mouse
{
   my $self = shift;
   my ( $ev, $button, $line, $col ) = @_;

   return unless $ev eq "press" and $button == 1;

   push @points, [ $line, $col ];
   shift @points while @points > 10;
   $self->redraw;
}

1;

This time there is no need to set the window focus, because mouse events do not need to follow the window that's in focus; they always affect the window at the location of the mouse cursor.

The on_mouse method then gets invoked whenever a mouse event happens within the window occupied by the widget. In this particular case, the method filters only for pressing button 1. It then stores the position of the mouse click in the @points array, for the render method to use.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>