Ascii.Pieces.WaveText (Ascii v0.3.0)

Copy Markdown View Source

A swell running through a line of text, left to right.

A swell rolls into a line of text from the left, lifts and drops each letter in turn, runs off the right, and the line settles level again. Give it your own text, and shape its swell; its letters take colours one by one, for a heading in your palette.

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): the line starts afresh with them, the swell where play time puts it.

  • text - the line, centred; as many characters as fit in the 36 columns (with spacing, fewer). Default "making waves".
  • amp - rows from the level line to a crest, up to 2.45; 0 is a level line. Default 1.25.
  • wavelength - letters from crest to crest, at least 4 (0 takes the default). Default 18.
  • speed - letters a second the swell travels, at least 0.5 (0 takes the default). Default 8.
  • spacing - blank columns between letters, a whole number. Default 0.
  • settle - true (the default) lets the line lie level between swells; false runs one endless swell.

The line is always 36 by 5.

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, and letter.<n> - the letters, and each by its place in the text from 1, counting every character, spaces too: letter.1, letter.2 and on, so w is letter.7 in "making waves". Wherever the swell has carried a letter, it keeps its colour. letter colours every one without a colour of its own.
  • trail - the dot a letter leaves on the level line as it lifts off, 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, as letter.3.

Screen readers

Ascii.describe/1 reads the text: "wave text: hello". Without text, it gives the piece's name and note.

Example

colours = %{"letter" => "#58a6ff", "letter.1" => "#ff5f6d", "trail" => "#8b949e"}
heading = Ascii.new!("wave-text", options: %{text: "hello", amp: 2, speed: 6}, parts: colours)
{frame, heading} = Ascii.frame(heading, 0.0)

# The first letter in its own colour, the rest in the letters'.
Ascii.part_at(heading, frame, 15, 2)
#=> {"letter.1", "h"}
Ascii.Frame.color_at(frame, 15, 2)
#=> "#ff5f6d"
Ascii.Frame.color_at(frame, 16, 2)
#=> "#58a6ff"

Ascii.describe(heading)
#=> "wave text: hello"
<Ascii.Phoenix.live_player id="heading" piece="wave-text" options={%{text: @title}} parts={%{"letter" => "var(--brand)"}} />

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