/ 
Term-Fabulous-0.01
/ Term::Fabulous::Render::Text

NAME

Term::Fabulous::Render::Text - Paint lines of text

SYNOPSIS

# Composed by Term::Fabulous::Render; called from draw for every
# text render command:
$ui->render_text( $command, $widget, $buffer );

DESCRIPTION

Most programs never use this module directly, and neither do widgets of your own. It is one of the roles Term::Fabulous::Render is made of, and it paints the text render commands Clay emits for Term::Fabulous::Widget::Text widgets. Clay breaks a widget's text into lines; each text command is one line. Read it if you write your own UI class or want to know exactly how text is drawn.

METHODS

render_text

$ui->render_text( $command, $widget, $buffer );

Paints one line of text, starting at the top-left cell of the command's bounding box, in the command's text color with the style bits of the widget (bold, italic, underline; see "style_attrs" in Term::Fabulous::Widget::Text), when the widget has any:

  • The text (stringContents, a character string) has its control characters replaced (see "sanitize_text" in Term::Fabulous::Unicode) and is split into grapheme clusters.

  • Every cluster advances by the number of columns termbox2 uses for it (see "cluster_columns" in Term::Fabulous::Unicode), so measuring and drawing agree.

  • The line ends before the first cluster that would cross the right edge of the bounding box or of the clip area. Clusters left of the clip area are not painted but still advance.

  • The background of each cell is the one recorded in $buffer (an array reference of rows of attributes, $buffer->[$y][$x]) by whatever was painted there before in this frame, or the terminal default.

  • When the widget has a line_styles method (a Term::Fabulous::Widget::RichText), it is asked for the runs of the line, $widget->line_styles( $offset, $length ) with the command's stringOffset (where the line starts in the widget's text, in characters) and the line's length, and each cluster is painted in the look of the run its first character lies in: the run's style bits set and cleared on the widget's, its text color in place of the command's, and its background in place of the one recorded in $buffer, which is updated to it. See "line_styles" in Term::Fabulous::Widget::RichText for the runs.

The line is skipped when its row lies outside the clip area. Segmented lines are cached by their text (the cache is emptied when it reaches 4096 entries), because texts rarely change between frames.

REQUIRED METHODS

The consuming class provides cell_target, which returns the cell target the text is painted into (its set_cell and extend_cell are called; see "CELL TARGET" in Term::Fabulous::Render), and clip_rect (from Term::Fabulous::Render, see "clip_rect" in Term::Fabulous::Render).

SEE ALSO

Term::Fabulous::Render, Term::Fabulous::Widget::Text, Term::Fabulous::Unicode.