Selkie.git | docs/api/ | Selkie--Widget--GradientFill.md

---

NAME
====

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

SYNOPSIS
========

```raku
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](Selkie--Gradient.md)'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](Selkie--Gradient.md).

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:

```raku
# 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.

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

```raku
$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](Selkie--Gradient.md) — the `Gradient` value type and the three painting subs

  * [Selkie::Widget](Selkie--Widget.md) — the role, and the `base-style` / `base-egc` see-through hooks

  * [Selkie::Alpha](Selkie--Alpha.md) — 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

```raku
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

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

Replace the background ramp and mark the widget dirty.

### method set-fg-gradient

```raku
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

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

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