1pod::Prima::Drawable(3)User Contributed Perl Documentatiopnod::Prima::Drawable(3)
2
6 Prima::Drawable - 2-D graphic interface
7
9 if ( $object-> isa('Prima::Drawable')) {
10 $object-> begin_paint;
11 $object-> color( cl::Black);
12 $object-> line( 100, 100, 200, 200);
13 $object-> ellipse( 100, 100, 200, 200);
14 $object-> end_paint;
15 }
16
18 Prima::Drawable is a descendant of Prima::Component. It provides
19 access to the object-bound graphic context and canvas through its
20 methods and properties. The Prima::Drawable descendants Prima::Widget,
21 Prima::Image, Prima::DeviceBitmap and Prima::Printer are backed by
22 system-dependent routines that allow drawing and painting on the system
23 objects.
24
26 Prima::Drawable, as well as its ancestors Prima::Component and
27 Prima::Object, is never used directly, because Prima::Drawable class by
28 itself provides only the interface. It provides a three-state object
29 access - when drawing and painting is enabled, when these are disabled,
30 and the information acquisition state. By default, the object is
31 created in paint-disabled state. To switch to the enabled state,
32 begin_paint() method is used. Once in the enabled state, the object
33 drawing and painting methods apply to the object-bound canvas. To
34 return to the disabled state, end_paint() method is called. The
35 information state can be managed by using begin_paint_info() and
36 end_paint_info() methods pair. An object cannot be triggered from the
37 information state to the enabled state ( and vice versa ) directly.
38 These states differ on how do they apply to a graphic context and a
39 canvas.
40 Graphic context and canvas
42 The graphic context is the set of variables, that control how exactly
43 graphic primitives are rendered. The variable examples are color, font,
44 line width, etc. Another term used here is 'canvas' - the graphic area
45 of a certain extent, bound to the object, where the drawing and
46 painting methods are applied to.
47 In all three states a graphic context is allowed to be modified, but in
49 different ways. In the disabled state the graphic context values form
50 a template values; when a object enters the information or the enabled
51 state, the values are preserved, but when the object is back to the
52 disabled state, the graphic context is restored to the values last
53 assigned before entering new state. The code example below illustrates
54 the idea:
55 $d = Prima::Drawable-> create;
57 $d-> lineWidth( 5);
58 $d-> begin_paint_info;
59 # lineWidth is 5 here
60 $d-> lineWidth( 1);
61 # lineWidth is 1
62 $d-> end_paint_info;
63 # lineWidth is 5 again
64 ( Note: "::region", "::clipRect" and "::translate" properties are
66 exceptions. They can not be used in the disabled state; their values
67 are neither recorded nor used as a template).
68 That is, in disabled state any Drawable maintains only the graphic
70 context. To draw on a canvas, the object must enter the enabled state
71 by calling begin_paint(). This function can be unsuccessful, because
72 the object binds with system resources during this stage, and might
73 fail. Only after the enabled state is entered, the canvas is
74 accessible:
75 $d = Prima::Image-> create( width => 100, height => 100);
77 if ( $d-> begin_paint) {
78 $d-> color( cl::Black);
79 $d-> bar( 0, 0, $d-> size);
80 $d-> color( cl::White);
81 $d-> fill_ellipse( $d-> width / 2, $d-> height / 2, 30, 30);
82 $d-> end_paint;
83 } else {
84 die "can't draw on image:$@";
85 }
86 Different objects are mapped to different types of canvases -
88 Prima::Image canvas pertains its content after end_paint(),
89 Prima::Widget maps it to a screen area, which content is of more
90 transitory nature, etc.
91 The information state is as same as the enabled state, but the changes
93 to a canvas are not visible. Its sole purpose is to read, not to write
94 information. Because begin_paint() requires some amount of system
95 resources, there is a chance that a resource request can fail, for any
96 reason. The begin_paint_info() requires some resources as well, but
97 usually much less, and therefore if only information is desired, it is
98 usually faster and cheaper to obtain it inside the information state. A
99 notable example is get_text_width() method, that returns the length of
100 a text string in pixels. It works in both enabled and information
101 states, but code
102 $d = Prima::Image-> create( width => 10000, height => 10000);
104 $d-> begin_paint;
105 $x = $d-> get_text_width('A');
106 $d-> end_paint;
107 is much more 'expensive' than
109 $d = Prima::Image-> create( width => 10000, height => 10000);
111 $d-> begin_paint_info;
112 $x = $d-> get_text_width('A');
113 $d-> end_paint_info;
114 for the obvious reasons.
116 It must be noted that some information methods like get_text_width()
118 work even under the disabled state; the object is switched to the
119 information state implicitly if it is necessary.
120 Color space
122 Graphic context and canvas operations rely completely on a system
123 implementation. The internal canvas color representation is therefore
124 system-specific, and usually could not be described in standard
125 definitions. Often the only information available about color space is
126 its color depth.
127 Therefore, all color manipulations, including dithering and
129 antialiasing are subject to system implementation, and can not be
130 controlled from perl code. When a property is set in the object
131 disabled state, it is recorded verbatim; color properties are no
132 exception. After the object switched to the enabled state, a color
133 value is transformed to a system color representation, which might be
134 different from Prima's. For example, if a display color depth is 15
135 bits, 5 bits for every component, then white color value 0xffffff is
136 mapped to
137 11111000 11111000 11111000
139 --R----- --G----- --B-----
140 that equals to 0xf8f8f8, not 0xffffff ( See Prima::gp-problems for
142 inevident graphic issues discussion ).
143 The Prima::Drawable color format is RRGGBB, with each component
145 resolution of 8 bit, thus allowing 2^24 color combinations. If the
146 device color space depth is different, the color is truncated or
147 expanded automatically. In case the device color depth is small,
148 dithering algorithms might apply.
149 Note: not only color properties, but all graphic context properties
151 allow all possible values in the disabled state, which transformed into
152 system-allowed values in the enabled and the information states. This
153 feature can be used to test if a graphic device is capable of
154 performing certain operations ( for example, if it supports raster
155 operations - the printers usually do not ). Example:
156 $d-> begin_paint;
158 $d-> rop( rop::Or);
159 if ( $d-> rop != rop::Or) { # this assertion is always false without
160 ... # begin_paint/end_paint brackets
161 }
162 $d-> end_paint;
163 There are ( at least ) two color properties on each drawable -
165 "::color" and "::backColor". The values they operate are integers in
166 the discussed above RRGGBB format, however, the toolkit defines some
167 mnemonic color constants:
168 cl::Black
170 cl::Blue
171 cl::Green
172 cl::Cyan
173 cl::Red
174 cl::Magenta
175 cl::Brown
176 cl::LightGray
177 cl::DarkGray
178 cl::LightBlue
179 cl::LightGreen
180 cl::LightCyan
181 cl::LightRed
182 cl::LightMagenta
183 cl::Yellow
184 cl::White
185 cl::Gray
186 As stated before, it is not unlikely that if a device color depth is
188 small, the primitives plotted in particular colors will be drawn with
189 dithered or incorrect colors. This usually happens on paletted
190 displays, with 256 or less colors.
191 There exists two methods that facilitate the correct color
193 representation. The first way is to get as much information as
194 possible about the device. The methods get_nearest_color() and
195 get_physical_palette() provide possibility to avoid mixed colors
196 drawing by obtaining indirect information about solid colors, supported
197 by a device. Another method is to use "::palette" property. It works
198 by inserting the colors into the system palette, so if an application
199 knows the colors it needs beforehand, it can employ this method -
200 however this might result in system palette flash when a window focus
201 toggles.
202 Both of these methods are applicable both with drawing routines and
204 image output. An image desired to output with least distortion is
205 advised to export its palette to an output device, because images
206 usually are not subject to automatic dithering algorithms.
207 Prima::ImageViewer module employs this scheme.
208 Monochrome bitmaps
210 A special case of "put_image" is taken where the object to be drawn is
211 a monochrome DeviceBitmap object. This object doesn't possess the color
212 palette, and is by definition a bitmap, where there are only two values
213 present, 0s and 1s. When it is drawn, 0s are drawn with the color value
214 of the target canvas "color" property, and 1s with "backColor".
215 This means that the following code
217 $bitmap-> color(0);
219 $bitmap-> line(0,0,100,100);
220 $target-> color(cl::Green);
221 $target-> put_image(0,0,$bitmap);
222 produces a green line on $target.
224 When using monochrome bitmaps for logical operations, note that target
226 colors should not be explicit 0 and 0xffffff, nor "cl::Black" and
227 "cl::White", but "cl::Clear" and "cl::Set" instead. The reason is that
228 on paletted displays, system palette may not necessarily contain the
229 white color under palette index (2^ScreenDepth-1). "cl::Set" thus
230 signals that the value should be "all ones", no matter what color it
231 represents, because it will be used for logical operations.
232 Fonts
234 Prima maintains its own font naming convention, that usually does not
235 conform to system's. Since its goal is interoperability, it might be so
236 that some system fonts would not be accessible from within the toolkit.
237 Prima::Drawable provides property "::font", that accepts/returns a
239 hash, that represents the state of a font in the object-bound graphic
240 context. The font hash keys that are acceptable on set-call are:
241 name
243 The font name string. If there is no such font, a default font name
244 is used. To select default font, a 'Default' string can be passed
245 with the same result ( unless the system has a font named
246 'Default', of course).
247 height
249 An integer value from 1 to MAX_INT. Specifies the desired extent of
250 a font glyph between descent and ascent lines in pixels.
251 size
253 An integer value from 1 to MAX_INT. Specifies the desired extent of
254 a font glyph between descent and internal leading lines in points.
255 The relation between "size" and "height" is
256 height - internal_leading
258 size = --------------------------- * 72.27
259 resolution
260 That differs from some other system representations: Win32, for
262 example, rounds 72.27 constant to 72.
263 width
265 A integer value from 0 to MAX_INT. If greater than 0, specifies the
266 desired extent of a font glyph width in pixels. If 0, sets the
267 default ( designed ) width corresponding to the font size or
268 height.
269 style
271 A combination of "fs::" ( font style ) constants. The constants
272 hight
273 fs::Normal
275 fs::Bold
276 fs::Thin
277 fs::Italic
278 fs::Underlined
279 fs::StruckOut
280 fs::Outline
281 and can be OR-ed together to express the font style. fs::Normal
283 equals to 0 and usually never used. If some styles are not
284 supported by a system-dependent font subsystem, they are ignored.
285 pitch
287 A one of three constants:
288 fp::Default
290 fp::Fixed
291 fp::Variable
292 fp::Default specifies no interest about font pitch selection.
294 fp::Fixed is set when a monospaced (all glyphs are of same width)
295 font is desired. fp::Variable pitch specifies a font with different
296 glyph widths. This key is of the highest priority; all other keys
297 may be altered for the consistency of the pitch key.
298 direction
300 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
301 is pi, etc. If a font could not be rotated, it is usually
302 substituted to the one that can.
303 encoding
305 A string value, one of the strings returned by
306 "Prima::Application::font_encodings". Selects desired font
307 encoding; if empty, picks the first matched encoding, preferably
308 the locale set up by the user.
309 The encodings provided by different systems are different; in
311 addition, the only encodings are recognizable by the system, that
312 are represented by at least one font in the system.
313 Unix systems and the toolkit PostScript interface usually provide
315 the following encodings:
316 iso8859-1
318 iso8859-2
319 ... other iso8859 ...
320 fontspecific
321 Win32 returns the literal strings like
323 Western
325 Baltic
326 Cyrillic
327 Hebrew
328 Symbol
329 A hash that "::font" returns, is a tied hash, whose keys are also
331 available as separate properties. For example,
332 $x = $d-> font-> {style};
334 is equivalent to
336 $x = $d-> font-> style;
338 While the latter gives nothing but the arguable coding convenience, its
340 usage in set-call is much more usable:
341 $d-> font-> style( fs::Bold);
343 instead of
345 my %temp = %{$d-> font};
347 $temp{ style} = fs::Bold;
348 $d-> font( \%temp);
349 The properties of a font tied hash are also accessible through set()
351 call, like in Prima::Object:
352 $d-> font-> style( fs::Bold);
354 $d-> font-> width( 10);
355 is adequate to
357 $d-> font-> set(
359 style => fs::Bold,
360 width => 10,
361 );
362 When get-called, "::font" property returns a hash where more entries
364 than the described above can be found. These keys are read-only, their
365 values are discarded if passed to "::font" in a set-call.
366 In order to query the full list of fonts available to a graphic device,
368 a "::fonts" method is used. This method is not present in
369 Prima::Drawable namespace; it can be found in two built-in class
370 instances, "Prima::Application" and "Prima::Printer".
371 "Prima::Application::fonts" returns metrics for the fonts available to
373 a screen device, while "Prima::Printer::fonts" ( or its substitute
374 Prima::PS::Printer ) returns fonts for the printing device. The result
375 of this method is an array of font metrics, fully analogous to these
376 returned by "Prima::Drawable::font" method.
377 family
379 A string with font family name. The family is a secondary string
380 key, used for distinguishing between fonts with same name but of
381 different vendors ( for example, Adobe Courier and Microsoft
382 Courier).
383 vector
385 A boolean; true if the font is vector ( e.g. can be scaled with no
386 quality loss ), false otherwise. The false value does not show if
387 the font can be scaled at all - the behavior is system-dependent.
388 Win32 can scale all non-vector fonts; X11 only the fonts specified
389 as the scalable.
390 ascent
392 Number of pixels between a glyph baseline and descent line.
393 descent
395 Number of pixels between a glyph baseline and descent line.
396 internalLeading
398 Number of pixels between ascent and internal leading lines.
399 Negative if the ascent line is below the internal leading line.
400 externalLeading
402 Number of pixels between ascent and external leading lines.
403 Negative if the ascent line is above the external leading line.
404 ------------- external leading line
406 $ ------------- ascent line
408 $ $
409 ------------- internal leading line
410 $
411 $$$
412 $ $
413 $ $ $
414 $$$$$$$ $$$
415 $ $ $ $
416 $ $ $ $
417 $ $ $$$ ---- baseline
418 $
419 $
420 $
421 $$$$ ---- descent line
422 weight
424 A font designed weight. Can be one of
425 fw::UltraLight
427 fw::ExtraLight
428 fw::Light
429 fw::SemiLight
430 fw::Medium
431 fw::SemiBold
432 fw::Bold
433 fw::ExtraBold
434 fw::UltraBold
435 constants.
437 maximalWidth
439 Maximal extent of a glyph in pixels. Equals to width in monospaced
440 fonts.
441 xDeviceRes
443 Designed horizontal font resolution in dpi.
444 yDeviceRes
446 Designed vertical font resolution in dpi.
447 firstChar
449 Index of the first glyph present in a font.
450 lastChar
452 Index of the last glyph present in a font.
453 breakChar
455 Index of the default character used to divide words. In a typical
456 western language font it is 32, ASCII space character.
457 defaultChar
459 Index of a glyph that is drawn instead of nonexistent glyph if its
460 index is passed to the text drawing routines.
461 Font ABC metrics
463 Besides these characteristics, every font glyph has an ABC-metric, the
464 three integer values that describe horizontal extents of a glyph's
465 black part relative to the glyph extent:
466 . . . . . . . .
468 . . $$$. . . . .
469 . . $$. $ . . . .
470 . . $$. . . . $$ . .
471 . $$$$$$$$$$. . .$$$$$ . .
472 . . $$ . . . $ $$ . .
473 . . $$ . . . .$$$$$ . .
474 . . $$ . . . . $$ . .
475 . .$$ . . . . $$$ $$$. .
476 $$ .$$ . . . $ $$ .
477 .$$$ . . . .$$$$$$$$. .
478 . . . . . . . .
479 <A>. .<C> <A>. .<C>
480 .<-.--B--.->. . .<--B--->. .
481 A = -3 A = 3
483 B = 13 B = 10
484 C = -3 C = 3
485 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
487 in picture on the left. A and C values are positive, if a glyph
488 contains empty space in front or behind the neighbor glyphs, like in
489 picture on the right. As can be seen, B is the width of a glyph's
490 black part.
491 ABC metrics returned by the get_font_abc() method.
493 Corresponding vertical metrics, called in Prima "DEF" metrics, are
495 returned by the get_font_def() method.
496 Raster operations
498 A drawable has two raster operation properties: "::rop" and "::rop2".
499 These define how the graphic primitives are plotted. "::rop" deals with
500 the foreground color drawing, and "::rop2" with the background.
501 The toolkit defines the following operations:
503 rop::Blackness # = 0
505 rop::NotOr # = !(src | dest)
506 rop::NotSrcAnd # &= !src
507 rop::NotPut # = !src
508 rop::NotDestAnd # = !dest & src
509 rop::Invert # = !dest
510 rop::XorPut # ^= src
511 rop::NotAnd # = !(src & dest)
512 rop::AndPut # &= src
513 rop::NotXor # = !(src ^ dest)
514 rop::NotSrcXor # alias for rop::NotXor
515 rop::NotDestXor # alias for rop::NotXor
516 rop::NoOper # = dest
517 rop::NotSrcOr # |= !src
518 rop::CopyPut # = src
519 rop::NotDestOr # = !dest | src
520 rop::OrPut # |= src
521 rop::Whiteness # = 1
522 Usually, however, graphic devices support only a small part of the
524 above set, limiting "::rop" to the most important operations: Copy,
525 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
526 only Copy and NoOp.
527 The raster operations apply to all graphic primitives except SetPixel.
529 Note for layering: using layered images and device bitmaps with
531 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
532 "rop::SrcOver" raster operations on OS-provided surfaces.
533 Additionally, Prima implements extra features for compositing on images
535 outside the begin_paint/end_paint brackets. It supports the following
536 12 Porter-Duff operators:
537 rop::Clear
539 rop::Xor
540 rop::SrcOver
541 rop::DstOver
542 rop::SrcCopy
543 rop::DstCopy
544 rop::SrcIn
545 rop::DstIn
546 rop::SrcOut
547 rop::DstOut
548 rop::SrcAtop
549 rop::DstAtop
550 and set of constants to apply a constant source and destination alpha
552 to override the existing alpha channel, if any:
553 rop::SrcAlpha
555 rop::SrcAlphaShift
556 rop::DstAlpha
557 rop::DstAlphaShift
558 To override the alpha channel(s) combine the rop constant using this
560 formula:
561 $rop = rop::XXX |
563 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
564 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
565 Also, function "rop::blend($alpha)" creates a rop constant for simple
567 blending of two images by the following formula:
568 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
570 In addition to that, "rop::AlphaCopy" operation is available for
572 accessing alpha bits only. When used, the source image is treated as
573 alpha mask, and therefore it has to be grayscale. It can be used to
574 apply the alpha bits independently, without need to construct an Icon
575 object.
576 Coordinates
578 The Prima toolkit employs a geometrical XY grid, where X ascends
579 rightwards and Y ascends upwards. There, the (0,0) location is the
580 bottom-left pixel of a canvas.
581 All graphic primitives use inclusive-inclusive boundaries. For
583 example,
584 $d-> bar( 0, 0, 1, 1);
586 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
588 The coordinate origin can be shifted using "::translate" property, that
590 translates the (0,0) point to the given offset. Calls to "::translate",
591 "::clipRect" and "::region" always use the 'physical' (0,0) point,
592 whereas the plotting methods use the transformation result, the
593 'logical' (0,0) point.
594 As noted before, these three properties can not be used in when an
596 object is in its disabled state.
597
599 Graphic context properties
600 backColor COLOR
601 Reflects background color in the graphic context. All drawing
602 routines that use non-solid or transparent fill or line patterns
603 use this property value.
604 color COLOR
606 Reflects foreground color in the graphic context. All drawing
607 routines use this property value.
608 clipRect X1, Y1, X2, Y2
610 Selects the clipping rectangle corresponding to the physical canvas
611 origin. On get-call, returns the extent of the clipping area, if
612 it is not rectangular, or the clipping rectangle otherwise. The
613 code
614 $d-> clipRect( 1, 1, 2, 2);
616 $d-> bar( 0, 0, 1, 1);
617 thus affects only one pixel at (1,1).
619 Set-call discards the previous "::region" value.
621 Note: "::clipRect" can not be used while the object is in the
623 paint-disabled state, its context is neither recorded nor used as a
624 template ( see "Graphic context and canvas").
625 fillWinding BOOLEAN
627 Affects filling style of complex polygonal shapes filled by
628 "fillpoly". If 1, the filled shape contains no holes; otherwise,
629 holes are present where the shape edges cross.
630 Default value: false
632 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
634 Selects 8x8 fill pattern that affects primitives that plot filled
635 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
636 fill_sector(), floodfill().
637 Accepts either a "fp::" constant or a reference to an array of 8
639 integers, each representing 8 bits of each line in a pattern, where
640 the first integer is the topmost pattern line, and the bit 0x80 is
641 the leftmost pixel in the line.
642 There are some predefined patterns, that can be referred via "fp::"
644 constants:
645 fp::Empty
647 fp::Solid
648 fp::Line
649 fp::LtSlash
650 fp::Slash
651 fp::BkSlash
652 fp::LtBkSlash
653 fp::Hatch
654 fp::XHatch
655 fp::Interleave
656 fp::WideDot
657 fp::CloseDot
658 fp::SimpleDots
659 fp::Borland
660 fp::Parquet
661 ( the actual patterns are hardcoded in primguts.c ) The default
663 pattern is fp::Solid.
664 An example below shows encoding of fp::Parquet pattern:
666 # 76543210
668 84218421 Hex
669 0 $ $ $ 51
671 1 $ $ 22
672 2 $ $ $ 15
673 3 $ $ 88
674 4 $ $ $ 45
675 5 $ $ 22
676 6 $ $ $ 54
677 7 $ $ 88
678 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
680 On a get-call always returns an array, never a "fp::" constant.
682 fillPatternOffset X, Y
684 Origin coordinates for the "fillPattern", from 0 to 7.
685 font \%FONT
687 Manages font context. FONT hash acceptable values are "name",
688 "height", "size", "width", "style" and "pitch".
689 Synopsis:
691 $d-> font-> size( 10);
693 $d-> font-> name( 'Courier');
694 $d-> font-> set(
695 style => $x-> font-> style | fs::Bold,
696 width => 22
697 );
698 See "Fonts" for the detailed descriptions.
700 Applies to text_out(), get_text_width(), get_text_box(),
702 get_font_abc(), get_font_def().
703 lineEnd VALUE
705 Selects a line ending cap for plotting primitives. VALUE can be one
706 of
707 le::Flat
709 le::Square
710 le::Round
711 constants. le::Round is the default value.
713 lineJoin VALUE
715 Selects a line joining style for polygons. VALUE can be one of
716 lj::Round
718 lj::Bevel
719 lj::Miter
720 constants. lj::Round is the default value.
722 linePattern PATTERN
724 Selects a line pattern for plotting primitives. PATTERN is either
725 a predefined "lp::" constant, or a string where each even byte is a
726 length of a dash, and each odd byte is a length of a gap.
727 The predefined constants are:
729 lp::Null # "" /* */
731 lp::Solid # "\1" /* ___________ */
732 lp::Dash # "\x9\3" /* __ __ __ __ */
733 lp::LongDash # "\x16\6" /* _____ _____ */
734 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
735 lp::Dot # "\1\3" /* . . . . . . */
736 lp::DotDot # "\1\1" /* ............ */
737 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
738 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
739 Not all systems are capable of accepting user-defined line
741 patterns, and in such situation the "lp::" constants are mapped to
742 the system-defined patterns. In Win9x, for example, lp::DashDotDot
743 is much different from its string definition therefore.
744 Default value is lp::Solid.
746 lineWidth WIDTH
748 Selects a line width for plotting primitives. If a VALUE is 0,
749 then a 'cosmetic' pen is used - the thinnest possible line that a
750 device can plot. If a VALUE is greater than 0, then a 'geometric'
751 pen is used - the line width is set in device units. There is a
752 subtle difference between VALUE 0 and 1 in a way the lines are
753 joined.
754 Default value is 0.
756 palette [ @PALETTE ]
758 Selects solid colors in a system palette, as many as possible.
759 PALETTE is an array of integer triplets, where each is R, G and B
760 component. The call
761 $d-> palette([128, 240, 240]);
763 selects a gray-cyan color, for example.
765 The return value from get-call is the content of the previous set-
767 call, not the actual colors that were copied to the system palette.
768 region OBJECT
770 Selects a clipping region applied to all drawing and painting
771 routines. On setting, the OBJECT is either undef, then the clip
772 region is erased ( no clip ), or a Prima::Image object with a bit
773 depth of 1. The bit mask of OBJECT is applied to the system
774 clipping region. Or, it is a Prima::Region object. If the OBJECT
775 is smaller than the drawable, its exterior is assigned to clipped
776 area as well. Discards the previous "::clipRect" value; successive
777 get-calls to "::clipRect" return the boundaries of the region.
778 On getting, OBJECT is either undef or Prima::Region object.
780 Note: "::region" can not be used while the object is in the paint-
782 disabled state, its context is neither recorded nor used as a
783 template ( see "Graphic context and canvas").
784 resolution X, Y
786 A read-only property. Returns horizontal and vertical device
787 resolution in dpi.
788 rop OPERATION
790 Selects raster operation that applies to foreground color plotting
791 routines.
792 See also: "::rop2", "Raster operations".
794 rop2 OPERATION
796 Selects raster operation that applies to background color plotting
797 routines.
798 See also: "::rop", "Raster operations".
800 textOpaque FLAG
802 If FLAG is 1, then text_out() fills the text background area with
803 "::backColor" property value before drawing the text. Default value
804 is 0, when text_out() plots text only.
805 See get_text_box().
807 textOutBaseline FLAG
809 If FLAG is 1, then text_out() plots text on a given Y coordinate
810 correspondent to font baseline. If FLAG is 0, a Y coordinate is
811 mapped to font descent line. Default is 0.
812 translate X_OFFSET, Y_OFFSET
814 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
815 affect "::clipRect" and "::region". Not cumulative, so the call
816 sequence
817 $d-> translate( 5, 5);
819 $d-> translate( 15, 15);
820 is equivalent to
822 $d-> translate( 15, 15);
824 Note: "::translate" can not be used while the object is in the
826 paint-disabled state, its context is neither recorded nor used as a
827 template ( see "Graphic context and canvas").
828 Other properties
830 height HEIGHT
831 Selects the height of a canvas.
832 size WIDTH, HEIGHT
834 Selects the extent of a canvas.
835 width WIDTH
837 Selects the width of a canvas.
838 Graphic primitives methods
840 alpha ALPHA <X1, Y1, X2, Y2>
841 Fills rectangle in the alpha channel, filled with ALPHA value
842 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
843 parameters, in this case fills all canvas area.
844 Has only effect on layered surfaces.
846 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
848 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
849 from START_ANGLE to END_ANGLE.
850 Context used: color, backColor, lineEnd, linePattern, lineWidth,
852 rop, rop2
853 bar X1, Y1, X2, Y2
855 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
856 Context used: color, backColor, fillPattern, fillPatternOffset,
858 rop, rop2
859 bars @RECTS
861 Draws a set of filled rectangles. RECTS is an array of integer
862 quartets in format (X1,Y1,X2,Y2).
863 Context used: color, backColor, fillPattern, fillPatternOffset,
865 rop, rop2
866 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
868 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
869 from START_ANGLE to END_ANGLE and connects its ends with a straight
870 line.
871 Context used: color, backColor, lineEnd, linePattern, lineWidth,
873 rop, rop2
874 clear <X1, Y1, X2, Y2>
876 Draws rectangle filled with pure background color within (X1,Y1) -
877 (X2,Y2) extents. Can be called without parameters, in this case
878 fills all canvas area.
879 Context used: backColor, rop2
881 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
883 TAB_INDENT = 1 ]
884 Draws several lines of text one under another with respect to align
885 and break rules, specified in FLAGS and TAB_INDENT tab character
886 expansion.
887 "draw_text" is a convenience wrapper around "text_wrap" for drawing
889 the wrapped text, and also provides the tilde ( ~ )- character
890 underlining support.
891 The FLAGS is a combination of the following constants:
893 dt::Left - text is aligned to the left boundary
895 dt::Right - text is aligned to the right boundary
896 dt::Center - text is aligned horizontally in center
897 dt::Top - text is aligned to the upper boundary
898 dt::Bottom - text is aligned to the lower boundary
899 dt::VCenter - text is aligned vertically in center
900 dt::DrawMnemonic - tilde-escapement and underlining is used
901 dt::DrawSingleChar - sets tw::BreakSingle option to
902 Prima::Drawable::text_wrap call
903 dt::NewLineBreak - sets tw::NewLineBreak option to
904 Prima::Drawable::text_wrap call
905 dt::SpaceBreak - sets tw::SpaceBreak option to
906 Prima::Drawable::text_wrap call
907 dt::WordBreak - sets tw::WordBreak option to
908 Prima::Drawable::text_wrap call
909 dt::ExpandTabs - performs tab character ( \t ) expansion
910 dt::DrawPartial - draws the last line, if it is visible partially
911 dt::UseExternalLeading - text lines positioned vertically with respect to
912 the font external leading
913 dt::UseClip - assign ::clipRect property to the boundary rectangle
914 dt::QueryLinesDrawn - calculates and returns number of lines drawn
915 ( contrary to dt::QueryHeight )
916 dt::QueryHeight - if set, calculates and returns vertical extension
917 of the lines drawn
918 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
919 dt::WordWrap - performs word wrapping by the width of the boundaries
920 dt::BidiText - use bidirectional formatting, if available
921 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
922 dt::UseExternalLeading
923 Context used: color, backColor, font, rop, textOpaque,
925 textOutBaseline
926 ellipse X, Y, DIAMETER_X, DIAMETER_Y
928 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
929 axis.
930 Context used: color, backColor, linePattern, lineWidth, rop, rop2
932 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
934 Fills a chord outline with center in X, Y and DIAMETER_X and
935 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see chord()).
936 Context used: color, backColor, fillPattern, fillPatternOffset,
938 rop, rop2
939 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
941 Fills an elliptical outline with center in X, Y and DIAMETER_X and
942 DIAMETER_Y axis.
943 Context used: color, backColor, fillPattern, fillPatternOffset,
945 rop, rop2
946 fillpoly \@POLYGON
948 Fills a polygonal area defined by POLYGON set of points. POLYGON
949 must present an array of integer pair in (X,Y) format. Example:
950 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
952 Context used: color, backColor, fillPattern, fillPatternOffset,
954 rop, rop2, fillWinding
955 Returns success flag; if failed, $@ contains the error.
957 See also: polyline().
959 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
961 Fills a sector outline with center in X, Y and DIAMETER_X and
962 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see sector()).
963 Context used: color, backColor, fillPattern, fillPatternOffset,
965 rop, rop2
966 fill_spline \@VERTICES, %OPTIONS
968 Fills a polygonal area defined by a curve, projected by applying
969 B-spline curve based on set of VERTICES. VERTICES must present an
970 array of integer pair in (X,Y) format. Example:
971 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
973 Context used: color, backColor, fillPattern, fillPatternOffset,
975 rop, rop2
976 Returns success flag; if failed, $@ contains the error.
978 See also: spline, render_spline
980 flood_fill X, Y, COLOR, SINGLEBORDER = 1
982 Fills an area of the canvas in current fill context. The area is
983 assumed to be bounded as specified by the SINGLEBORDER parameter.
984 SINGLEBORDER can be 0 or 1.
985 SINGLEBORDER = 0: The fill area is bounded by the color specified
987 by the COLOR parameter.
988 SINGLEBORDER = 1: The fill area is defined by the color that is
990 specified by COLOR. Filling continues outward in all directions as
991 long as the color is encountered. This style is useful for filling
992 areas with multicolored boundaries.
993 Context used: color, backColor, fillPattern, fillPatternOffset,
995 rop, rop2
996 line X1, Y1, X2, Y2
998 Plots a straight line from (X1,Y1) to (X2,Y2).
999 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1001 lines \@LINES
1003 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1004 lines() plots a straight line per quartet.
1005 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1007 Returns success flag; if failed, $@ contains the error.
1009 new_gradient
1011 Returns a new gradient object. See Prima::Drawable::Gradient for
1012 usage and details.
1013 new_path
1015 Returns a new path object. See Prima::Drawable::Path for usage and
1016 details.
1017 pixel X, Y, <COLOR>
1019 ::pixel is a property - on set-call it changes the pixel value at
1020 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1021 pixel value at (X,Y).
1022 No context is used.
1024 polyline \@POLYGON
1026 Draws a polygonal area defined by POLYGON set of points. POLYGON
1027 must present an array of integer pair in (X,Y) format.
1028 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1030 lineEnd, rop, rop2
1031 Returns success flag; if failed, $@ contains the error.
1033 See also: fillpoly().
1035 put_image X, Y, OBJECT, [ ROP ]
1037 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1038 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1039 specified, it is used. Otherwise, value of "::rop" property is
1040 used.
1041 Returns success flag; if failed, $@ contains the error.
1043 Context used: rop; color and backColor for a monochrome
1045 DeviceBitmap
1046 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1048 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1049 Copies a OBJECT from a source rectangle into a destination
1050 rectangle, stretching or compressing the OBJECT to fit the
1051 dimensions of the destination rectangle, if necessary. The source
1052 rectangle starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide
1053 and SRC_HEIGHT pixels tall. The destination rectangle starts at
1054 (X,Y), and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT)
1055 pixels tall. If DEST_WIDTH or DEST_HEIGHT are negative, a
1056 mirroring by respective axis is performed.
1057 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1059 No context is used, except color and backColor for a monochrome
1061 DeviceBitmap
1062 Returns success flag; if failed, $@ contains the error.
1064 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1066 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1067 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1068 specified, paints an inferior rectangle with it, otherwise the
1069 inferior rectangle is not touched.
1070 Context used: rop; color and backColor for a monochrome
1072 DeviceBitmap
1073 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1075 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1076 line width.
1077 No context is used.
1079 rectangle X1, Y1, X2, Y2
1081 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1082 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1084 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1086 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1087 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1088 two straight lines.
1089 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1091 rop, rop2
1092 spline \@VERTICES, %OPTIONS
1094 Draws a B-spline curve defined by set of VERTICES control points.
1095 VERTICES must present an array of integer pair in (X,Y) format. If
1096 the first and the last vertices point to the same point, draws
1097 closed spline shape ( Note - by adding degree minus two points to
1098 the set; this is important if "weight" or "knots" are specificed).
1099 The following options are supported:
1101 degree INTEGER = 2
1103 The B-spline degree. Default is 2 (quadratic). Number of points
1104 supplied must be at least degree plus one.
1105 knots \@INTEGERS
1107 Array of integers, number of points plus degree plus one, which
1108 makes the result a Bezier curve. By default, if the shape is
1109 opened (i.e. first and last points are different), is set to a
1110 clamped array, so that the first and last points of the final
1111 curve match the first and the last control points. If the shape
1112 is closed, set to an unclamped array, so that no control points
1113 lie directly on the curve.
1114 precision INTEGER = 24
1116 Defines number of steps to split the curve into. The value is
1117 multiplied to the number of points and the result is used as
1118 number of steps.
1119 weight \@INTEGERS = [ 1, 1, 1, ... ]
1121 Array of integers, one for each point supplied. Assigning these
1122 can be used to convert B-spline into a NURBS. By default set of
1123 ones.
1124 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1126 rop, rop2
1127 See also: fill_spline, render_spline.
1129 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1131 Copies a OBJECT into a destination rectangle, stretching or
1132 compressing the OBJECT to fit the dimensions of the destination
1133 rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT are
1134 negative, a mirroring is performed. The destination rectangle
1135 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1136 pixels tall.
1137 If ROP raster operation is specified, it is used. Otherwise, value
1139 of "::rop" property is used.
1140 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1142 Returns success flag; if failed, $@ contains the error.
1144 Context used: rop
1146 text_out TEXT, X, Y
1148 Draws TEXT string at (X,Y).
1149 Returns success flag; if failed, $@ contains the error.
1151 Context used: color, backColor, font, rop, textOpaque,
1153 textOutBaseline
1154 Methods
1156 begin_paint
1157 Enters the enabled ( active paint ) state, returns success flag; if
1158 failed, $@ contains the error. Once the object is in enabled
1159 state, painting and drawing methods can perform write operations on
1160 a canvas.
1161 See also: "end_paint", "begin_paint_info", "Graphic context and
1163 canvas"
1164 begin_paint_info
1166 Enters the information state, returns success flag; if failed, $@
1167 contains the error. The object information state is same as
1168 enabled state ( see "begin_paint"), except painting and drawing
1169 methods do not change the object canvas.
1170 See also: "end_paint_info", "begin_paint", "Graphic context and
1172 canvas"
1173 end_paint
1175 Exits the enabled state and returns the object to a disabled state.
1176 See also: "begin_paint", "Graphic context and canvas"
1178 end_paint_info
1180 Exits the information state and returns the object to a disabled
1181 state.
1182 See also: "begin_paint_info", "Graphic context and canvas"
1184 font_match \%SOURCE, \%DEST, PICK = 1
1186 Performs merging of two font hashes, SOURCE and DEST. Returns the
1187 merge result. If PICK is true, matches the result with a system
1188 font repository.
1189 Called implicitly by "::font" on set-call, allowing the following
1191 example to work:
1192 $d-> font-> set( size => 10);
1194 $d-> font-> set( style => fs::Bold);
1195 In the example, the hash 'style => fs::Bold' does not overwrite the
1197 previous font context ( 'size => 10' ) but gets added to it ( by
1198 font_match()), providing the resulting font with both font
1199 properties set.
1200 fonts <FAMILY = "", ENCODING = "">
1202 Member of "Prima::Application" and "Prima::Printer", does not
1203 present in "Prima::Drawable".
1204 Returns an array of font metric hashes for a given font FAMILY and
1206 ENCODING. Every hash has full set of elements described in
1207 "Fonts".
1208 If called without parameters, returns an array of same hashes where
1210 each hash represents a member of font family from every system font
1211 set. It this special case, each font hash contains additional
1212 "encodings" entry, which points to an array of encodings available
1213 for the font.
1214 If called with FAMILY parameter set but no ENCODING is set,
1216 enumerates all combinations of fonts with all available encodings.
1217 If called with FAMILY set to an empty string, but ENCODING
1219 specified, returns only fonts that can be displayed with the
1220 encoding.
1221 Example:
1223 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1225 get_bpp
1227 Returns device color depth. 1 is for black-and-white monochrome, 24
1228 for true color, etc.
1229 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1231 Returns ABC font metrics for the given range, starting at
1232 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1233 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1234 responsible of representation of characters in 127-255 range. If
1235 0, the default, encoding-dependent characters are assumed. If 1,
1236 the U007F-U00FF glyphs from Latin-1 set are used.
1237 The result is an integer array reference, where every character
1239 glyph is referred by three integers, each triplet containing A, B
1240 and C values.
1241 For detailed explanation of ABC meaning, see "Font ABC metrics";
1243 Context used: font
1245 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1247 Same as "get_font_abc", but for vertical mertics. Is expensive on
1248 bitmap fonts, because to find out the correct values Prima has to
1249 render glyphs on bitmaps and scan for black and white pixels.
1250 Vector fonts are not subject to this, and the call is as effective
1252 as "get_font_abc".
1253 get_font_ranges
1255 Returns array of integer pairs denoting unicode indices of glyphs
1256 covered by the currently selected font. Each pair is the first and
1257 the last index of a contiguous range.
1258 Context used: font
1260 get_nearest_color COLOR
1262 Returns a nearest possible solid color in representation of object-
1263 bound graphic device. Always returns same color if the device bit
1264 depth is equal or greater than 24.
1265 get_paint_state
1267 Returns paint state value on of ps:: constants - "ps::Disabled" if
1268 the object is in the disabled state, "ps::Enabled" for the enabled
1269 state, "ps::Information" for the information state.
1270 For brevity, mb::Disabled is equal to 0 so this allows for simple
1272 boolean testing whether one can get/set graphical properties on an
1273 object.
1274 See "Graphic context and canvas" for more.
1276 get_physical_palette
1278 Returns an anonymous array of integers, in (R,G,B) format, every
1279 color entry described by three values, in range 0 - 255.
1280 The physical palette array is non-empty only on paletted graphic
1282 devices, the true color devices return an empty array.
1283 The physical palette reflects the solid colors currently available
1285 to all programs in the system. The information is volatile if the
1286 system palette can change colors, since any other application may
1287 change the system colors at any moment.
1288 get_text_width TEXT, ADD_OVERHANG = 0
1290 Returns TEXT string width if it would be drawn using currently
1291 selected font.
1292 If ADD_OVERHANG is 1, the first character's absolute A value and
1294 the last character's absolute C value are added to the string if
1295 they are negative.
1296 See more on ABC values at "Font ABC metrics".
1298 Context used: font
1300 get_text_box TEXT
1302 Returns TEXT string extensions if it would be drawn using currently
1303 selected font.
1304 The result is an anonymous array of 5 points ( 5 integer pairs in
1306 (X,Y) format). These 5 points are offsets for the following string
1307 extents, given the string is plotted at (0,0):
1308 1: start of string at ascent line ( top left )
1310 2: start of string at descent line ( bottom left )
1312 3: end of string at ascent line ( top right )
1314 4: end of string at descent line ( bottom right )
1316 5: concatenation point
1318 The concatenation point coordinates (XC,YC) are coordinated passed
1320 to consequent text_out() call so the conjoint string would plot as
1321 if it was a part of TEXT. Depending on the value of the
1322 "textOutBaseline" property, the concatenation point is located
1323 either on the baseline or on the descent line.
1324 Context used: font, textOutBaseline
1326 1 3 3 4
1328 ** ****
1329 * * *
1330 *** ***
1331 * * *
1332 **** **
1333 2 4 1 2
1334 render_spline \@VERTICES, %OPTIONS
1336 Renders B-spline curve from set of VERTICES to a polyline with
1337 given options.
1338 The method is internally used by "spline" and "fill_spline", and is
1340 provided for cases when these are insufficient. See description of
1341 options in spline.
1342 text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
1344 Breaks TEXT string in chunks that would fit into WIDTH pixels wide
1345 box.
1346 The break algorithm and its result are governed by OPTIONS integer
1348 value which is a combination of "tw::" constants:
1349 tw::CalcMnemonic
1351 Use 'hot key' semantics, when a character preceded by ~ has
1352 special meaning - it gets underlined. If this bit is set, the
1353 first tilde character used as an escapement is not calculated,
1354 and never appeared in the result apart from the escaped
1355 character.
1356 tw::CollapseTilde
1358 In addition to tw::CalcMnemonic, removes '~' character from the
1359 resulting chunks.
1360 tw::CalcTabs
1362 If set, calculates a tab ('\t') character as TAB_INDENT times
1363 space characters.
1364 tw::ExpandTabs
1366 If set, expands tab ('\t') character as TAB_INDENT times space
1367 characters.
1368 tw::BreakSingle
1370 Defines procedure behavior when the text cannot be fit in
1371 WIDTH, does not affect anything otherwise.
1372 If set, returns an empty array. If unset, returns a text
1374 broken by minimum number of characters per chunk. In the
1375 latter case, the width of the resulting text blocks will exceed
1376 WIDTH.
1377 tw::NewLineBreak
1379 Forces new chunk after a newline character ('\n') is met. If
1380 UTF8 text is passed, unicode line break characters 0x2028 and
1381 0x2029 produce same effect as the newline character.
1382 tw::SpaceBreak
1384 Forces new chunk after a space character (' ') or a tab
1385 character ('\t') are met.
1386 tw::ReturnChunks
1388 Defines the result of text_wrap() function.
1389 If set, the array consists of integer pairs, each consists of a
1391 text offset within TEXT and a its length.
1392 If unset, the resulting array consists from text chunks.
1394 tw::ReturnLines
1396 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1397 tw::WordBreak
1399 If unset, the TEXT breaks as soon as the chunk width exceeds
1400 WIDTH. If set, tries to keep words in TEXT so they do not
1401 appear in two chunks, e.g. breaks TEXT by words, not by
1402 characters.
1403 tw::ReturnFirstLineLength
1405 If set, "text_wrap" proceeds until the first line is wrapped,
1406 either by width or ( if specified ) by break characters.
1407 Returns length of the resulting line. Used for efficiency when
1408 the reverse function to "get_text_width" is needed.
1409 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1411 the last scalar in the array result is a special hash reference.
1412 The hash contains extra information regarding the 'hot key'
1413 underline position - it is assumed that '~' - escapement denotes an
1414 underlined character. The hash contains the following keys:
1415 tildeLine
1417 Chunk index that contains the escaped character. Set to undef
1418 if no ~ - escapement was found. The other hash information is
1419 not relevant in this case.
1420 tildeStart
1422 Horizontal offset of a beginning of the line that underlines
1423 the escaped character.
1424 tildeEnd
1426 Horizontal offset of an end of the line that underlines the
1427 escaped character.
1428 tildeChar
1430 The escaped character.
1431 Context used: font
1433
1435 Dmitry Karasik, <dmitry@karasik.eu.org>.
1436
1438 Prima, Prima::Object, Prima::Image, Prima::Region,
1439 Prima::Drawable::Path
1440perl v5.28.1 2019-02-02 pod::Prima::Drawable(3)