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

FreeBSD Manual Pages

  
 
  

home | help
Curses::UI::Widget(3) User Contributed Perl DocumentationCurses::UI::Widget(3)

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:
       o   -parent < OBJECTREF >

	   This	option specifies parent	of the object. This parent is the
	   object (Curses::UI, Window, Widget(descendant), etc.)  in which the
	   widget is drawn.

       o   -intellidraw	< BOOLEAN >

	   If BOOLEAN has a true value (which is the default), the intellidraw
	   method (see below) will be suported.	This option is mainly used in
	   widget building.

       o   -userdata < SCALAR >

	   This	option specifies a user	data that can be retrieved with	the
	   userdata() method.  It is useful to store application's internal
	   data	that otherwise would not be accessible in callbacks.

       o   -border < BOOLEAN >

	   Each	widget can be drawn with or without a border. To enable	the
	   border use a	true value and to disable it use a false value for
	   BOOLEAN. The	default	is not to use a	border.

       o   -sbborder < BOOLEAN >

	   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		    |
	+---------------------------------------------------+

       o   -x <	VALUE >

	   The x-position of the widget, relative to the parent. The default
	   is 0.

       o   -y <	VALUE >

	   The y-position of the widget, relative to the parent. The default
	   is 0.

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

       o   -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:
       o   -pad	< VALUE	>

       o   -padtop < VALUE >

       o   -padbottom <	VALUE >

       o   -padleft < VALUE >

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

       o   -ipad < VALUE >

       o   -ipadtop < VALUE >

       o   -ipadbottom < VALUE >

       o   -ipadleft < VALUE >

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

       o   -title < TEXT >

	   Set the title of the	widget to TEXT.	If the text is longer then the
	   available width, it will be clipped.

       o   -titlereverse < BOOLEAN >

	   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.

       o   -titlefullwidth < BOOLEAN >

	   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 location indicators".  But since they look
       so much like scrollbars I decided I could get away with this naming
       convention.

       o   -vscrollbar < VALUE >

	   VALUE can be	'left',	'right', another true value or false.

	   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.

       o   -hscrollbar < VALUE >

	   VALUE can be	'top', 'bottom', another true value or false.

	   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.

   EVENTS
       o   -onfocus < CODEREF >

	   This	sets the onFocus event handler for the widget.	If the widget
	   gets	the focus, the code in CODEREF will be executed. It will get
	   the widget reference	as its argument.

       o   -onblur < CODEREF >

	   This	sets the onBlur	event handler for the widget.  If the widget
	   loses the focus, the	code in	CODEREF	will be	executed. It will get
	   the widget reference	as its argument.

