NAME
Curses::UI::Widget - The base class for all widgets
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. Here's an example of how to start out creating a new widget:
package Curses::UI::YourWidget
use Curses;
use Curses::UI::Widget;
use Curses::UI::Common; # some common widget routines
use vars qw($VERSION @ISA);
$VERSION = '1.0.0';
@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' => 'RETURN',
'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 loose 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;
....your own layout stuff....
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->{-windowscr}.
#
sub draw(;$) {
my $this = shift;
my $no_doupdate = shift || 0;
return $this if $this->hidden;
$this->SUPER::draw(1);
....your own draw stuff....
$this->{-windowscr}->addstr(0, 0, "Fixed string");
....your own draw stuff....
$this->{-windowscr}->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 generic_focus() from
# Curses::UI::Common.
#
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....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:
- -parent <parent object>
-
This option specifies parent of the object. This parent is the object (Curses::UI, Window, Widget(descendant), etc.) in which the widget is drawn.
- -border <0 or 1>
-
Each widget can be drawn with or without a border. To enable the border use a true value (1) and to disable it use a false value (0). The default is not to use a border.
- -sbborder <0 or 1>
-
If no border is used, a square bracket border may be used. This is a border which is constructed from '[' and ']' characters. This type of border is especially useful for single line widgets (like text entries and popup boxes). A square bracket border can only be enabled if -border is false. The default is not to use a square bracket border.
POSITIONING:
+---------------------------------------------------+
| parent ^ |
| | |
| y |
| | |
| v |
| ^ |
| | |
| padtop |
| | |
| v |
| +- TITLE -------+ |
| | widget ^ | |
| | | | |
| | | | |
|<--x--><--padleft-->|<----width---->|<--padright-->|
| | | | |
| | | | |
| | height | |
| | v | |
| +---------------+ |
| ^ |
| | |
| padbottom |
| | |
| v |
+---------------------------------------------------+- -x <value>
-
The x-position of the widget, relative to the parent. The default is 0.
- -y <value>
-
The y-position of the widget, relative to the parent. The default is 0.
- -width <value>
-
The width of the widget. If the width is undefined or -1, the maximum available width will be used. By default the widget will use the maximum available width.
- -height <value>
-
The height of the widget. If the height is undefined or -1, the maximum available height will be used. By default the widget will use the maximum available height.
PADDING:
- -pad <value>
- -padtop <value>
- -padbottom <value>
- -padleft <value>
- -padright <value>
-
With -pad you can specify the default padding outside the widget (the default value for -pad is 0). Using one of the -pad... options that have a direction in them, you can override the default padding.
- -ipad <value>
- -ipadtop <value>
- -ipadbottom <value>
- -ipadleft <value>
- -ipadright <value>
-
These are almost the same as the -pad... options, except these options specify the padding _inside_ the widget. Normally the available effective drawing area for a widget will be the complete area if no border is used or else the area within the border.
TITLE:
Remark:
A title is drawn in the border of a widget. So a title will only be available if -border is true.
- -title <text>
-
The text to use for the title. If the text is longer then the available width, it will be clipped.
- -titlereverse <0 or 1>
-
The title can be drawn in normal or in reverse type. If -titlereverse is true, the text will be drawn in reverse type. The default is to use reverse type.
- -titlefullwidth <0 or 1>
-
If -titlereverse is true, the title can be stretched to fill the complete width of the widget by giving -titlefullwidth a true value. By default this option is disabled.
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 loction indicators". But since they look so much like scrollbars I decided I could get away with this naming convention.
- -vscrollbar <0, 1, 'left' or 'right'>
-
If -vscrollbar has a true value, a vertical scrollbar will be drawn by the widget. If this true value happens to be "left", the scrollbar will be drawn on the left side of the widget. In all other cases it will be drawn on the right side. The default is not to draw a vertical scrollbar.
For widget programmers: To control the scrollbar, the widget data -vscrolllen (the total length of the content of the widget) and -vscrollpos (the current position in the document) should be set. If Curses::UI::Widget::draw is called, the scrollbar will be drawn.
- -hscrollbar <0, 1, 'top' or 'bottom'>
-
If -hscrollbar has a true value, a horizontal scrollbar will be drawn by the widget. If this true value happens to be "top", the scrollbar will be drawn at the top of the widget. In all other cases it will be drawn at the bottom. The default is not to draw a horizontal scrollbar.
For widget programmers: To control the scrollbar, the widget data -hscrolllen (the maximum width of the content of the widget) and -hscrollpos (the current horizontal position in the document) should be set. If Curses::UI::Widget::draw is called, the scrollbar will be drawn.
METHODS
- new (<list of options>)
-
Create a new Curses::UI::Widget instance.
- layout ()
-
Layout the widget. Compute the size the widget needs and see if it fits. Create the curses windows that are needed for the widget (the border and the effective drawing area).
- draw (<0 or 1>)
-
Draw the Curses::UI::Widget. If the argument to draw is true, the screen will not update after drawing.
- title (<text>)
-
Change the title that is shown in the border of the widget to <text>.
- width ()
- height ()
-
These methods return the total width and height of the widget. This is the space that the widget itself uses plus the space that is used by the outside padding.
- borderwidth ()
- borderheight ()
-
These methods return the width and the height of the border of the widget.
- screenwidth ()
- screenheight ()
-
These methods return the with and the height of the effective drawing area of the widget. This is the area where the draw() method of a widget may draw the contents of the widget (BTW: the curses window that is associated to this drawing area is $this->{-windowscr}).
- width_by_windowscrwidth (<needed width>, <%arguments>)
- height_by_windowscrheight (<needed height>, <%arguments>)
-
These methods are exported by this module. These can be used in child classes to easily compute the total width/height the widget needs in relation to the needed width/height of the effective drawing area ($this->{-windowscr}). The %arguments are the arguments that will be used to create the widget. So if we want a widget that has a drawing area height of 1 and that has a border, the -height option can be computed using something like:
my $height = height_by_windowscrheight(1, -border => 1);
SEE ALSO
AUTHOR
Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.
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.