1Prima::Drawable::GlyphsU(s3e)r Contributed Perl DocumentaPtriiomna::Drawable::Glyphs(3)
2
6 Prima::Drawable::Glyphs - helper routines for bi-directional text input
7 and complex scripts output
8
10 use Prima;
11 $::application-> begin_paint;
12 $::application-> text_shape_out('אפס123', 0,0);
13 123ספא
15
17 The class implements an abstraction over a set of glyphs that can be
18 rendered to represent text strings. Objects of the class are created
19 and returned from "Prima::Drawable::text_shape" calls, see more in
20 "text_shape" in Prima::Drawable. A "Prima::Drawable::Glyphs" object is
21 a blessed array reference that can contain either two, four, or five
22 packed arrays with 16-bit integers, representing, correspondingly, a
23 set of glyph indexes, a set of character indexes, a set of glyph
24 advances, a set of glyph position offsets per glyph, and a font index.
25 Additionally, the class implements several sets of helper routines that
26 aim to address common tasks when displaying glyph-based strings.
27 Structure
29 Each sub-array is an instance of "Prima::array", an effective plain
30 memory structure that provides standard perl interface over a string
31 scalar filled with fixed-width integers.
32 The following methods provide read-only access to these arrays:
34 glyphs
36 Contains a set of unsigned 16-bit integers where each is a glyph
37 number corresponding to the font that was used for shaping the
38 text. These glyph numbers are only applicable to that font. Zero is
39 usually treated as a default glyph in vector fonts, when shaping
40 cannot map a character; in bitmap fonts this number is usually same
41 as "defaultChar".
42 This array is recognized as a special case when is sent to
44 "text_out" or "get_text_width", that can process it without other
45 arrays. In this case, no special advances and glyph positions are
46 taken into the account though.
47 Each glyph is not necessarily mapped to a character, and quite
49 often is not, even in english left-to-right texts. F ex character
50 combinations like "ff", "fi", "fl" may be mapped to single ligature
51 glyphs. When right-to-left, RTL, text direction is taken into the
52 account, the glyph positions may change, too. See "indexes" below
53 that addresses mapping of glyphs to characters.
54 indexes
56 Contains a set of unsigned 16-bit integers where each is a text
57 offset corresponding to the text was used in shaping. Each glyph
58 position thus points to a first character in the text that maps to
59 the glyph.
60 There can be more than one character per glyph, such as the above
62 example with a "ff" ligature. There can also be cases with more
63 than one character per more than one glyph, f ex in indic scripts.
64 In these cases it is easier to operate neither by character offsets
65 nor by glyph offsets, but rather by clusters, where each cluster is
66 an individual syntax unit that contains one or more characters per
67 one or more glyphs.
68 In addition to the text offset, each index value can be flagged
70 with a "to::RTL" bit, signifying that the character in question has
71 RTL direction. This is not necessarily semitic characters from RTL
72 languages that only have that attribute set; spaces in these
73 languages are normally attributed the RTL bit too, sometimes also
74 numbers. Use of explicit direction control characters from U+20XX
75 block can result in any character being assigned or not assigned
76 the RTL bit.
77 The array has an extra item added to its end, the length of the
79 text that was used for the shaping. This helps for easy calculation
80 of cluster length in characters, especially of the last one, where
81 the difference between indexes is, basically, the cluster length.
82 The array is not used for text drawing or calculation, but only for
84 conversion between character, glyph, and cluster coordinates (see
85 "Coordinates" below).
86 advances
88 Contains a set of unsigned 16-bit integers where each is a pixel
89 distance of how much space the corresponding glyph occupies. Where
90 the advances array is not present, or was force-filled by
91 "advances" options in "text_shape", a glyph advance value is
92 basically a sum of a, b, and c widths of the corresponding glyph.
93 However there are cases when depending on shaping input, these
94 values can differ.
95 One of those cases is the combining graphemes, where the text
97 consisting of two characters, "A" and combining grave accent U+300
98 should be drawn as a single "À" symbol, and where the font doesn't
99 have that single glyph but rather two individual glyphs "A" and
100 "`". There, where the grave glyph has its own advance for
101 standalone usage, in this case it should be ignored though, and
102 that is achieved by the shaper setting the advance of the "`" to
103 zero.
104 The array content is respected by "text_out" and "get_text_width",
106 and its content can be changed at will to produce gaps in the text
107 quite easily. F ex "Prima::Edit" uses that to display tab
108 characters as spaces with 8x advance.
109 positions
111 Contains a set of pairs of signed 16-bit integers where each is a X
112 and Y pixel offset for each glyph. Like in the previous example
113 with the "À" symbol, the grave glyph "`" may be positioned
114 differently on the vertical axis in "À" and "à" graphemes, for
115 example.
116 The array is respected by "text_out" (but not by "get_text_width").
118 fonts
120 Contains a set of unsigned 16-bit integers where each is an index
121 in the font substitution list (see "fontMapperPalette" in
122 Prima::Drawable). Zero means the current font.
123 The font substitution is applied by "text_shape" when "polyfont"
125 options is set (it is by default), and when the shaper cannot match
126 all fonts. If the current font contains all needed glyphs, this
127 entry is not present at all.
128 The array is respected by "text_out" and "get_text_width".
130 Coordinates
132 In addition to the natural character coordinates, where each index is a
133 text offset that can be directly used in "substr" perl function, the
134 "Prima::Drawable::Glyphs" class offers two additional coordinate
135 systems that help abstract the object data for display and navigation.
136 The glyph coordinate system is a rather straighforward copy of the
138 character coordinate system, where each number is an offset in the
139 "glyphs" array. Similarly, these offsets can be used to address
140 individual glyphs, indexes, advances, and positions. However these are
141 not easy to use when one needs, for example, to select a grapheme with
142 a mouse, or break set of glyphs in such a way so that a grapheme is not
143 broken. These can be managed easier in the cluster coordinate system.
144 The cluster coordinates represent a virtually superimposed set of
146 offsets where each corresponds to a set of one or more characters
147 displayed by a one or more glyphs. Most useful functions below operate
148 in this system.
149 Selection
151 Practically, most useful coordinates that can be used for implementing
152 selection is either character or cluster, but not glyphs. The charater-
153 based selections makes trivial extraction or replacement of the
154 selected text, while the cluster-based makes it easier to manipulate (f
155 ex with Shift- arrow keys) the selection itself.
156 The class supports both, by operatin on selection maps or selection
158 chunks, where each represent same information but in different ways.
159 For example, consider embedded number in a bidi text. For the sake of
160 clarity I'll use latin characters here. Let's have a text scalar
161 containing these characters:
162 ABC123
164 where ABC is right-to-left text, and which, when rendered on screen,
166 should be displayed as
167 123CBA
169 (and index array is (3,4,5,2,1,0) ).
171 Next, the user clicks the mouse between A and B (in text offset 1),
173 drags the mouse then to the left, and finally stops between characters
174 2 and 3 (text offset 4). The resulting selection then should not be, as
175 one might naively expect, this:
176 123CBA
178 __^^^_
179 but this instead:
181 123CBA
183 ^^_^^_
184 because the next character after C is 1, and the range of the selected
186 sub-text is from characters 1 to 4.
187 The class offers to encode such information in a map, i.e. array of
189 integers "1,1,0,1,1,0", where each entry is either 0 or 1 depending on
190 whether the cluster is or is not selected. Alternatively, the same
191 information can be encoded in chunks, or RLE sets, as array
192 "0,2,1,2,1", where the first integer signifies number of non-selected
193 clusters to display, the second - number of selected clusters, the
194 third the non-selected again, etc. If the first character belongs to
195 the selected chunk, the first integer in the result is set to 0.
196 Bidi input
198 When sending input to a widget in order to type in text, the otherwise
199 trivial case of figuring out at which position the text should be
200 inserted (or removed, for that matter), becomes interesting when there
201 are characters with mixed direction.
202 F ex it is indeed trivial, when the latin text is "AB", and the cursor
204 is positioned between "A" and "B", to figure out that whenever the user
205 types "C", the result should become "ACB". Likewise, when the text is
206 RTL and both text and input is arabic, the result is the same. However
207 when f.ex. the text is "A1", that is displayed as "1A" because of RTL
208 shaping, and the cursor is positioned between 1 (LTR) and "A" (RTL), it
209 is not clear whether that means the new input should be appended after
210 1 and become "A1C", or after "A", and become, correspondingly, "AC1".
211 There is no easy solution for this problem, and different programs
213 approach this differently, and some go as far as to provide two cursors
214 for both directions. The class offers its own solution that uses some
215 primitive heuristics to detect whether cursor belongs to the left or to
216 the right glyph. This is the area that can be enhanced, and any help
217 from native users of RTL languages can be greatly appreciated.
218
220 abc $CANVAS, $INDEX
221 Returns a, b, c metrics from the glyph $INDEX
222 advances
224 Read-only accessor to the advances array, see Structure above.
225 clone
227 Clones the object
228 cluster2glyph $FROM, $LENGTH
230 Maps a range of clusters starting with $FROM with size $LENGTH into
231 the corresponding range of glyphs. Undefined $LENGTH calculates the
232 range from $FROM till the object end.
233 cluster2index $CLUSTER
235 Returns character offset of the first character in cluster
236 $CLUSTER.
237 Note: result may contain "to::RTL" flag.
239 cluster2range $CLUSTER
241 Returns character offset of the first character in cluster $CLUSTER
242 and how many characters are there in the cluster.
243 clusters
245 Returns array of integers where each is a first character offsets
246 per cluster.
247 cursor2offset $AT_CLUSTER, $PREFERRED_RTL
249 Given a cursor positioned next to the cluster $AT_CLUSTER, runs
250 simple heuristics to see what character offset it corresponds to.
251 $PREFERRED_RTL is used when object data are not enough.
252 See "Bidi input" above.
254 def $CANVAS, $INDEX
256 Returns d, e, f metrics from the glyph $INDEX
257 fonts
259 Read-only accessor to the font indexes, see Structure above.
260 get_box $CANVAS
262 Return box metrics of the glyph object.
263 See "get_text_box" in Prima::Drawable.
265 get_sub $FROM, $LENGTH
267 Extracts and clones a new object that constains data from cluster
268 offset $FROM, with cluster length $LENGTH.
269 get_sub_box $CANVAS, $FROM, $LENGTH
271 Calculate box metrics of a glyph string from the cluster $FROM with
272 size $LENGTH.
273 get_sub_width $CANVAS, $FROM, $LENGTH
275 Calculate pixel width of a glyph string from the cluster $FROM with
276 size $LENGTH.
277 get_width $CANVAS, $WITH_OVERHANGS
279 Return width of the glyph objects, with overhangs if requested.
280 glyph2cluster $GLYPH
282 Return the cluster that contains $GLYPH.
283 glyphs
285 Read-only accessor to the glyph indexes, see Structure above.
286 glyph_lengths
288 Returns array where each glyph position is set to a number showing
289 how many glyphs the cluster occupies at this position
290 index2cluster $INDEX
292 Returns the cluster that contains the character offset $INDEX.
293 indexes
295 Read-only accessor to the indexes, see Structure above.
296 index_lengths
298 Returns array where each glyph position is set to a number showing
299 how many characters the cluster occupies at this position
300 left_overhang
302 First integer from the "overhangs" result.
303 log2vis
305 Returns a map of integers where each character position corresponds
306 to a glyph position. The name is a rudiment from pure fribidi
307 shaping, where "log2vis" and "vis2log" were mapper functions with
308 the same functionality.
309 n_clusters
311 Calculates how many clusters the object contains.
312 new @ARRAYS
314 Create new object. Not used directly, but rather from inside
315 "text_shape" calls.
316 new_array NAME
318 Creates an array suitable for the object for direct insertion, if
319 manual construction of the object is needed. F ex one may set
320 missing "fonts" array like this:
321 $obj->[ Prima::Drawable::Glyphs::FONTS() ] = $obj->new_array('fonts');
323 $obj->fonts->[0] = 1;
324 The newly created array is filled with zeros.
326 new_empty
328 Creates a new empty object.
329 overhangs
331 Calculates two pixel widths for overhangs in the beginning and in
332 the end of the glyph string. This is used in emulation of a
333 "get_text_width" call with the "to::AddOverhangs" flag.
334 positions
336 Read-only accessor to the positions array, see Structure above.
337 reorder_text TEXT
339 Returns a visual representation of "TEXT" assuming it was the input
340 of the "text_shape" call that created the object.
341 reverse
343 Creates a new object that has all arrays reversed. User for
344 calculation of pixel offset from the right end of a glyph string.
345 right_overhang
347 Second integer from the "overhangs" result.
348 selection2range $CLUSTER_START $CLUSTER_END
350 Converts cluster selection range into text selection range
351 selection_chunks_clusters, selection_chunks_glyphs $START, $END
353 Calculates a set of chunks of texts, that, given a text selection
354 from positions $START to $END, represent each either a set of
355 selected and non-selected clusters/glyphs.
356 selection_diff $OLD, $NEW
358 Given set of two chunk lists, in format as returned by
359 "selection_chunks_clusters" or "selection_chunks_glyphs",
360 calculates the list of chunks affected by the selection change. Can
361 be used for efficient repaints when the user interactively changes
362 text selection, to redraw only the changed regions.
363 selection_map_clusters, selection_map_glyphs $START, $END
365 Same as "selection_chunks_XXX", but instead of RLE chunks returns
366 full array for each cluster/glyph, where each entry is a boolean
367 value corresponding to whether that cluster/glyph is to be
368 displayed as selected, or not.
369 selection_walk $CHUNKS, $FROM, $TO = length, $SUB
371 Walks the selection chunks array, returned by "selection_chunks",
372 between $FROM and $TO clusters/glyphs, and for each chunk calls the
373 provided "$SUB->($offset, $length, $selected)", where each call
374 contains 2 integers to chunk offset and length, and a boolean flag
375 whether the chunk is selected or not.
376 Can be also used on a result of "selection_diff", in which case
378 $selected flag is irrelevant.
379 sub_text_out $CANVAS, $FROM, $LENGTH, $X, $Y
381 Optimized version of "$CANVAS->text_out( $self->get_sub($FROM,
382 $LENGTH), $X, $Y )".
383 sub_text_wrap $CANVAS, $FROM, $LENGTH, $WIDTH, $OPT, $TABS
385 Optimized version of "$CANVAS->text_wrap( $self->get_sub($FROM,
386 $LENGTH), $WIDTH, $OPT, $TABS )". The result is also converted to
387 chunks.
388 text_length
390 Returns the length of the text that was shaped and that produced
391 the object.
392 x2cluster $CANVAS, $X, $FROM, $LENGTH
394 Given sub-cluster from $FROM with size $LENGTH, calculates how many
395 clusters would fit in width $X.
396
398 This section is only there to test proper rendering
399 Latin
401 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
402 eiusmod tempor incididunt ut labore et dolore magna aliqua.
403 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
405 Latin combining
407 D̍üi̔s͙ a̸u̵t͏eͬ ịr͡u̍r͜e̥ d͎ǒl̋o̻rͫ i̮n̓
408 r͐e̔p͊rͨe̾h̍e͐n̔ḋe͠r̕i̾t̅ ịn̷ vͅo̖lͦuͦpͧt̪ątͅe̪
409 v̰e̷l̳i̯t̽ e̵s̼s̈e̮ ċi̵l͟l͙u͆m͂ d̿o̙lͭo͕r̀e̯ ḛu̅ fͩuͧg̦iͩa̓ť n̜u̼lͩl͠a̒ p̏a̽r̗i͆a͆t̳űr̀
411 Cyrillic
413 Lorem Ipsum используют потому, что тот обеспечивает более или менее
414 стандартное заполнение шаблона.
415 а также реальное распределение букв и пробелов в абзацах
417 Hebrew
419 זוהי עובדה מבוססת שדעתו של הקורא תהיה מוסחת על ידי טקטס קריא כאשר
420 הוא יביט בפריסתו.
421 המטרה בשימוש ב-Lorem Ipsum הוא שיש לו פחות או יותר תפוצה של אותיות, בניגוד למלל
423 Arabic
425 العديد من برامح النشر المكتبي وبرامح تحرير صفحات الويب تستخدم لوريم
426 إيبسوم بشكل إفتراضي
427 كنموذج عن النص، وإذا قمت بإدخال "lorem ipsum" في أي محرك بحث ستظهر العديد من
429 Hindi
431 Lorem Ipsum के अंश कई रूप में उपलब्ध हैं, लेकिन बहुमत को किसी अन्य
432 रूप में परिवर्तन का सामना करना पड़ा है, हास्य डालना या क्रमरहित
433 शब्द ,
434 जो तनिक भी विश्वसनीय नहीं लग रहे हो. यदि आप Lorem Ipsum के एक अनुच्छेद का उपयोग करने जा रहे हैं, तो आप को यकीन दिला दें कि पाठ के मध्य में वहाँ कुछ भी शर्मनाक छिपा हुआ नहीं है.
436 Chinese
438 无可否认，当读者在浏览一个页面的排版时，难免会被可阅读的内容所分散注意力。
439 Lorem Ipsum的目的就是为了保持字母多多少少标准及平
441 Largest well-known grapheme cluster in Unicode
443 ཧྐྵྨླྺྼྻྂ
444 <http://archives.miloush.net/michkap/archive/2010/04/28/10002896.html>.
446
448 Dmitry Karasik, <dmitry@karasik.eu.org>.
449
451 examples/bidi.pl
452perl v5.32.1 2021-01-27 Prima::Drawable::Glyphs(3)