NAME

Selkie::Widget::GradientFill - A pane filled edge to edge with a colour ramp

SYNOPSIS

use Selkie::Gradient;
use Selkie::Widget::GradientFill;
use Selkie::Sizing;

# A two-row dusk fade under a header.
my $band = Selkie::Widget::GradientFill.new(
    gradient => Gradient.vertical(0x2E1A4A, 0x1A1A2E),
    sizing   => Sizing.fixed(2),
);
$root.add($band);

# Re-theme it later — marks dirty, repaints on the next frame.
$band.set-gradient(Gradient.vertical($theme.accent, $theme.bg-base));

DESCRIPTION

The whole widget is one call to gradient-fill over its own plane: a rectangle of colour, no text, no focus, no input. Use it for decorative bands, dividers, accent strips, and the empty half of a split.

The gradient's corners are collapsed for the widget's actual size on every render (see Selkie::Gradient's for-region), so the same Gradient value works whether the layout gives the widget twenty rows or one.

This is not a backdrop

A GradientFill sibling does not appear behind another widget's text. Every Selkie widget owns its own notcurses plane, gradients are written into the cells of one plane, and the widget above wins each cell it covers — including the blank ones, because its base cell is opaque too. Putting a GradientFill and a Text in the same VBox gives you a gradient band and a text row, not text on a gradient.

For text on a gradient, call gradient-fill at the top of your own widget's render and putstr over it — same plane, one pass. That idiom, and the see-through-widget alternative, are written up in Selkie::Gradient.

Glyphs and the foreground ramp

egc is what gets stamped into every cell, and it defaults to a space, which is what you want for a background wash. Set it to a block or a texture glyph and the cell's foreground becomes the visible colour — at which point you want fg-gradient as well, since without one the glyphs are drawn in the terminal's default colour:

# A ramp drawn as coloured blocks rather than as a background.
my $bar = Selkie::Widget::GradientFill.new(
    gradient    => Gradient.uniform($theme.base.bg),   # behind the blocks
    fg-gradient => Gradient.horizontal(0x2E1A4A, 0xC04A2E),
    egc         => '█',
    sizing      => Sizing.fixed(1),
);

Keep egc to a single column — it is stamped into every cell, so a double-width grapheme misaligns the whole pane.

EXAMPLES

An accent strip down the side of a layout

A one-column widget is a degenerate region for notcurses, and would paint nothing at all without the corner collapse render applies.

my $row = Selkie::Layout::HBox.new(sizing => Sizing.flex);
$row.add: Selkie::Widget::GradientFill.new(
    gradient => Gradient.vertical(0xC04A2E, 0x2E1A4A),
    sizing   => Sizing.fixed(1),
);
$row.add: $content;

Driving it from the store

Like any widget: subscribe, then swap the value in the callback.

$app.store.subscribe-with-callback(
    'banner-accent',
    -> $s { $s.get-in('theme', 'accent') // 0x4A2E6E },
    -> UInt $accent {
        $band.set-gradient(Gradient.horizontal($accent, 0x1A1A2E));
    },
    $band,
);

SEE ALSO

• Selkie::Gradient — the Gradient value type and the three painting subs

• Selkie::Widget — the role, and the base-style / base-egc see-through hooks

• Selkie::Alpha — why a gradient cannot be faded with alpha

has Selkie::Gradient::Gradient $.gradient

The background colour ramp painted across the whole pane. Required.

has Selkie::Gradient::Gradient $.fg-gradient

An optional foreground ramp — the colour egc is drawn in. Left undefined the glyphs take the terminal's default colour, which is invisible for the default blank egc and almost certainly not what you want for any other.

has Str $.egc

The grapheme stamped into every cell. A space (the default) makes the pane a pure background wash. Must be a single column wide.

method new

method new(
    *%args
) returns Selkie::Widget::GradientFill

Constructor. Defaults focusable to False — the widget is decorative and takes no input. Accepts :gradient (required), :fg-gradient, :egc, and the usual Selkie::Widget attributes.

method set-gradient

method set-gradient(
    Selkie::Gradient::Gradient:D $gradient
) returns Nil

Replace the background ramp and mark the widget dirty.

method set-fg-gradient

method set-fg-gradient(
    Selkie::Gradient::Gradient $fg-gradient
) returns Nil

Replace the foreground ramp and mark the widget dirty. Pass the bare Gradient type object to clear it back to the terminal default.

method set-egc

method set-egc(
    Str:D $egc
) returns Nil

Replace the per-cell grapheme and mark the widget dirty.