1Prima::Drawable::TextBlUoscekr(3C)ontributed Perl DocumePnrtiamtai:o:nDrawable::TextBlock(3)
2
3
4

NAME

6       Prima::Drawable::TextBlock - rich text representation
7

API

9   Block header
10       A block's fixed header consists of "tb::BLK_START - 1" integer scalars,
11       each of those is accessible via the corresponding "tb::BLK_XXX"
12       constant.  The constants are separated into two logical groups:
13
14               BLK_FLAGS
15               BLK_WIDTH
16               BLK_HEIGHT
17               BLK_X
18               BLK_Y
19               BLK_APERTURE_X
20               BLK_APERTURE_Y
21               BLK_TEXT_OFFSET
22
23       and
24
25               BLK_FONT_ID
26               BLK_FONT_SIZE
27               BLK_FONT_STYLE
28               BLK_COLOR
29               BLK_BACKCOLOR
30
31       The second group is enclosed in "tb::BLK_DATA_START" -
32       "tb::BLK_DATA_END" range, like the whole header is contained in 0 -
33       "tb::BLK_START - 1" range.  This is done for the backward
34       compatibility, if the future development changes the length of the
35       header.
36
37       The first group fields define the text block dimension, aperture
38       position and text offset ( remember, the text is stored as one big
39       chunk ). The second defines the initial color and font settings.
40       Prima::TextView needs all fields of every block to be initialized
41       before displaying. block_wrap method can be used for automated
42       assigning of these fields.
43
44   Block parameters
45       The scalars, beginning from "tb::BLK_START", represent the commands to
46       the renderer.  These commands have their own parameters, that follow
47       the command. The length of a command is located in @oplen array, and
48       must not be changed. The basic command set includes "OP_TEXT",
49       "OP_COLOR", "OP_FONT", "OP_TRANSPOSE", and "OP_CODE".  The additional
50       codes are "OP_WRAP" and "OP_MARK", not used in drawing but are special
51       commands to block_wrap.
52
53       OP_TEXT - TEXT_OFFSET, TEXT_LENGTH, TEXT_WIDTH
54           "OP_TEXT" commands to draw a string, from offset
55           "tb::BLK_TEXT_OFFSET + TEXT_OFFSET", with a length TEXT_LENGTH. The
56           third parameter TEXT_WIDTH contains the width of the text in
57           pixels. Such the two-part offset scheme is made for simplification
58           of an imaginary code, that would alter ( insert to, or delete part
59           of ) the big text chunk; the updating procedure would not need to
60           traverse all commands, but just the block headers.
61
62           Relative to: "tb::BLK_TEXT_OFFSET" when not preceded by OP_BIDIMAP.
63
64       OP_COLOR - COLOR
65           "OP_COLOR" sets foreground or background color. To set the
66           background, COLOR must be or-ed with "tb::BACKCOLOR_FLAG" value. In
67           addition to the two toolkit supported color values ( RRGGBB and
68           system color index ), COLOR can also be or-ed with
69           "tb::COLOR_INDEX" flags, in such case it is an index in
70           "::colormap" property array.
71
72           Relative to: "tb::BLK_COLOR", "tb::BLK_BACKCOLOR".
73
74       OP_FONT - KEY, VALUE
75           As the font is a complex property, that itself includes font name,
76           size, direction, etc keys, "OP_FONT" KEY represents one of the
77           three parameters - "tb::F_ID", "tb::F_SIZE", "tb::F_STYLE". All
78           three have different VALUE meaning.
79
80           Relative to: "tb::BLK_FONT_ID", "tb::BLK_FONT_SIZE",
81           "tb::BLK_FONT_STYLE".
82
83           F_STYLE
84               Contains a combination of "fs::XXX" constants, such as
85               "fs::Bold", "fs::Italic" etc.
86
87               Default value: 0
88
89           F_SIZE
90               Contains the relative font size. The size is relative to the
91               current widget's font size. As such, 0 is a default value, and
92               -2 is the widget's default font decreased by 2 points.
93               Prima::TextView provides no range checking ( but the toolkit
94               does ), so while it is o.k. to set the negative "F_SIZE" values
95               larger than the default font size, one must be vary when
96               relying on the combined font size value .
97
98               If "F_SIZE" value is added to a "F_HEIGHT" constant, then it is
99               treated as a font height in pixels rather than font size in
100               points. The macros for these opcodes are named respectively
101               "tb::fontSize" and "tb::fontHeight", while the opcode is the
102               same.
103
104           F_ID
105               All other font properties are collected under an 'ID'. ID is a
106               index in the "::fontPalette" property array, which contains
107               font hashes with the other font keys initialized - name,
108               encoding, and pitch. These three are minimal required set, and
109               the other font keys can be also selected.
110
111       OP_TRANSPOSE X, Y, FLAGS
112           Contains a mark for an empty space. The space is extended to the
113           relative coordinates (X,Y), so the block extension algorithms take
114           this opcode in the account. If FLAGS does not contain
115           "tb::X_EXTEND", then in addition to the block expansion, current
116           coordinate is also moved to (X,Y). In this regard,
117           "(OP_TRANSPOSE,0,0,0)" and "(OP_TRANSPOSE,0,0,X_EXTEND)" are
118           identical and are empty operators.
119
120           There are formatting-only flags,in effect with block_wrap function.
121           "X_DIMENSION_FONT_HEIGHT" indicates that (X,Y) values must be
122           multiplied to the current font height.  Another flag
123           "X_DIMENSION_POINT" does the same but multiplies by current value
124           of resolution property divided by 72 ( basically, treats X and Y
125           not as pixel but point values).
126
127           "OP_TRANSPOSE" can be used for customized graphics, in conjunction
128           with "OP_CODE" to assign a space, so the rendering algorithms do
129           not need to be re-written every time the new graphic is invented.
130           As an example, see how Prima::PodView deals with the images.
131
132       OP_CODE - SUB, PARAMETER
133           Contains a custom code pointer SUB with a parameter PARAMETER,
134           passed when a block is about to be drawn. SUB is called with the
135           following format:
136
137                   ( $widget, $canvas, $text_block, $font_and_color_state, $x, $y, $parameter);
138
139           $font_and_color_state ( or $state, through the code ) contains the
140           state of font and color commands in effect, and is changed as the
141           rendering algorithm advances through a block.  The format of the
142           state is the same as of text block, so one may notice that for
143           readability F_ID, F_SIZE, F_STYLE constants are paired to
144           BLK_FONT_ID, BLK_FONT_SIZE and BLK_FONT_STYLE.
145
146           The SUB code is executed only when the block is about to draw.
147
148       OP_WRAP mode
149           "OP_WRAP" is only in effect in block_wrap method. "mode" is a flag,
150           selecting the wrapping command.
151
152              WRAP_MODE_ON   - default, block commands can be wrapped
153              WRAP_MODE_OFF  - cancels WRAP_MODE_ON, commands cannot be wrapped
154              WRAP_IMMEDIATE - proceed with immediate wrapping, unless ignoreImmediateWrap options is set
155
156           block_wrap does not support stacking for the wrap commands, so the
157           "(OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_ON,OP_WRAP,WRAP_MODE_OFF)"
158           has same effect as "(OP_WRAP,WRAP_MODE_OFF)". If "mode" is
159           WRAP_MODE_ON, wrapping is disabled - all following commands treated
160           an non-wrapable until "(OP_WRAP,WRAP_MODE_OFF)" is met.
161
162       OP_MARK PARAMETER, X, Y
163           "OP_MARK" is only in effect in block_wrap method and is a user
164           command.  block_wrap only sets (!) X and Y to the current
165           coordinates when the command is met.  Thus, "OP_MARK" can be used
166           for arbitrary reasons, easy marking the geometrical positions that
167           undergo the block wrapping.
168
169       OP_BIDIMAP VISUAL, BIDIMAP
170           "OP_BIDIMAP" is used when the text to be displayed is RTL (right-
171           to-left) and requires special handling. This opcode is
172           automatically created by "block_wrap". It must be present before
173           any "OP_TEXT" opcode, because when in effect, the "OP_TEXT" offset
174           calculation is different - instead of reading characters from
175           "$self->{text}", it reads them from "VISUAL", and "BLK_TEXT_OFFSET"
176           in the block header is not used.
177
178       As can be noticed, these opcodes are far not enough for the full-weight
179       rich text viewer. However, the new opcodes can be created using
180       "tb::opcode", that accepts the opcode length and returns the new opcode
181       value.
182
183   Rendering methods
184       block_wrap
185           "block_wrap" is the function, that is used to wrap a block into a
186           given width.  It returns one or more text blocks with fully
187           assigned headers. The returned blocks are located one below
188           another, providing an illusion that the text itself is wrapped.  It
189           does not only traverses the opcodes and sees if the command fit or
190           not in the given width; it also splits the text strings if these do
191           not fit.
192
193           By default the wrapping can occur either on a command boundary or
194           by the spaces or tab characters in the text strings. The
195           unsolicited wrapping can be prevented by using "OP_WRAP" command
196           brackets. The commands inside these brackets are not wrapped;
197           "OP_WRAP" commands are removed from the output blocks.
198
199           In general, "block_wrap" copies all commands and their parameters
200           as is, ( as it is supposed to do ), but some commands are treated
201           especially:
202
203           - "OP_TEXT"'s third parameter, "TEXT_WIDTH", is disregarded, and is
204           recalculated for every "OP_TEXT" met.
205
206           - If "OP_TRANSPOSE"'s third parameter, "X_FLAGS" contains
207           "X_DIMENSION_FONT_HEIGHT" flag, the command coordinates X and Y are
208           multiplied to the current font height and the flag is cleared in
209           the output block.
210
211           - "OP_MARK"'s second and third parameters assigned to the current
212           (X,Y) coordinates.
213
214           - "OP_WRAP" removed from the output.
215
216           - "OP_BIDIMAP" added to the output, if the text to be displayed in
217           the block contains right-to-left characters.
218
219       walk BLOCK, %OPTIONS
220           Cycles through block opcodes, calls supplied callbacks on each.
221

AUTHOR

223       Dmitry Karasik, <dmitry@karasik.eu.org>.
224

SEE ALSO

226       Prima::TextView, Prima::Drawable::Markup, examples/mouse_tale.pl.
227
228
229
230perl v5.30.1                      2020-01-30     Prima::Drawable::TextBlock(3)
Impressum