/ 
Term-Fabulous-0.01
/ Term::Fabulous::Render::Rectangle

NAME

Term::Fabulous::Render::Rectangle - Paint widget backgrounds

SYNOPSIS

# Composed by Term::Fabulous::Render; called from draw for every
# rectangle render command:
$ui->render_rectangle( $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 rectangle render commands Clay emits for widget backgrounds (background_color). Read it if you write your own UI class or want to know exactly how backgrounds are painted and blended.

METHODS

render_rectangle

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

Paints the cells of the command's bounding box that lie inside the command's clip rect (see "clip_rect" in Term::Fabulous::Render) in the command's background color. It also records the resulting background of every painted cell in $buffer, an array reference of rows of attributes indexed $buffer->[$y][$x], so that text and borders drawn on top later in the frame know the background below them.

An opaque color (alpha 255) fills the cells with spaces, using the target's fill_row. A translucent color (alpha 1 to 254) is blended with the background $buffer holds for each cell ("blended_bg_attr" in Term::Fabulous::Render::Attr), and then one of two things happens, depending on the widget's glyphs_show_through ("glyphs_show_through" in Term::Fabulous::Widget):

  • Off (the default, also when $widget is not a Term::Fabulous::Widget): the cells are covered with spaces in the blended colors, one fill_row per run of equal color.

  • On: every cell is read back from the target (painted_cell) and repainted with the glyph found there, its foreground tinted with the same color ("blended_fg_attr" in Term::Fabulous::Render::Attr); a cell holding nothing or a space becomes a space. The cells a wide glyph covers are not touched.

When $widget is a Term::Fabulous::Widget whose reverse_video method returns true (a pressed Term::Fabulous::Widget::Button, see "reverse_video" in Term::Fabulous::Widget::Button), every background attribute gets the TB_REVERSE flag. The text and borders painted on top later take their background from $buffer, flag included, so the whole widget is shown with swapped colors.

Clay never emits a rectangle for a color with alpha 0.

$command is a Clay render command hash (see "RENDER COMMANDS" in Clay::XS); $widget is the widget it belongs to.

REQUIRED METHODS

The consuming class provides cell_target, which returns the cell target the background is painted into (its fill_row, set_cell, extend_cell and painted_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::Render::Frame.