1Prima::TextView(3) User Contributed Perl Documentation Prima::TextView(3)
2
6 Prima::TextView - rich text browser widget
7
9 use strict;
10 use warnings;
11 use Prima qw(TextView Application);
12 my $w = Prima::MainWindow-> create(
14 name => 'TextView example',
15 );
16 my $t = $w->insert(TextView =>
18 text => 'Hello from TextView!',
19 pack => { expand => 1, fill => 'both' },
20 );
21 # Create a single block that renders all the text using the default font
23 my $tb = tb::block_create();
24 my $text_width_px = $t->get_text_width($t->text);
25 my $font_height_px = $t->font->height;
26 $tb->[tb::BLK_WIDTH] = $text_width_px;
27 $tb->[tb::BLK_HEIGHT] = $font_height_px;
28 $tb->[tb::BLK_BACKCOLOR] = cl::Back;
29 $tb->[tb::BLK_FONT_SIZE] = int($font_height_px) + tb::F_HEIGHT;
30 # Add an operation that draws the text:
31 push @$tb, tb::text(0, length($t->text), $text_width_px);
32 # Set the markup block(s) and recalculate the ymap
34 $t->{blocks} = [$tb];
35 $t->recalc_ymap;
36 # Additional step needed for horizontal scroll as well as per-character
38 # selection:
39 $t->paneSize($text_width_px, $font_height_px);
40 run Prima;
42
44 Prima::TextView accepts blocks of formatted text, and provides basic
45 functionality - scrolling and user selection. The text strings are
46 stored as one large text chunk, available by the "::text" and
47 "::textRef" properties. A block of a formatted text is an array with
48 fixed-length header and the following instructions.
49 A special package "tb::" provides the block constants and simple
51 functions for text block access.
52 Capabilities
54 Prima::TextView is mainly the text block functions and helpers. It
55 provides function for wrapping text block, calculating block
56 dimensions, drawing and converting coordinates from (X,Y) to a block
57 position. Prima::TextView is centered around the text functionality,
58 and although any custom graphic of arbitrary complexity can be embedded
59 in a text block, the internal coordinate system is used ( TEXT_OFFSET,
60 BLOCK ), where TEXT_OFFSET is a text offset from the beginning of a
61 block and BLOCK is an index of a block.
62 The functionality does not imply any text layout - this is up to the
64 class descendants, they must provide they own layout policy. The only
65 policy Prima::TextView requires is that blocks' BLK_TEXT_OFFSET field
66 must be strictly increasing, and the block text chunks must not
67 overlap. The text gaps are allowed though.
68 A text block basic drawing function includes change of color, backColor
70 and font, and the painting of text strings. Other types of graphics can
71 be achieved by supplying custom code.
72 block_draw CANVAS, BLOCK, X, Y
74 The "block_draw" draws BLOCK onto CANVAS in screen coordinates
75 (X,Y). It can be used not only inside begin_paint/end_paint
76 brackets; CANVAS can be an arbitrary "Prima::Drawable" descendant.
77 block_walk BLOCK, %OPTIONS
79 Cycles through block opcodes, calls supplied callbacks on each.
80 Coordinate system methods
82 Prima::TextView employs two its own coordinate systems: (X,Y)-document
83 and (TEXT_OFFSET,BLOCK)-block.
84 The document coordinate system is isometric and measured in pixels. Its
86 origin is located into the imaginary point of the beginning of the
87 document ( not of the first block! ), in the upper-left pixel. X
88 increases to the right, Y increases down. The block header values
89 BLK_X and BLK_Y are in document coordinates, and the widget's pane
90 extents ( regulated by "::paneSize", "::paneWidth" and "::paneHeight"
91 properties ) are also in document coordinates.
92 The block coordinate system in an-isometric - its second axis, BLOCK,
94 is an index of a text block in the widget's blocks storage,
95 "$self->{blocks}", and its first axis, TEXT_OFFSET is a text offset
96 from the beginning of the block.
97 Below different coordinate system converters are described
99 screen2point X, Y
101 Accepts (X,Y) in the screen coordinates ( O is a lower left widget
102 corner ), returns (X,Y) in document coordinates ( O is upper left
103 corner of a document ).
104 xy2info X, Y
106 Accepts (X,Y) is document coordinates, returns (TEXT_OFFSET,BLOCK)
107 coordinates, where TEXT_OFFSET is text offset from the beginning of
108 a block ( not related to the big text chunk ) , and BLOCK is an
109 index of a block.
110 info2xy TEXT_OFFSET, BLOCK
112 Accepts (TEXT_OFFSET,BLOCK) coordinates, and returns (X,Y) in
113 document coordinates of a block.
114 text2xoffset TEXT_OFFSET, BLOCK
116 Returns X coordinate where TEXT_OFFSET begins in a BLOCK index.
117 info2text_offset
119 Accepts (TEXT_OFFSET,BLOCK) coordinates and returns the text offset
120 with regard to the big text chunk.
121 text_offset2info TEXT_OFFSET
123 Accepts big text offset and returns (TEXT_OFFSET,BLOCK) coordinates
124 text_offset2block TEXT_OFFSET
126 Accepts big text offset and returns BLOCK coordinate.
127 Text selection
129 The text selection is performed automatically when the user selects a
130 text region with a mouse. The selection is stored in
131 (TEXT_OFFSET,BLOCK) coordinate pair, and is accessible via the
132 "::selection" property. If its value is assigned to (-1,-1,-1,-1) this
133 indicates that there is no selection. For convenience the
134 "has_selection" method is introduced.
135 Also, "get_selected_text" returns the text within the selection (or
137 undef with no selection ), and "copy" copies automatically the selected
138 text into the clipboard. The latter action is bound to "Ctrl+Insert"
139 key combination.
140 Event rectangles
142 Partly as an option for future development, partly as a hack a concept
143 of 'event rectangles' was introduced. Currently, "{contents}" private
144 variable points to an array of objects, equipped with "on_mousedown",
145 "on_mousemove", and "on_mouseup" methods. These are called within the
146 widget's mouse events, so the overloaded classes can define the
147 interactive content without overloading the actual mouse events ( which
148 is although easy but is dependent on Prima::TextView own mouse
149 reactions ).
150 As an example Prima::PodView uses the event rectangles to catch the
152 mouse events over the document links. Theoretically, every 'content' is
153 to be bound with a separate logical layer; when the concept was
154 designed, a html-browser was in mind, so such layers can be thought as
155 ( in the html world ) links, image maps, layers, external widgets.
156 Currently, "Prima::TextView::EventRectangles" class is provided for
158 such usage. Its property "::rectangles" contains an array of
159 rectangles, and the "contains" method returns an integer value, whether
160 the passed coordinates are inside one of its rectangles or not; in the
161 first case it is the rectangle index.
162
164 Dmitry Karasik, <dmitry@karasik.eu.org>.
165
167 Prima::Drawable::TextBlock, Prima::PodView, examples/mouse_tale.pl.
168perl v5.30.0 2019-08-21 Prima::TextView(3)