# `Ascii.Pieces.BigText`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/big_text.ex#L1)

A block-letter banner with a line shadow and a passing glint.

A banner in a hand-made five-row block font with a drop shadow drawn in
double lines, and a glint that sweeps across now and then: a heading, in
your words and, letter by letter, your colours.

## Options

Give them to `Ascii.new/2` as `options:`, and new ones while it plays
with `Ascii.put_options/2` (or a Phoenix player's `options`): it starts
afresh with the new text, the glint carrying on, being a function of play
time.

  * `text` - the words, in capitals whatever their case. The font has
    `A` to `Z`, `0` to `9`, `.`, `,`, `!`, `?`, `'`, `:`, `-`, `+`, `=`,
    `/`, `_` and the space; any other character is left out. A pixel is
    two columns wide (square, as cells are twice as tall as wide) when
    the text fits, about six letters, and one column when it does not,
    about twelve; past that, it is cut at the frame's edge. Default
    `"hello"`.

The frame is always 66 by 8, the banner centred in it.

## Colours

In one ink, or a gradient, with `:ink` and `:gradient` (see
`Ascii.Ink`); part by part with `:parts` (see `Ascii.Parts`),
`parts: true` taking the colours suggested here:

  * `letter` - the letters' ink, glint and all; and `letter.<n>`, each
    letter by its place in the text from 1, counting every character,
    spaces too (so `w` is `letter.7` in "hello world"). Colours for the
    numbered letters set a heading in your own palette.
  * `shadow` - the double-line shadow, grey.

## Keys and clicks

It takes none: it is a heading, and `Ascii.handle_event/2` ignores
every event. A Phoenix player given `interactive` and `notify` still
tells your LiveView where it was clicked, and on which part
(`Ascii.part_at/4`): which letter, say.

## Screen readers

`Ascii.describe/1` reads the text, its spaces closed up: "big text:
hello". A text of only spaces gives the piece's name and note.

## Example

```elixir
colours = %{"letter.1" => "#3fb950", "letter.2" => "#58a6ff", "shadow" => "#8b949e"}
banner = Ascii.new!("big-text", options: %{text: "ok!"}, parts: colours)
{frame, _banner} = Ascii.frame(banner, 0.0)
frame.palette
#=> [nil, "#3fb950", "#58a6ff", "#8b949e"]

Ascii.describe(banner)
#=> "big text: ok!"
```

```heex
<Ascii.Phoenix.live_player id="heading" piece="big-text" options={%{text: @title}} ink="#ff5f6d,#ffc371" />
```

Ported from `src/pieces/big-text.ts` in bas3line/ascii (MIT).

---

*Consult [api-reference.md](api-reference.md) for complete listing*