Widget...reation(3pm)

✨ NAME ✨

Curses::Widget::Tutorial::Creation — the Widget Creation Tutorial, bestie. This is the one that teaches you how to build your own widget from scratch 💅

---

🌸 POD VERSION 🌸

$Id: Creation.pod,v 0.3 2002/11/04 00:45:06 corliss Exp corliss $

---

🎀 DESCRIPTION 🎀

okay so, creating a custom widget? literally so easy. All you gotta do is make a descendant class of Curses::Widget and define as few as four methods. That's it. That's the whole vibe:

• _conf — Validates configurations options and initialises the internal state/data
• _content — Renders the widget according to the current state
• _cursor — Renders the widget cursor according to the current state
• input_key — Updates the state information according to the passed character input

🦋 BASIC MODULE STRUCTURE 🦋

A decent code template for custom widgets would start with the following (we'll call our new widget MyWidget, main character energy obviously):

package MyWidget;

use strict;
use vars qw($VERSION @ISA);
use Curses;
use Curses::Widget;

($VERSION) = (q$Revision: 0.3 $ =~ /(\d+(?:\.(\d+))+)/);
@ISA = qw(Curses::Widget);

heads up bestie: that use Curses::Widget; statement is doing more than just handing you a base class to inherit methods from — it's also importing standard functions for use in the module. iykyk.

Here's the function tea:

• select_colour — Initialises new colour pairs, and returns the appropriate colour pair number, for use with $wh->attrset(COLOR_PAIR($n)) calls. select_color, the American English spelling, also works.
• scankey — This blocks until a key is pressed, and that key returned.
• textwrap — Splits the text given into lines no longer than the column limit specified.

See the Curses::Widget pod for the specific syntax.

Descendent classes will automatically know the following fields (as used by the new or get/setField methods) — no cap:

• Y — int — Y coordinate of upper left corner of widget
• X — int — X coordinate of upper left corner of widget
• LINES — int — Number of lines in the content area of the widget
• COLUMNS — int — Number of columsn inthe content area
• BORDER — boolean — Whether to surround the widget with a box
• CAPTION — string — Caption to display on top of border
• FOREGROUND — string — Default foreground colour
• BACKGROUND — string — Default background colour
• BORDERCOL — string — Default border foreground colour
• CAPTIONCOL — string — Default caption foreground colour

The colours, if not specified during widget instantiation, will default to the colours in colour pair 0 (the terminal default). Borders will only be drawn if BORDER is true, and that decision is made in the default _border method, not in the draw method. The _caption method also decides internally whether or not to draw itself according to the value of BORDER. ✨

---

💜 METHOD SEMANTICS 💜

The _conf method is called by the class constructor (provided by Curses::Widget, unless you override it here as well). Widget objects should be created with all configuration options passed in a hash ref, like so:

$widget = Curses::Widget::MyWidget->new({
  OPTION1   => $value1,
  OPTION2   => $value2,
  [. . .]
  });

The configuration hash is dereferenced and passed as arguments to the _conf method inside of the new constructor:

$rv = $self->_conf(%$conf);

Because of this, the _conf method should probably begin along these lines:

sub _conf {
  my $self = shift;
  my %conf = (
    OPTION1 => default1,
    OPTION2 => default2,
    [. . .],
    @_
    );
  my $err = 0;

  # Validate and initialise the widget's state
  # and store in the %conf hash

  # Always include the following
  $err = 1 unless $self->SUPER::_conf(%conf);

  return ($err == 0) ? 1 : 0;
}

You should perform any initialisation and validation of the configuration options here. This routine is expected to return a true or false value, depending on whether or not any critical errors were found. A false value will prevent the new constructor from returning an object reference, causing the instantiation request to fail. so yeah, don't fumble that return value fr fr.

The last two lines of code should always be included in this subroutine. The call to the parent class' _conf method stores the final initialised state information in %conf in the object field CONF, after initialising many of the standard colour fields, should they have been left undefined. You can retrieve and update the state information via $self->{CONF}. A copy of that state information will be stored in $self->{OCONF}, and can be restored with a call to reset, a method provided by Curses::Widgets.

The second method you should override is the _content method. This method, as mentioned above, is responsible for rendering the widget according to its state information. This method should handle one arguments:

$widget->_content($cwh);

The argument will be a window handle to the content area of the widget. You should always layout your widget with the upper left corner as (0, 0), since the draw method is responsible for allocating any extra space needed for borders and captions. 👑

If your widget doesn't support borders and/or captions you can do one of two things: override those methods (_border and _caption) to immediately return without doing anything, or override the draw method to exclude those calls. Typically, the former method of handling this would be preferred.

The third method you need to override is the _cursor method. This accepts the same window handle as the _content method. The default draw method will only call this method if it was called with a true active argument.

Neither of these two methods will need to allocate, refresh, or destroy window handles, just print the content. The windows will already be erased and initialised to specified foreground/background pairs, and those settings saved via the _save method. If at any time you need to reset the window handle's current cursor back to those settings you can call _restore:

$self->_restore($dwh);

In fact, in order to make the state of the window handle more predictable for descendent classes you should probably call _restore at the end of each of these methods. trust, it's the move.

The final method that should be overridden is the input_key method. This expects a single argument, that being the keystroke captured by the keyboard scanning function. It uses that value to update (if it's not rejected) the widget's state information. A rough skeleton for this function would be as follows:

sub input_key {
  my $self = shift;
  my $key = shift;
  my $conf = $self->{CONF};

  # validate/update state information
}

---

🌈 CONCLUSION 🌈

That, in a nutshell, is all there is to creating a custom widget. For a working example which uses the structure noted above, look at the TextField or ButtonSet widgets. Both consist of nothing more than the routines listed above. slay, you're basically a widget dev now 💅✨

---

🎀 HISTORY 🎀

2001/07/07 — First draft. 2002/11/01 — Updated for reworked internals.

---

👑 AUTHOR/COPYRIGHT 👑

(c) 2001 Arthur Corliss (corliss@digitalmages.com),

---

and that's a wrap bestie 🫶 this page came to you courtesy of perl v5.34.0, dated 2022-06-12, filed under Widget...reation(3pm) in the User Contributed Perl Documentation. go build something iconic 💖