Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Prima::TextView(3)    User Contributed Perl Documentation   Prima::TextView(3)

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 X, Y
	   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	).

       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.

   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>.

SEE ALSO
       Prima::Drawable::TextBlock, Prima::PodView, examples/mouse_tale.pl.

perl v5.24.1			  2017-02-27		    Prima::TextView(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::TextView&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help