1Prima::Drawable::TextBlUoscekr(3C)ontributed Perl DocumePnrtiamtai:o:nDrawable::TextBlock(3)
2
6 Prima::Drawable::TextBlock - rich text representation
7
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 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 and
24 BLK_FONT_ID
26 BLK_FONT_SIZE
27 BLK_FONT_STYLE
28 BLK_COLOR
29 BLK_BACKCOLOR
30 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 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 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 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 Relative to: "tb::BLK_TEXT_OFFSET" when not preceded by OP_BIDIMAP.
63 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 Relative to: "tb::BLK_COLOR", "tb::BLK_BACKCOLOR".
73 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 Relative to: "tb::BLK_FONT_ID", "tb::BLK_FONT_SIZE",
81 "tb::BLK_FONT_STYLE".
82 F_STYLE
84 Contains a combination of "fs::XXX" constants, such as
85 "fs::Bold", "fs::Italic" etc.
86 Default value: 0
88 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 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 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 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 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 "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 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 ( $widget, $canvas, $text_block, $font_and_color_state, $x, $y, $parameter);
138 $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 The SUB code is executed only when the block is about to draw.
147 OP_WRAP mode
149 "OP_WRAP" is only in effect in block_wrap method. "mode" is a flag,
150 selecting the wrapping command.
151 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 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 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 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 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 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 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 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 - "OP_TEXT"'s third parameter, "TEXT_WIDTH", is disregarded, and is
204 recalculated for every "OP_TEXT" met.
205 - 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 - "OP_MARK"'s second and third parameters assigned to the current
212 (X,Y) coordinates.
213 - "OP_WRAP" removed from the output.
215 - "OP_BIDIMAP" added to the output, if the text to be displayed in
217 the block contains right-to-left characters.
218 walk BLOCK, %OPTIONS
220 Cycles through block opcodes, calls supplied callbacks on each.
221
223 Dmitry Karasik, <dmitry@karasik.eu.org>.
224
226 Prima::TextView, Prima::Drawable::Markup, examples/mouse_tale.pl.
227perl v5.30.0 2019-08-21 Prima::Drawable::TextBlock(3)