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 high 16-bit word of the
48 command. The basic command set includes "OP_TEXT", "OP_COLOR",
49 "OP_FONT", "OP_TRANSPOSE", and "OP_CODE". The additional codes are
50 "OP_WRAP" and "OP_MARK", not used in drawing but are special commands
51 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"
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 As can be noticed, these opcodes are far not enough for the full-weight
170 rich text viewer. However, the new opcodes can be created using
171 "tb::opcode", that accepts the opcode length and returns the new opcode
172 value.
173 Rendering methods
175 block_wrap %OPTIONS
176 "block_wrap" wraps a block into a given width. It returns one or
177 more text blocks with fully assigned headers. The returned blocks
178 are located one below another, providing an illusion that the text
179 itself is wrapped. It does not only traverses the opcodes and sees
180 if the command fit or not in the given width; it also splits the
181 text strings if these do not fit.
182 By default the wrapping can occur either on a command boundary or
184 by the spaces or tab characters in the text strings. The
185 unsolicited wrapping can be prevented by using "OP_WRAP" command
186 brackets. The commands inside these brackets are not wrapped;
187 "OP_WRAP" commands are removed from the output blocks.
188 In general, "block_wrap" copies all commands and their parameters
190 as is, ( as it is supposed to do ), but some commands are treated
191 specially:
192 - "OP_TEXT"'s third parameter, "TEXT_WIDTH", is disregarded, and is
194 recalculated for every "OP_TEXT" met.
195 - If "OP_TRANSPOSE"'s third parameter, "X_FLAGS" contains
197 "X_DIMENSION_FONT_HEIGHT" flag, the command coordinates X and Y are
198 multiplied to the current font height and the flag is cleared in
199 the output block.
200 - "OP_MARK"'s second and third parameters assigned to the current
202 (X,Y) coordinates.
203 - "OP_WRAP" removed from the output.
205 justify_interspace %OPTIONS
207 Uses $OPTIONS{width} and $OPTIONS{min_text_to_space_ratio} to try
208 to make inter-word spacing. Returns new block if successful, undef
209 otherwise.
210 walk BLOCK, %OPTIONS
212 Cycles through block opcodes, calls supplied callbacks on each.
213
215 Dmitry Karasik, <dmitry@karasik.eu.org>.
216
218 Prima::TextView, Prima::Drawable::Markup, examples/mouse_tale.pl.
219perl v5.36.0 2022-07-22 Prima::Drawable::TextBlock(3)