METHODS
       o   new ( OPTIONS )

	   Create a new	Curses::UI::Widget instance using the options in HASH.

       o   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).

       o   draw	( BOOLEAN )

	   Draw	the Curses::UI::Widget.	If BOOLEAN is true, the	screen will
	   not update after drawing. By	default	this argument is false,	so the
	   screen will update after drawing the	widget.

       o   intellidraw ( )

	   If the widget is visible (it	is not hidden and it is	in the window
	   that	is currently on	top) and if intellidraw	is not disabled	for it
	   (-intellidraw has a true value) it is drawn and the curses routine
	   doupdate() will be called to	update the screen.

	   This	is useful if you change	something in a widget and want it to
	   update its state. If	you simply call	draw() and doupdate()
	   yourself, then the widget will also be drawn	if it is on a window
	   that	is currently not on top. This would result in the widget being
	   drawn right through the contents of the window that is currently on
	   top.

       o   focus ( )

	   Give	focus to the widget. In	Curses::UI::Widget, this method
	   immediately returns,	so the widget will not get focused.  A derived
	   class that needs focus, must	override this method.

       o   focusable ( [BOOLEAN] )

	   If BOOLEAN is set to	a true value the widget	will be	focusable,
	   false will make it unfocusable. If not argument is given, it	will
	   return the current state.

       o   lose_focus (	)

	   This	method makes the current widget	lose it's focus.  It returns
	   the current widget.

       o   modalfocus (	)

	   Gives the widget a modal focus, i.e.	no other widget	can be active
	   till	this widget is removed.

       o   title ( TEXT	)

	   Change the title that is shown in the border	of the widget to TEXT.

       o   width ( )

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

       o   borderwidth ( )

       o   borderheight	( )

	   These methods return	the width and the height of the	border of the
	   widget.

       o   canvaswidth ( )

       o   canvasheight	( )

	   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->{-canvasscr}).

       o   width_by_windowscrwidth ( NEEDWIDTH,	OPTIONS	)

       o   height_by_windowscrheight ( NEEDHEIGHT, OPTIONS )

	   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->{-canvasscr}). The OPTIONS contains the
	   options 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);

       o   generic_focus ( BLOCKTIME, CTRLKEYS,	CURSOR,	PRECALLBACK )

	   For most widgets the	generic_focus method will be enough to handle
	   focusing. This method will do the following:

	   It starts a loop for	reading	keyboard input from the	user.  At the
	   start of this loop the PRECALLBACK is called. This callback can for
	   example be used for layouting the widget. Then, the widget is
	   drawn.

	   Now a key is	read or	if the DO_KEY:<key> construction was used, the
	   <key> will be used as if it was read	from the keyboard (you can
	   find	more on	this construction below). If the DO_KEY:<key>
	   construction	was not	used, a	key is read using the get_key method
	   which is in Curses::UI::Common.  The	arguments BLOCKTIME, CTRLKEYS
	   and CURSOR are passed to get_key.

	   Now the key is checked. If the value	of the key is -1, get_key did
	   not read a key at all. In that case,	the program will go back to
	   the start of	the loop.

	   As soon as a	key is read, this key will be handed to	the
	   process_bindings method (see	below).	The returnvalue	of this	method
	   (called RETURN from now on) will be used to determine what to do
	   next. We have the following cases:

	   * RETURN matches DO_KEY:<key>

	   The <key> is	extracted from RETURN. The loop	is restarted and <key>
	   will	be used	as if it was entered using the keyboard.

	   * RETURN is a CODE reference

	   RETURN will be returned to the caller of generic_focus.  This will
	   have	the widget lose	its focus. The caller then can execute the
	   code.

	   * RETURN is a SCALAR	value

	   RETURN will be returned to the caller of generic_focus.  This will
	   have	the widget lose	its focus.

	   * anything else

	   The widget will keep	its focus. The loop will be restarted all over
	   again. So, if you are writing a binding routine for a widget, you
	   can have the	focus to stay at the widget by returning the widget
	   instance itself. Example:

	       sub myroutine() {
		   my $this = shift;
		   ....	do your	thing ....
		   return $this;
	       }

       o   process_bindings ( KEY )

	   KEY -> maps via binding to -> ROUTINE -> maps to -> VALUE

	   This	method will try	to find	out if there is	a binding defined for
	   the KEY. If no binding is found, the	method will return the widget
	   object itself.  If a	binding	is found, the method will check	if
	   there is an corresponding ROUTINE. If the ROUTINE can be found it
	   will	check if it's VALUE is a code reference. If it is, the code
	   will	be executed and	the returnvalue	of this	code will be returned.
	   Else	the VALUE will directly	be returned.

       o   clear_binding ( ROUTINE )

	   Clear all keybindings for routine ROUTINE.

       o   set_routine ( ROUTINE, VALUE	)

	   Set the routine ROUTINE to the VALUE. The VALUE may either be a
	   scalar value	or a code reference. If	process_bindings (see above)
	   sees	a scalar value,	it will	return this value. If it sees a
	   coderef, it will execute the	code and return	the returnvalue	of
	   this	code.

       o   set_binding ( ROUTINE, KEYLIST )

	   Bind	the keys in the	list KEYLIST to	the ROUTINE. If	you use	an
	   empty string	for a key, then	this routine will become the default
	   routine (in case no other keybinding	could be found). This is for
	   example used	in the TextEditor widget.

       o   set_event ( EVENT, [CODEREF]	)

	   This	routine	will set the callback for event	EVENT to CODEREF. If
	   CODEREF is omitted or undefined, the	event will be cleared.

       o   clear_event ( EVENT )

	   This	will clear the callback	for event EVENT.

       o   run_event ( EVENT )

	   This	routine	will check if a	callback for the event EVENT is	set
	   and if is a code reference. If this is the case, it will run	the
	   code	and return its return value.

       o   onFocus ( CODEREF )

	   This	method can be used to set the -onfocus event handler (see
	   above) after	initialization of the widget.

       o   onBlur ( CODEREF )

	   This	method can be used to set the -onblur event handler (see
	   above) after	initialization of the widget.

       o   parentwindow	( )

	   Returns this	parent window for the widget or	undef if no parent
	   window can be found (this should not	happen).

       o   in_topwindow	( )

	   Returns true	if the widget is in the	window that is currently on
	   top.

       o   userdata ( [	SCALAR ] )

	   This	method will return the user internal data stored in this
	   widget.  If a SCALAR	parameter is specified it will also set	the
	   current user	data to	it.

       o   beep_on ( )

	   This	sets the data member $this->{-nobeep} of the class instance to
	   a false value.

       o   beep_off ( )

	   This	sets the data member $this->{-nobeep} of the class instance to
	   a true value.

       o   dobeep ( )

	   This	will call the curses beep() routine, but only if -nobeep is
	   false.

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.

perl v5.24.1			  2011-09-02		 Curses::UI::Widget(3)

NAME | CLASS HIERARCHY | SYNOPSIS | STANDARD OPTIONS | WIDGET-SPECIFIC OPTIONS | METHODS | WIDGET STRUCTURE | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Curses::UI::Widget&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help