Curses::UI::Widget(3)

📦

version 0.9609 · 6 versions

0.9609 · alpine 3.24 (latest)
0.9609 · arch rolling
0.9609 · fedora 43
0.9609 · fedora 44
0.9609 · ubuntu resolute, ubuntu stonking
0.9609 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

okay so bestie, welcome to Curses::UI::Widget(3) from the User Contributed Perl Documentation section — yes, the manual name is Curses::UI::Widget(3) and this page is literally the blueprint for every widget under the Curses::UI sun 🌈💅

💖 NAME 💖

Curses::UI::Widget — the base class for all widgets. that's the whole vibe: it's the parent of the widget family tree 🫶

🧬 CLASS HIERARCHY 🧬

Curses::UI::Widget - base class

✨ SYNOPSIS ✨

okay so real talk: 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 — plot twist, bestie 😭🎀

🌟 GENERAL 🌟

-parent < OBJECTREF > — this option specifies the parent of the object. this parent is the object (Curses::UI, Window, Widget(descendant), etc.) in which the widget is drawn 🫶
-intellidraw < BOOLEAN > — if BOOLEAN has a true value (which is the default), the intellidraw method (see below) will be supported. this option is mainly used in widget building ✨
-userdata < SCALAR > — this option specifies 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 💌
-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 🎀
-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                   |
        +---------------------------------------------------+

-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 > — set the title of the widget to TEXT. if the text is longer than the available width, it will be clipped ✂️
-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 🔄
-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 😭🌀

-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 👩‍💻✨

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

-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 💖
-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 ✨

new ( OPTIONS ) — Makes a brand-new Curses::UI::Widget instance using the options in HASH. New widget, who dis? 💅
layout ( ) — Lays the widget out. It computes the size the widget needs and checks if it fits. Then it creates the curses windows that are needed for the widget: the border and the effective drawing area. ✨
draw ( BOOLEAN ) — Draws 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. 🎀
intellidraw ( ) — If the widget is visible (it’s not hidden and it’s in the window that is currently on top) and if intellidraw is not disabled for it (-intellidraw has a true value), it gets drawn and the curses routine doupdate() is called to update the screen.

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

focus ( ) — Gives 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. No cap. 🫶
focusable ( [BOOLEAN] ) — If BOOLEAN is set to a true value, the widget will be focusable; false will make it unfocusable. If no argument is given, it returns the current state. Vibe check for focus. ⭐
lose_focus ( ) — Makes the current widget lose its focus. It returns the current widget. Bye bestie 👋
modalfocus ( ) — Gives the widget a modal focus, i.e. no other widget can be active till this widget is removed. Main character energy only. 👑
title ( TEXT ) — Changes the title that is shown in the border of the widget to TEXT. Slay that border. 💖
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. Border check ✅
canvaswidth ( ) / canvasheight ( ) — These methods return the width 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}. 🎨
width_by_windowscrwidth ( NEEDWIDTH, OPTIONS ) / height_by_windowscrheight ( NEEDHEIGHT, OPTIONS ) — These methods are exported by this module. They 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);

generic_focus ( BLOCKTIME, CTRLKEYS, CURSOR, PRECALLBACK ) — For most widgets, the generic_focus method will be enough to handle focusing. This method does 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 stay at the widget by returning the widget instance itself. Example:

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

process_bindings ( KEY ) — It goes like this:

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 a corresponding ROUTINE. If the ROUTINE can be found, it will check if its 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. 💅

clear_binding ( ROUTINE ) — Clears all keybindings for routine ROUTINE. Ghosted. 💀
set_routine ( ROUTINE, VALUE ) — Sets 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. 🎀
set_binding ( ROUTINE, KEYLIST ) — Binds 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. 🔥
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.
clear_event ( EVENT ) — This will clear the callback for event EVENT. Event: cancelled 🙈
run_event ( EVENT ) — This routine will check if a callback for the event EVENT is set and if it is a code reference. If this is the case, it will run the code and return its return value. 🏃‍♀️
onFocus ( CODEREF ) — This method can be used to set the -onfocus event handler (see above) after initialization of the widget. ✨
onBlur ( CODEREF ) — This method can be used to set the -onblur event handler (see above) after initialization of the widget. Blurred, but make it cute. 🦋
parentwindow ( ) — Returns the parent window for the widget or undef if no parent window can be found (this should not happen). 🫶
in_topwindow ( ) — Returns true if the widget is in the window that is currently on top. Top-window icon behavior. 👑
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. Your data, your rules. 💜
beep_on ( ) — This sets the data member $this->{-nobeep} of the class instance to a false value. Beeps are back on the menu. 🔔
beep_off ( ) — This sets the data member $this->{-nobeep} of the class instance to a true value. Silence, bestie. 🤫
dobeep ( ) — This will call the curses beep() routine, but only if -nobeep is false. Beep beep 🚗

Okay bestie, here's the tea: this is a basic framework for making a brand-new widget. You do not have to follow this framework exactly. The real vibe check is simple — as long as your widget has the methods new(), layout(), draw() and focus(), it can be used in Curses::UI. Periodt. 💅

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

That's the whole skeleton, and honestly it's giving main-character energy: routines get names, bindings wire keypresses to those routines, an empty-string keypress is the default binding for anything not handled by another binding, and new() is where optional and forced arguments live. The comments in the code are doing a lot of the lore, so read them like they're the group chat receipts. 🫶

👀 SEE ALSO 👀

Curses::UI — go peek, bestie, it's the parent vibe.

💖 AUTHOR 💖

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.

💖 Signing off from Curses::UI::Widget(3) — source/version perl v5.42.2, dated 2023-07-03. Bye bestie! 💅✨

📦 where this page comes from

alpine 3.24: perl-curses-ui-doc 0.9609-r3 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms