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 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
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"
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       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
174   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
183           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
189           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
193           - "OP_TEXT"'s third parameter, "TEXT_WIDTH", is disregarded, and is
194           recalculated for every "OP_TEXT" met.
195
196           - 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
201           - "OP_MARK"'s second and third parameters assigned to the current
202           (X,Y) coordinates.
203
204           - "OP_WRAP" removed from the output.
205
206       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
211       walk BLOCK, %OPTIONS
212           Cycles through block opcodes, calls supplied callbacks on each.
213

AUTHOR

215       Dmitry Karasik, <dmitry@karasik.eu.org>.
216

SEE ALSO

218       Prima::TextView, Prima::Drawable::Markup, examples/mouse_tale.pl.
219
220
221
222perl v5.36.0                      2022-07-22     Prima::Drawable::TextBlock(3)
Impressum