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 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
105       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
111       info2xy TEXT_OFFSET, BLOCK
112           Accepts (TEXT_OFFSET,BLOCK) coordinates, and returns (X,Y) in
113           document coordinates of a block.
114
115       text2xoffset TEXT_OFFSET, BLOCK
116           Returns X coordinate where TEXT_OFFSET begins in a BLOCK index.
117
118       info2text_offset
119           Accepts (TEXT_OFFSET,BLOCK) coordinates and returns the text offset
120           with regard to the big text chunk.
121
122       text_offset2info TEXT_OFFSET
123           Accepts big text offset and returns (TEXT_OFFSET,BLOCK) coordinates
124
125       text_offset2block TEXT_OFFSET
126           Accepts big text offset and returns BLOCK coordinate.
127
128   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
136       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
141   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
151       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
157       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

AUTHOR

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

SEE ALSO

167       Prima::Drawable::TextBlock, Prima::PodView, examples/mouse_tale.pl.
168
169
170
171perl v5.30.1                      2020-01-30                Prima::TextView(3)
Impressum