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, point2screen X, Y
101 "screen2point" accepts (X,Y) in the screen coordinates ( O is a
102 lower left widget corner ), returns (X,Y) in document coordinates (
103 O is upper left corner of a document ). "point2screen" does the
104 reverse.
105 xy2info X, Y
107 Accepts (X,Y) is document coordinates, returns (TEXT_OFFSET,BLOCK)
108 coordinates, where TEXT_OFFSET is text offset from the beginning of
109 a block ( not related to the big text chunk ) , and BLOCK is an
110 index of a block.
111 info2xy TEXT_OFFSET, BLOCK
113 Accepts (TEXT_OFFSET,BLOCK) coordinates, and returns (X,Y) in
114 document coordinates of a block.
115 text2xoffset TEXT_OFFSET, BLOCK
117 Returns X coordinate where TEXT_OFFSET begins in a BLOCK index.
118 info2text_offset
120 Accepts (TEXT_OFFSET,BLOCK) coordinates and returns the text offset
121 with regard to the big text chunk.
122 text_offset2info TEXT_OFFSET
124 Accepts big text offset and returns (TEXT_OFFSET,BLOCK) coordinates
125 text_offset2block TEXT_OFFSET
127 Accepts big text offset and returns BLOCK coordinate.
128 Text selection
130 The text selection is performed automatically when the user selects a
131 text region with a mouse. The selection is stored in
132 (TEXT_OFFSET,BLOCK) coordinate pair, and is accessible via the
133 "::selection" property. If its value is assigned to (-1,-1,-1,-1) this
134 indicates that there is no selection. For convenience the
135 "has_selection" method is introduced.
136 Also, "get_selected_text" returns the text within the selection (or
138 undef with no selection ), and "copy" copies automatically the selected
139 text into the clipboard. The latter action is bound to "Ctrl+Insert"
140 key combination.
141 A block with TEXT_OFFSET set to -1 will be treated as not containing
143 any text, and therefore will not be able to get selected.
144 Event rectangles
146 Partly as an option for future development, partly as a hack a concept
147 of 'event rectangles' was introduced. Currently, "{contents}" private
148 variable points to an array of objects, equipped with "on_mousedown",
149 "on_mousemove", and "on_mouseup" methods. These are called within the
150 widget's mouse events, so the overloaded classes can define the
151 interactive content without overloading the actual mouse events ( which
152 is although easy but is dependent on Prima::TextView own mouse
153 reactions ).
154 As an example Prima::PodView uses the event rectangles to catch the
156 mouse events over the document links. Theoretically, every 'content' is
157 to be bound with a separate logical layer; when the concept was
158 designed, a html-browser was in mind, so such layers can be thought as
159 ( in the html world ) links, image maps, layers, external widgets.
160 Currently, "Prima::TextView::EventRectangles" class is provided for
162 such usage. Its property "::rectangles" contains an array of
163 rectangles, and the "contains" method returns an integer value, whether
164 the passed coordinates are inside one of its rectangles or not; in the
165 first case it is the rectangle index.
166
168 Dmitry Karasik, <dmitry@karasik.eu.org>.
169
171 Prima::Drawable::TextBlock, Prima::PodView, examples/mouse_tale.pl.
172perl v5.36.0 2023-03-20 Prima::TextView(3)