NAME

Prima::TextView - rich text browser widget

SYNOPSIS

 use strict;
 use warnings;
 use Prima qw(TextView Application);

 my $w = Prima::MainWindow-> create(
     name => 'TextView example',
 );

 my $t = $w->insert(TextView =>
     text     => 'Hello from TextView!',
     pack     => { expand => 1, fill => 'both' },
 );

 # Create a single block that renders all the text using the default font
 my $tb = tb::block_create();
 my $text_width_px = $t->get_text_width($t->text);
 my $font_height_px = $t->font->height;
 $tb->[tb::BLK_WIDTH]  = $text_width_px;
 $tb->[tb::BLK_HEIGHT] = $font_height_px;
 $tb->[tb::BLK_BACKCOLOR] = cl::Back;
 $tb->[tb::BLK_FONT_SIZE] = int($font_height_px) + tb::F_HEIGHT;
 # Add an operation that draws the text:
 push @$tb, tb::text(0, length($t->text), $text_width_px);

 # Set the markup block(s) and recalculate the ymap
 $t->{blocks} = [$tb];
 $t->recalc_ymap;

 # Additional step needed for horizontal scroll as well as per-character
 # selection:
 $t->paneSize($text_width_px, $font_height_px);

 run Prima;

DESCRIPTION

Prima::TextView accepts blocks of formatted text, and provides basic functionality - scrolling and user selection. The text strings are stored as one large text chunk, available by the "::text" and "::textRef" properties. A block of a formatted text is an array with fixed-length header and the following instructions.

A special package "tb::" provides the block constants and simple functions for text block access.

Capabilities

Prima::TextView is mainly the text block functions and helpers. It provides function for wrapping text block, calculating block dimensions, drawing and converting coordinates from (X,Y) to a block position. Prima::TextView is centered around the text functionality, and although any custom graphic of arbitrary complexity can be embedded in a text block, the internal coordinate system is used ( TEXT_OFFSET, BLOCK ), where TEXT_OFFSET is a text offset from the beginning of a block and BLOCK is an index of a block.

The functionality does not imply any text layout - this is up to the class descendants, they must provide they own layout policy. The only policy Prima::TextView requires is that blocks' BLK_TEXT_OFFSET field must be strictly increasing, and the block text chunks must not overlap. The text gaps are allowed though.

A text block basic drawing function includes change of color, backColor and font, and the painting of text strings. Other types of graphics can be achieved by supplying custom code.

block_draw CANVAS, BLOCK, X, Y: The "block_draw" draws BLOCK onto CANVAS in screen coordinates (X,Y). It can be used not only inside begin_paint/end_paint brackets; CANVAS can be an arbitrary "Prima::Drawable" descendant.
block_walk BLOCK, %OPTIONS: Cycles through block opcodes, calls supplied callbacks on each.

Coordinate system methods

Prima::TextView employs two its own coordinate systems: (X,Y)-document and (TEXT_OFFSET,BLOCK)-block.

The document coordinate system is isometric and measured in pixels. Its origin is located into the imaginary point of the beginning of the document ( not of the first block! ), in the upper-left pixel. X increases to the right, Y increases down. The block header values BLK_X and BLK_Y are in document coordinates, and the widget's pane extents ( regulated by "::paneSize", "::paneWidth" and "::paneHeight" properties ) are also in document coordinates.

The block coordinate system in an-isometric - its second axis, BLOCK, is an index of a text block in the widget's blocks storage, "$self->{blocks}", and its first axis, TEXT_OFFSET is a text offset from the beginning of the block.

Below different coordinate system converters are described

screen2point, point2screen X, Y: "screen2point" accepts (X,Y) in the screen coordinates ( O is a lower left widget corner ), returns (X,Y) in document coordinates ( O is upper left corner of a document ). "point2screen" does the reverse.
xy2info X, Y: Accepts (X,Y) is document coordinates, returns (TEXT_OFFSET,BLOCK) coordinates, where TEXT_OFFSET is text offset from the beginning of a block ( not related to the big text chunk ) , and BLOCK is an index of a block.
info2xy TEXT_OFFSET, BLOCK: Accepts (TEXT_OFFSET,BLOCK) coordinates, and returns (X,Y) in document coordinates of a block.
text2xoffset TEXT_OFFSET, BLOCK: Returns X coordinate where TEXT_OFFSET begins in a BLOCK index.
info2text_offset: Accepts (TEXT_OFFSET,BLOCK) coordinates and returns the text offset with regard to the big text chunk.
text_offset2info TEXT_OFFSET: Accepts big text offset and returns (TEXT_OFFSET,BLOCK) coordinates
text_offset2block TEXT_OFFSET: Accepts big text offset and returns BLOCK coordinate.

Text selection

The text selection is performed automatically when the user selects a text region with a mouse. The selection is stored in (TEXT_OFFSET,BLOCK) coordinate pair, and is accessible via the "::selection" property. If its value is assigned to (-1,-1,-1,-1) this indicates that there is no selection. For convenience the "has_selection" method is introduced.

Also, "get_selected_text" returns the text within the selection (or undef with no selection ), and "copy" copies automatically the selected text into the clipboard. The latter action is bound to "Ctrl+Insert" key combination.

A block with TEXT_OFFSET set to -1 will be treated as not containing any text, and therefore will not be able to get selected.

Event rectangles

Partly as an option for future development, partly as a hack a concept of 'event rectangles' was introduced. Currently, "{contents}" private variable points to an array of objects, equipped with "on_mousedown", "on_mousemove", and "on_mouseup" methods. These are called within the widget's mouse events, so the overloaded classes can define the interactive content without overloading the actual mouse events ( which is although easy but is dependent on Prima::TextView own mouse reactions ).

As an example Prima::PodView uses the event rectangles to catch the mouse events over the document links. Theoretically, every 'content' is to be bound with a separate logical layer; when the concept was designed, a html-browser was in mind, so such layers can be thought as ( in the html world ) links, image maps, layers, external widgets.

Currently, "Prima::TextView::EventRectangles" class is provided for such usage. Its property "::rectangles" contains an array of rectangles, and the "contains" method returns an integer value, whether the passed coordinates are inside one of its rectangles or not; in the first case it is the rectangle index.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.