/ 
Term-Fabulous-0.05
/ Term::Fabulous::Role::MarkedText

NAME

Term::Fabulous::Role::MarkedText - The spans and highlights of a widget that shows one text

SYNOPSIS

use Object::Pad 0.825;
use Term::Fabulous::Role::MarkedText;
use Term::Fabulous::Text::Marks;
use Term::Fabulous::Widget::Display;

class My::Banner :isa(Term::Fabulous::Widget::Display) :does(Term::Fabulous::Role::MarkedText) {
	field $marks;

	ADJUST :params ( :$text = '' ) {
		$marks = Term::Fabulous::Text::Marks->new( owner => ref($self), text => $text );
	}

	method text_marks () { return $marks }

	method marks_changed ($is_content) {
		$self->mark_changed;    # paint again with the new runs
		return;
	}

	method reveal_text ( $key, $offset ) { return [ $self, 0 ] }
	method natural_size () { return ( length $marks->text, 1 ) }
	method paint () { ... }    # with $marks->runs( theme => $self->drawing_theme )
}

DESCRIPTION

Term::Fabulous::Widget::Text and Term::Fabulous::Widget::CodeBlock show one text each, with spans that style it and highlights that a search paints over them. Both keep these in a Term::Fabulous::Text::Marks and present the same methods through this role, which also answers Term::Fabulous::Role::Searchable for the one text (its key is undef). A widget that composes it provides "text_marks", "marks_changed" and "reveal_text", which differs from widget to widget.

The marks are those of Term::Fabulous::Text::Marks; this role handles the spans and highlights; the widget handles its links itself.

REQUIRED METHODS

text_marks

method text_marks () { return $marks }

The Term::Fabulous::Text::Marks of the text the widget shows.

marks_changed

method marks_changed ($is_content) { ... }

Called after the role changed the marks: $is_content is 1 after the spans changed, 0 after the highlights did. The widget drops what it made from the old marks (its runs) and makes the next frame paint again (a Text drops its runs and bumps the revision of Clay::UI::Revision; a CodeBlock, like the SYNOPSIS, calls mark_changed).

reveal_text

method reveal_text ( $key, $offset ) { ... }

The reveal_text of "reveal_text" in Term::Fabulous::Role::Searchable: a Text returns [ $self, undef ], a CodeBlock [ $self, $line ] with the line of the offset.

PROVIDED METHODS

spans

my $spans = $widget->spans;              # [ [ $start, $end, \%style ], ... ]
$widget->spans( [ [ 0, 4, 'bold' ] ] );

Accessor: the spans (a copy), or replaces them and returns the new ones. See "set_spans" in Term::Fabulous::Text::Marks for the checks.

stylize

$widget->stylize( 'underline', 7, 17 );
$widget->stylize('dim');                 # the whole text

Appends a span from $start (default 0) up to $end (default the end of the text). Returns the widget.

clear_spans

Removes every span. Returns the widget.

highlights

my $highlights = $widget->highlights;
$widget->highlights( [ [ 3, 5, 'on accent' ] ] );

Accessor for the highlights, painted over the spans; setting them does not change "content_revision".

clear_highlights

Removes every highlight. Returns the widget.

content_revision

The "content_revision" in Term::Fabulous::Text::Marks: it grows with every change of the text, the spans (and a text's links and markup), never with the highlights.

search_texts, search_revision, highlight_text, clear_text_highlights

The methods of Term::Fabulous::Role::Searchable for the one text: its key is undef, its revision is "content_revision", and highlight_text sets "highlights". search_serial comes from "search_serial" in Term::Fabulous::Role::Searchable.

SEE ALSO

Term::Fabulous::Text::Marks, Term::Fabulous::Role::Searchable, Term::Fabulous::Widget::Text, Term::Fabulous::Widget::CodeBlock.