1Prima::TextView(3)    User Contributed Perl Documentation   Prima::TextView(3)
2
3
4

NAME

6       Prima::TextView - rich text browser widget
7

SYNOPSIS

9        use strict;
10        use warnings;
11        use Prima qw(TextView Application);
12
13        my $w = Prima::MainWindow-> create(
14            name => 'TextView example',
15        );
16
17        my $t = $w->insert(TextView =>
18            text     => 'Hello from TextView!',
19            pack     => { expand => 1, fill => 'both' },
20        );
21
22        # 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
33        # Set the markup block(s) and recalculate the ymap
34        $t->{blocks} = [$tb];
35        $t->recalc_ymap;
36
37        # Additional step needed for horizontal scroll as well as per-character
38        # selection:
39        $t->paneSize($text_width_px, $font_height_px);
40
41        run Prima;
42

DESCRIPTION

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
50       A special package "tb::" provides the block constants and simple
51       functions for text block access.
52
53   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
63       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
69       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
73       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
78       block_walk BLOCK, %OPTIONS
79           Cycles through block opcodes, calls supplied callbacks on each.
80
81   Coordinate system methods
82       Prima::TextView employs two its own coordinate systems: (X,Y)-document
83       and (TEXT_OFFSET,BLOCK)-block.
84
85       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
93       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
98       Below different coordinate system converters are described
99
100       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
106       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
112       info2xy TEXT_OFFSET, BLOCK
113           Accepts (TEXT_OFFSET,BLOCK) coordinates, and returns (X,Y) in
114           document coordinates of a block.
115
116       text2xoffset TEXT_OFFSET, BLOCK
117           Returns X coordinate where TEXT_OFFSET begins in a BLOCK index.
118
119       info2text_offset
120           Accepts (TEXT_OFFSET,BLOCK) coordinates and returns the text offset
121           with regard to the big text chunk.
122
123       text_offset2info TEXT_OFFSET
124           Accepts big text offset and returns (TEXT_OFFSET,BLOCK) coordinates
125
126       text_offset2block TEXT_OFFSET
127           Accepts big text offset and returns BLOCK coordinate.
128
129   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
137       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
142       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
145   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
155       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
161       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

AUTHOR

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

SEE ALSO

171       Prima::Drawable::TextBlock, Prima::PodView, examples/mouse_tale.pl.
172
173
174
175perl v5.36.0                      2023-03-20                Prima::TextView(3)
Impressum