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 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
296 different glyph widths. This key is of the highest priority; all
297 other keys may be altered for the consistency of the pitch key.
298 vector
300 On of three constants:
301 fv::Default
303 fv::Bitmap
304 fv::Outline
305 "fv::Default" specifies no interest about font type selection,
307 "fv::Bitmap" sets priority for bitmap fonts, "fv::Outline" for
308 vector fonts.
309 Additionally, font entries returned from "fonts" method may set
311 "vector" to "fv::ScalableBitmap", to distingush a bitmap font face
312 that comes with predefined bitmap sets from a scalable font.
313 direction
315 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
316 is pi, etc. If a font could not be rotated, it is usually
317 substituted to the one that can.
318 encoding
320 A string value, one of the strings returned by
321 "Prima::Application::font_encodings". Selects desired font
322 encoding; if empty, picks the first matched encoding, preferably
323 the locale set up by the user.
324 The encodings provided by different systems are different; in
326 addition, the only encodings are recognizable by the system, that
327 are represented by at least one font in the system.
328 Unix systems and the toolkit PostScript interface usually provide
330 the following encodings:
331 iso8859-1
333 iso8859-2
334 ... other iso8859 ...
335 fontspecific
336 Win32 returns the literal strings like
338 Western
340 Baltic
341 Cyrillic
342 Hebrew
343 Symbol
344 A hash that "::font" returns, is a tied hash, whose keys are also
346 available as separate properties. For example,
347 $x = $d-> font-> {style};
349 is equivalent to
351 $x = $d-> font-> style;
353 While the latter gives nothing but the arguable coding convenience, its
355 usage in set-call is much more usable:
356 $d-> font-> style( fs::Bold);
358 instead of
360 my %temp = %{$d-> font};
362 $temp{ style} = fs::Bold;
363 $d-> font( \%temp);
364 The properties of a font tied hash are also accessible through set()
366 call, like in Prima::Object:
367 $d-> font-> style( fs::Bold);
369 $d-> font-> width( 10);
370 is adequate to
372 $d-> font-> set(
374 style => fs::Bold,
375 width => 10,
376 );
377 When get-called, "::font" property returns a hash where more entries
379 than the described above can be found. These keys are read-only, their
380 values are discarded if passed to "::font" in a set-call.
381 In order to query the full list of fonts available to a graphic device,
383 a "::fonts" method is used. This method is not present in
384 Prima::Drawable namespace; it can be found in two built-in class
385 instances, "Prima::Application" and "Prima::Printer".
386 "Prima::Application::fonts" returns metrics for the fonts available to
388 a screen device, while "Prima::Printer::fonts" ( or its substitute
389 Prima::PS::Printer ) returns fonts for the printing device. The result
390 of this method is an array of font metrics, fully analogous to these
391 returned by "Prima::Drawable::font" method.
392 family
394 A string with font family name. The family is a secondary string
395 key, used for distinguishing between fonts with same name but of
396 different vendors ( for example, Adobe Courier and Microsoft
397 Courier).
398 vector
400 A boolean; true if the font is vector ( e.g. can be scaled with no
401 quality loss ), false otherwise. The false value does not show if
402 the font can be scaled at all - the behavior is system-dependent.
403 Win32 can scale all non-vector fonts; X11 only the fonts specified
404 as the scalable.
405 ascent
407 Number of pixels between a glyph baseline and descent line.
408 descent
410 Number of pixels between a glyph baseline and descent line.
411 internalLeading
413 Number of pixels between ascent and internal leading lines.
414 Negative if the ascent line is below the internal leading line.
415 externalLeading
417 Number of pixels between ascent and external leading lines.
418 Negative if the ascent line is above the external leading line.
419 ------------- external leading line
421 $ ------------- ascent line
423 $ $
424 ------------- internal leading line
425 $
426 $$$
427 $ $
428 $ $ $
429 $$$$$$$ $$$
430 $ $ $ $
431 $ $ $ $
432 $ $ $$$ ---- baseline
433 $
434 $
435 $
436 $$$$ ---- descent line
437 weight
439 A font designed weight. Can be one of
440 fw::UltraLight
442 fw::ExtraLight
443 fw::Light
444 fw::SemiLight
445 fw::Medium
446 fw::SemiBold
447 fw::Bold
448 fw::ExtraBold
449 fw::UltraBold
450 constants.
452 maximalWidth
454 Maximal extent of a glyph in pixels. Equals to width in monospaced
455 fonts.
456 xDeviceRes
458 Designed horizontal font resolution in dpi.
459 yDeviceRes
461 Designed vertical font resolution in dpi.
462 firstChar
464 Index of the first glyph present in a font.
465 lastChar
467 Index of the last glyph present in a font.
468 breakChar
470 Index of the default character used to divide words. In a typical
471 western language font it is 32, ASCII space character.
472 defaultChar
474 Index of a glyph that is drawn instead of nonexistent glyph if its
475 index is passed to the text drawing routines.
476 Font ABC metrics
478 Besides these characteristics, every font glyph has an ABC-metric, the
479 three integer values that describe horizontal extents of a glyph's
480 black part relative to the glyph extent:
481 . . . . . . . .
483 . . $$$. . . . .
484 . . $$. $ . . . .
485 . . $$. . . . $$ . .
486 . $$$$$$$$$$. . .$$$$$ . .
487 . . $$ . . . $ $$ . .
488 . . $$ . . . .$$$$$ . .
489 . . $$ . . . . $$ . .
490 . .$$ . . . . $$$ $$$. .
491 $$ .$$ . . . $ $$ .
492 .$$$ . . . .$$$$$$$$. .
493 . . . . . . . .
494 <A>. .<C> <A>. .<C>
495 .<-.--B--.->. . .<--B--->. .
496 A = -3 A = 3
498 B = 13 B = 10
499 C = -3 C = 3
500 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
502 in picture on the left. A and C values are positive, if a glyph
503 contains empty space in front or behind the neighbor glyphs, like in
504 picture on the right. As can be seen, B is the width of a glyph's
505 black part.
506 ABC metrics returned by the get_font_abc() method.
508 Corresponding vertical metrics, called in Prima "DEF" metrics, are
510 returned by the get_font_def() method.
511 Raster operations
513 A drawable has two raster operation properties: "::rop" and "::rop2".
514 These define how the graphic primitives are plotted. "::rop" deals with
515 the foreground color drawing, and "::rop2" with the background.
516 Universal ROPs
518 The toolkit defines the following operations:
520 rop::Blackness # = 0
522 rop::NotOr # = !(src | dest)
523 rop::NotSrcAnd # &= !src
524 rop::NotPut # = !src
525 rop::NotDestAnd # = !dest & src
526 rop::Invert # = !dest
527 rop::XorPut # ^= src
528 rop::NotAnd # = !(src & dest)
529 rop::AndPut # &= src
530 rop::NotXor # = !(src ^ dest)
531 rop::NotSrcXor # alias for rop::NotXor
532 rop::NotDestXor # alias for rop::NotXor
533 rop::NoOper # = dest
534 rop::NotSrcOr # |= !src
535 rop::CopyPut # = src
536 rop::NotDestOr # = !dest | src
537 rop::OrPut # |= src
538 rop::Whiteness # = 1
539 Usually, however, graphic devices support only a small part of the
541 above set, limiting "::rop" to the most important operations: Copy,
542 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
543 only Copy and NoOp.
544 The raster operations apply to all graphic primitives except SetPixel.
546 Note for layering: using layered images and device bitmaps with
548 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
549 "rop::SrcOver" raster operations on OS-provided surfaces.
550 Also, "rop::AlphaCopy" operation is available for accessing alpha bits
552 only. When used, the source image is treated as alpha mask, and
553 therefore it has to be grayscale. It can be used to apply the alpha
554 bits independently, without need to construct an Icon object.
555 Additional ROPs
557 Prima implements extra features for compositing on images outside the
559 begin_paint/end_paint brackets. It supports the following 12 Porter-
560 Duff operators and some selected Photoshop blend operators:
561 rop::Clear rop::Add
563 rop::Xor rop::Multiply
564 rop::SrcOver rop::Screen
565 rop::DstOver rop::Overlay
566 rop::SrcCopy rop::Darken
567 rop::DstCopy rop::Lighten
568 rop::SrcIn rop::ColorDodge
569 rop::DstIn rop::ColorBurn
570 rop::SrcOut rop::HardLight
571 rop::DstOut rop::SoftLight
572 rop::SrcAtop rop::Difference
573 rop::DstAtop rop::Exclusion
574 Transparency control
576 There is defined a set of constants to apply a constant source and
577 destination alpha to when there is no alpha channel available:
578 rop::SrcAlpha
580 rop::SrcAlphaShift
581 rop::DstAlpha
582 rop::DstAlphaShift
583 Combine the rop constant using this formula:
585 $rop = rop::XXX |
587 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
588 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
589 Also, function "rop::blend($alpha)" creates a rop constant for
591 simple blending of two images by the following formula:
592 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
594 Its brother function "rop::alpha($rop, $src_alpha, $dst_alpha)" can
596 be used for drawing on image outside begin_paint/end_paint:
597 $image->rop( rop::alpha( rop::SrcOver, 128 ));
599 $image->ellipse( 5, 5, 5, 5 );
600 When used with icons, their source and/or destination alpha
602 channels are additionally multiplied with these values.
603 rop::Premultiply
605 When this bit is set, source pixels will be multiplied with alpha
606 before blending
607 rop::ConstantColor
609 This bit is used when the alpha is defined but the main bits
610 aren't. In this case, the main bits are filled from the
611 destination's image color, and the source image treated as alpha
612 channel. The following code applies a solid green shade with a mask
613 loaded from file.
614 $src->load('8-bit gray mask.png');
616 $dst->color(cl::LightGreen);
617 $dst->put_image( 0,0,$src,rop::SrcOver | rop::ConstantColor | rop::Premultiply);
618 Also, remember "rop::Premultiply" for proper results.
620 Coordinates
622 The Prima toolkit employs a geometrical XY grid, where X ascends
623 rightwards and Y ascends upwards. There, the (0,0) location is the
624 bottom-left pixel of a canvas.
625 All graphic primitives use inclusive-inclusive boundaries. For
627 example,
628 $d-> bar( 0, 0, 1, 1);
630 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
632 The coordinate origin can be shifted using "::translate" property, that
634 translates the (0,0) point to the given offset. Calls to "::translate",
635 "::clipRect" and "::region" always use the 'physical' (0,0) point,
636 whereas the plotting methods use the transformation result, the
637 'logical' (0,0) point.
638 As noted before, these three properties can not be used in when an
640 object is in its disabled state.
641
643 Graphic context properties
644 backColor COLOR
645 Reflects background color in the graphic context. All drawing
646 routines that use non-solid or transparent fill or line patterns
647 use this property value.
648 color COLOR
650 Reflects foreground color in the graphic context. All drawing
651 routines use this property value.
652 clipRect X1, Y1, X2, Y2
654 Selects the clipping rectangle corresponding to the physical canvas
655 origin. On get-call, returns the extent of the clipping area, if
656 it is not rectangular, or the clipping rectangle otherwise. The
657 code
658 $d-> clipRect( 1, 1, 2, 2);
660 $d-> bar( 0, 0, 1, 1);
661 thus affects only one pixel at (1,1).
663 Set-call discards the previous "::region" value.
665 Note: "::clipRect" can not be used while the object is in the
667 paint-disabled state, its context is neither recorded nor used as a
668 template ( see "Graphic context and canvas").
669 fillMode INTEGER
671 Affects filling style of complex polygonal shapes filled by
672 "fillpoly". If "fm::Winding", the filled shape contains no holes;
673 if "fm::EvenOdd", holes are present where the shape edges cross.
674 "fm::Overlay" flag can be combined with these to counter an
676 intrinsic defect of filled shaped both in Win32 and X11 that don't
677 exactly follow polygon vertices. When supplied, it overlays a
678 polygon over the filled shape, so that the latter falls exactly in
679 the boundaries defined by vertices. This is desirable when one
680 wants to follow polygon vertices, but is not desirable when a shape
681 has holes in it connected in a way that the polygon overlay may
682 leave connection edges over them.
683 Default value: "fm::Winding|fm::Overlay"
685 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
687 Selects 8x8 fill pattern that affects primitives that plot filled
688 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
689 fill_sector(), floodfill().
690 Accepts either a "fp::" constant or a reference to an array of 8
692 integers, each representing 8 bits of each line in a pattern, where
693 the first integer is the topmost pattern line, and the bit 0x80 is
694 the leftmost pixel in the line.
695 There are some predefined patterns, that can be referred via "fp::"
697 constants:
698 fp::Empty
700 fp::Solid
701 fp::Line
702 fp::LtSlash
703 fp::Slash
704 fp::BkSlash
705 fp::LtBkSlash
706 fp::Hatch
707 fp::XHatch
708 fp::Interleave
709 fp::WideDot
710 fp::CloseDot
711 fp::SimpleDots
712 fp::Borland
713 fp::Parquet
714 ( the actual patterns are hardcoded in primguts.c ) The default
716 pattern is fp::Solid.
717 An example below shows encoding of fp::Parquet pattern:
719 # 76543210
721 84218421 Hex
722 0 $ $ $ 51
724 1 $ $ 22
725 2 $ $ $ 15
726 3 $ $ 88
727 4 $ $ $ 45
728 5 $ $ 22
729 6 $ $ $ 54
730 7 $ $ 88
731 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
733 On a get-call always returns an array, never a "fp::" constant.
735 fillPatternOffset X, Y
737 Origin coordinates for the "fillPattern", from 0 to 7.
738 font \%FONT
740 Manages font context. FONT hash acceptable values are "name",
741 "height", "size", "width", "style" and "pitch".
742 Synopsis:
744 $d-> font-> size( 10);
746 $d-> font-> name( 'Courier');
747 $d-> font-> set(
748 style => $x-> font-> style | fs::Bold,
749 width => 22
750 );
751 See "Fonts" for the detailed descriptions.
753 Applies to text_out(), get_text_width(), get_text_box(),
755 get_font_abc(), get_font_def().
756 fontMapperPalette INDEX, [\%FONT | COMMAND]
758 A pseudo-property that manages access to a set of fonts used for
759 substitution in polyfont shaping (see "text_shape"). INDEX is the
760 same font index used in "fonts" array returned from "text_shape",
761 if polyfont was used (where 0 is the current font).
762 There are two font lists used in the substituion mechanism, passive
764 and active. The passive font list is initiated during the toolkit
765 start and is not changed. Each font there is addressed by "INDEX".
766 When the actual search for a glyph is initiated, these fonts are
767 queried in the loop and are checked whether they do contain
768 required glyphs. These queries are cached, so that next time
769 lookups run much quicker. That way, an "active" font list is built,
770 and next substitutions use it before trying to look into the
771 passive list. Since font order is system based, and is rather
772 random, some fonts may not be a good or aesthetic substition.
773 Therefore "fontMapperPallette" can assist in adding or removing
774 particular fonts to the active list, potentially allowing an
775 application to store and load a user-driven selection of
776 substitution fonts.
777 "fontMapperPallette" is a pseudo-property, such that it is not
779 symmetric as real properties are; its call formats are several and
780 not orthogonal to each other neither in syntax nor functionality.
781 Therefore these may change in future.
782 As a getter, the property returns the following depending on INDEX:
784 If it is -1, returns how many fonts are in the passive list. If 0,
785 which means the current font return either the non-index of the
786 current font if the same font is found in the palette, and 0
787 otherwise. If greater than zero, returns the substitution FONT
788 record from the passive list.
789 As a setter, manages the active list, and uses COMMAND integer as a
791 second argument. If COMMAND is 0, removes the INDEXth font from
792 the active list, and if 1, marks it for immediate scanning and
793 adding to the active list. The font is added in the end of the
794 list, after the existing active entries.
795 lineEnd VALUE
797 Selects a line ending cap for plotting primitives. VALUE can be one
798 of
799 le::Flat
801 le::Square
802 le::Round
803 constants. le::Round is the default value.
805 lineJoin VALUE
807 Selects a line joining style for polygons. VALUE can be one of
808 lj::Round
810 lj::Bevel
811 lj::Miter
812 constants. lj::Round is the default value.
814 linePattern PATTERN
816 Selects a line pattern for plotting primitives. PATTERN is either
817 a predefined "lp::" constant, or a string where each even byte is a
818 length of a dash, and each odd byte is a length of a gap.
819 The predefined constants are:
821 lp::Null # "" /* */
823 lp::Solid # "\1" /* ___________ */
824 lp::Dash # "\x9\3" /* __ __ __ __ */
825 lp::LongDash # "\x16\6" /* _____ _____ */
826 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
827 lp::Dot # "\1\3" /* . . . . . . */
828 lp::DotDot # "\1\1" /* ............ */
829 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
830 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
831 Not all systems are capable of accepting user-defined line
833 patterns, and in such situation the "lp::" constants are mapped to
834 the system-defined patterns. In Win9x, for example, lp::DashDotDot
835 is much different from its string definition therefore.
836 Default value is lp::Solid.
838 lineWidth WIDTH
840 Selects a line width for plotting primitives. If a VALUE is 0,
841 then a 'cosmetic' pen is used - the thinnest possible line that a
842 device can plot. If a VALUE is greater than 0, then a 'geometric'
843 pen is used - the line width is set in device units. There is a
844 subtle difference between VALUE 0 and 1 in a way the lines are
845 joined.
846 Default value is 0.
848 miterLimit VALUE
850 When path segments connect at a sharp angle, a miter join results
851 in a spike that extends well beyond the connection point. The
852 purpose of the miter limit is to cut off such spikes when they
853 become objectionably long. At any given corner, the miter length is
854 the distance from the point at which the inner edges of the stroke
855 intersect to the point at which the outside edges of the strokes
856 intersect-in other words, the diagonal length of the miter. This
857 distance increases as the angle between the segments decreases. If
858 the ratio of the miter length to the line width exceeds the miter
859 limit parameter, stroke treats the corner with a bevel join instead
860 of a miter join. The ratio of miter length to line width is
861 directly related to the angle j between the segments by the
862 formula:
863 r = 1/sin(j/2)
865 Default value is 10.0.
867 Asssuming line join is "lj::Miter" and line angle is 30 degrees:
869 miter limit = 1.0: \__/
871 miter limit = 9.0: \ /
873 \/
874 Note: does not work under X11.
876 palette [ @PALETTE ]
878 Selects solid colors in a system palette, as many as possible.
879 PALETTE is an array of integer triplets, where each is R, G and B
880 component. The call
881 $d-> palette([128, 240, 240]);
883 selects a gray-cyan color, for example.
885 The return value from get-call is the content of the previous set-
887 call, not the actual colors that were copied to the system palette.
888 region OBJECT
890 Selects a clipping region applied to all drawing and painting
891 routines. On setting, the OBJECT is either undef, then the clip
892 region is erased ( no clip ), or a Prima::Image object with a bit
893 depth of 1. The bit mask of OBJECT is applied to the system
894 clipping region. Or, it is a Prima::Region object. If the OBJECT
895 is smaller than the drawable, its exterior is assigned to clipped
896 area as well. Discards the previous "::clipRect" value; successive
897 get-calls to "::clipRect" return the boundaries of the region.
898 On getting, OBJECT is either undef or Prima::Region object.
900 Note: "::region" can not be used while the object is in the paint-
902 disabled state, its context is neither recorded nor used as a
903 template ( see "Graphic context and canvas").
904 resolution X, Y
906 A read-only property. Returns horizontal and vertical device
907 resolution in dpi.
908 rop OPERATION
910 Selects raster operation that applies to foreground color plotting
911 routines.
912 See also: "::rop2", "Raster operations".
914 rop2 OPERATION
916 Selects raster operation that applies to background color plotting
917 routines.
918 See also: "::rop", "Raster operations".
920 textOpaque FLAG
922 If FLAG is 1, then text_out() fills the text background area with
923 "::backColor" property value before drawing the text. Default value
924 is 0, when text_out() plots text only.
925 See get_text_box().
927 textOutBaseline FLAG
929 If FLAG is 1, then text_out() plots text on a given Y coordinate
930 correspondent to font baseline. If FLAG is 0, a Y coordinate is
931 mapped to font descent line. Default is 0.
932 translate X_OFFSET, Y_OFFSET
934 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
935 affect "::clipRect" and "::region". Not cumulative, so the call
936 sequence
937 $d-> translate( 5, 5);
939 $d-> translate( 15, 15);
940 is equivalent to
942 $d-> translate( 15, 15);
944 Note: "::translate" can not be used while the object is in the
946 paint-disabled state, its context is neither recorded nor used as a
947 template ( see "Graphic context and canvas").
948 Other properties
950 height HEIGHT
951 Selects the height of a canvas.
952 size WIDTH, HEIGHT
954 Selects the extent of a canvas.
955 width WIDTH
957 Selects the width of a canvas.
958 Graphic primitives methods
960 alpha ALPHA <X1, Y1, X2, Y2>
961 Fills rectangle in the alpha channel, filled with ALPHA value
962 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
963 parameters, in this case fills all canvas area.
964 Has only effect on layered surfaces.
966 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
968 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
969 from START_ANGLE to END_ANGLE.
970 Context used: color, backColor, lineEnd, linePattern, lineWidth,
972 miterLimit, rop, rop2
973 bar X1, Y1, X2, Y2
975 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
976 Context used: color, backColor, fillPattern, fillPatternOffset,
978 rop, rop2
979 bars @RECTS
981 Draws a set of filled rectangles. RECTS is an array of integer
982 quartets in format (X1,Y1,X2,Y2).
983 Context used: color, backColor, fillPattern, fillPatternOffset,
985 rop, rop2
986 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
988 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
989 from START_ANGLE to END_ANGLE and connects its ends with a straight
990 line.
991 Context used: color, backColor, lineEnd, linePattern, lineWidth,
993 miterLimit, rop, rop2
994 clear <X1, Y1, X2, Y2>
996 Draws rectangle filled with pure background color within (X1,Y1) -
997 (X2,Y2) extents. Can be called without parameters, in this case
998 fills all canvas area.
999 Context used: backColor, rop2
1001 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
1003 TAB_INDENT = 1 ]
1004 Draws several lines of text one under another with respect to align
1005 and break rules, specified in FLAGS and TAB_INDENT tab character
1006 expansion.
1007 "draw_text" is a convenience wrapper around "text_wrap" for drawing
1009 the wrapped text, and also provides the tilde ( ~ )- character
1010 underlining support.
1011 The FLAGS is a combination of the following constants:
1013 dt::Left - text is aligned to the left boundary
1015 dt::Right - text is aligned to the right boundary
1016 dt::Center - text is aligned horizontally in center
1017 dt::Top - text is aligned to the upper boundary
1018 dt::Bottom - text is aligned to the lower boundary
1019 dt::VCenter - text is aligned vertically in center
1020 dt::DrawMnemonic - tilde-escapement and underlining is used
1021 dt::DrawSingleChar - sets tw::BreakSingle option to
1022 Prima::Drawable::text_wrap call
1023 dt::NewLineBreak - sets tw::NewLineBreak option to
1024 Prima::Drawable::text_wrap call
1025 dt::SpaceBreak - sets tw::SpaceBreak option to
1026 Prima::Drawable::text_wrap call
1027 dt::WordBreak - sets tw::WordBreak option to
1028 Prima::Drawable::text_wrap call
1029 dt::ExpandTabs - performs tab character ( \t ) expansion
1030 dt::DrawPartial - draws the last line, if it is visible partially
1031 dt::UseExternalLeading - text lines positioned vertically with respect to
1032 the font external leading
1033 dt::UseClip - assign ::clipRect property to the boundary rectangle
1034 dt::QueryLinesDrawn - calculates and returns number of lines drawn
1035 ( contrary to dt::QueryHeight )
1036 dt::QueryHeight - if set, calculates and returns vertical extension
1037 of the lines drawn
1038 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
1039 dt::WordWrap - performs word wrapping by the width of the boundaries
1040 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
1041 dt::UseExternalLeading
1042 Context used: color, backColor, font, rop, textOpaque,
1044 textOutBaseline
1045 ellipse X, Y, DIAMETER_X, DIAMETER_Y
1047 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
1048 axis.
1049 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1051 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1053 Fills a chord outline with center in X, Y and DIAMETER_X and
1054 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see chord()).
1055 Context used: color, backColor, fillPattern, fillPatternOffset,
1057 rop, rop2
1058 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
1060 Fills an elliptical outline with center in X, Y and DIAMETER_X and
1061 DIAMETER_Y axis.
1062 Context used: color, backColor, fillPattern, fillPatternOffset,
1064 rop, rop2
1065 fillpoly \@POLYGON
1067 Fills a polygonal area defined by POLYGON set of points. POLYGON
1068 must present an array of integer pair in (X,Y) format. Example:
1069 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
1071 Context used: color, backColor, fillPattern, fillPatternOffset,
1073 rop, rop2, fillMode
1074 Returns success flag; if failed, $@ contains the error.
1076 See also: polyline().
1078 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1080 Fills a sector outline with center in X, Y and DIAMETER_X and
1081 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see sector()).
1082 Context used: color, backColor, fillPattern, fillPatternOffset,
1084 rop, rop2
1085 fill_spline \@VERTICES, %OPTIONS
1087 Fills a polygonal area defined by a curve, projected by applying
1088 B-spline curve based on set of VERTICES. VERTICES must present an
1089 array of integer pair in (X,Y) format. Example:
1090 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1092 Context used: color, backColor, fillPattern, fillPatternOffset,
1094 rop, rop2
1095 Returns success flag; if failed, $@ contains the error.
1097 See also: spline, render_spline
1099 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1101 Fills an area of the canvas in current fill context. The area is
1102 assumed to be bounded as specified by the SINGLEBORDER parameter.
1103 SINGLEBORDER can be 0 or 1.
1104 SINGLEBORDER = 0: The fill area is bounded by the color specified
1106 by the COLOR parameter.
1107 SINGLEBORDER = 1: The fill area is defined by the color that is
1109 specified by COLOR. Filling continues outward in all directions as
1110 long as the color is encountered. This style is useful for filling
1111 areas with multicolored boundaries.
1112 Context used: color, backColor, fillPattern, fillPatternOffset,
1114 rop, rop2
1115 line X1, Y1, X2, Y2
1117 Plots a straight line from (X1,Y1) to (X2,Y2).
1118 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1120 lines \@LINES
1122 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1123 lines() plots a straight line per quartet.
1124 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1126 Returns success flag; if failed, $@ contains the error.
1128 new_gradient
1130 Returns a new gradient object. See Prima::Drawable::Gradient for
1131 usage and details.
1132 new_path
1134 Returns a new path object. See Prima::Drawable::Path for usage and
1135 details.
1136 pixel X, Y, <COLOR>
1138 ::pixel is a property - on set-call it changes the pixel value at
1139 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1140 pixel value at (X,Y).
1141 No context is used.
1143 polyline \@POLYGON
1145 Draws a polygonal area defined by POLYGON set of points. POLYGON
1146 must present an array of integer pair in (X,Y) format.
1147 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1149 lineEnd, miterLimit, rop, rop2
1150 Returns success flag; if failed, $@ contains the error.
1152 See also: fillpoly().
1154 put_image X, Y, OBJECT, [ ROP ]
1156 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1157 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1158 specified, it is used. Otherwise, value of "::rop" property is
1159 used.
1160 Returns success flag; if failed, $@ contains the error.
1162 Context used: rop; color and backColor for a monochrome
1164 DeviceBitmap
1165 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1167 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1168 Copies a OBJECT from a source rectangle into a destination
1169 rectangle, stretching or compressing the OBJECT to fit the
1170 dimensions of the destination rectangle, if necessary. The source
1171 rectangle starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide
1172 and SRC_HEIGHT pixels tall. The destination rectangle starts at
1173 (X,Y), and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT)
1174 pixels tall. If DEST_WIDTH or DEST_HEIGHT are negative, a
1175 mirroring by respective axis is performed.
1176 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1178 No context is used, except color and backColor for a monochrome
1180 DeviceBitmap
1181 Returns success flag; if failed, $@ contains the error.
1183 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1185 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1186 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1187 specified, paints an inferior rectangle with it, otherwise the
1188 inferior rectangle is not touched.
1189 Context used: rop; color and backColor for a monochrome
1191 DeviceBitmap
1192 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1194 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1195 line width.
1196 No context is used.
1198 rectangle X1, Y1, X2, Y2
1200 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1201 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1203 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1205 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1206 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1207 two straight lines.
1208 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1210 miterLimit, rop, rop2
1211 spline \@VERTICES, %OPTIONS
1213 Draws a B-spline curve defined by set of VERTICES control points.
1214 VERTICES must present an array of integer pair in (X,Y) format.
1215 The following options are supported:
1217 closed BOOL = undef
1219 When not set, checks if the first and the last vertices point
1220 to the same point, and if yes, assumes a closed shape. Note - a
1221 closed shape rendering is implemented by adding degree minus
1222 two points to the set; this is important if "weight" or "knots"
1223 are specificed.
1224 degree INTEGER = 2
1226 The B-spline degree. Default is 2 (quadratic). Number of points
1227 supplied must be at least degree plus one.
1228 knots \@INTEGERS
1230 Array of integers, number of points plus degree plus one, which
1231 makes the result a Bezier curve. By default, if the shape is
1232 opened (i.e. first and last points are different), is set to a
1233 clamped array, so that the first and last points of the final
1234 curve match the first and the last control points. If the shape
1235 is closed, set to an unclamped array, so that no control points
1236 lie directly on the curve.
1237 precision INTEGER = 24
1239 Defines number of steps to split the curve into. The value is
1240 multiplied to the number of points and the result is used as
1241 number of steps.
1242 weight \@INTEGERS = [ 1, 1, 1, ... ]
1244 Array of integers, one for each point supplied. Assigning these
1245 can be used to convert B-spline into a NURBS. By default set of
1246 ones.
1247 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1249 miterLimit, rop, rop2
1250 See also: fill_spline, render_spline.
1252 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1254 Copies a OBJECT into a destination rectangle, stretching or
1255 compressing the OBJECT to fit the dimensions of the destination
1256 rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT are
1257 negative, a mirroring is performed. The destination rectangle
1258 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1259 pixels tall.
1260 If ROP raster operation is specified, it is used. Otherwise, value
1262 of "::rop" property is used.
1263 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1265 Returns success flag; if failed, $@ contains the error.
1267 Context used: rop
1269 text_out TEXT, X, Y
1271 Draws TEXT string at (X,Y). TEXT is either character string, or a
1272 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1273 "Prima::Drawable::Glyphs->glyphs" strings of glyphs.
1274 Returns success flag; if failed, $@ contains the error.
1276 Context used: color, backColor, font, rop, textOpaque,
1278 textOutBaseline
1279 text_shape TEXT, %OPTIONS
1281 Converts TEXT into set of glyphs, returns either a
1282 "Prima::Drawable::Glyphs" object, or a 0 integer when shaping is
1283 not necessary, or "undef" as an error.
1284 When compiled with "libfribidi", runs unicode bidirectional
1286 algorithm on TEXT that properly positions embedded directional text
1287 (f.ex. a latin quote inside an arabic text), see
1288 <http://unicode.org/reports/tr9/tr9-22.html>. Without the library
1289 only does minimal RTL alignment.
1290 Glyphs returned are positioned according to RTL directions given in
1292 TEXT using characters from uncode block "General Punctuation U+2000
1293 .. U+206F". Additionally, character ligation may be performed to
1294 that one or more characters are respresented by one or more glyphs.
1295 Such syntatic units, clusters, are adopted in Prima where
1296 appropriate, instead of character units, for selection, navigation
1297 etc in f.ex. "Prima::InputLine" and "Prima::Edit". Helper routines
1298 that translate clusters, glyphs, and characters into each other are
1299 found in Prima::Drawable::Glyphs.
1300 Options recognized:
1302 advances BOOLEAN = false
1304 Shaping process may or may not fill integer array of advances
1305 and positions for each glyphs, depending on the implementation.
1306 The advances are needed to represent f.ex. combining
1307 graphemes, when TEXT consisting of two characters, "A" and
1308 combining grave accent U+300 should be drawn as a single À
1309 cluster but are represented by a two glyphs "A" and "`". The
1310 grave glyph has its own advance for standalone usage, but in
1311 this case it should be ignored, and that is achieved by filling
1312 advance table where the "A" advance is the normal glyph
1313 advance, whereas the advance of the "`" is zero. Also, the
1314 position table additionaly shifts glyph position by X and Y
1315 coordinates, when that is needed (f.ex. it might be positioned
1316 differently by vertical on "a" and "A").
1317 Setting this options to "true" will force fill advance and
1319 positioning tables. These tables can be manipulated later, and
1320 are respected by "text_out" and "get_text_width".
1321 language STRING = undef
1323 When set, shaping process can take in the account the language
1324 of the text. F.ex. text "ae" might be shaped as a single glyph
1325 æ for the Latin language, but never for the English.
1326 level INTEGER = ts:XXX
1328 Selects the shaping (i.e. text to glyph conversion) level, how
1329 the system should treat the input text and how deep the shaping
1330 should go. One of the following "ts::XXX" options:
1331 ts::Bytes
1333 Treats input text as non-unicode locale-specific
1334 codepoints, characters higher than 255 are treated as
1335 chr(255). Reordering never happens, font substition never
1336 happens, kerning and ligation never happens; returns glyph
1337 indexes in a 1:1 mapping for each codepoint.
1338 ts::None
1340 Performs quick null shaping without mapping to the font
1341 glyphs, but only running bidirectional algorithm on the
1342 text. On the return, "glyphs", as well as eventual
1343 "advances" and "positions", are filled with zeros, but
1344 "indexes" are filled with the proper character offsets,
1345 effectively making it a visual-to-logical map since the
1346 number of glyphs will always be equal to the number of
1347 characters in TEXT, because ligation never happens here
1348 (except when TEXT contains unicode directional characters
1349 such as isolates etc - those are removed from the output).
1350 By default, advances and positions are not filled, but if
1352 the "advances" option is set, fills them with zeros.
1353 ts::Glyphs
1355 Applies the unicode bidi algoritm and maps the result onto
1356 font glyphs. Ligation and kerning doesn't happen here,
1357 it's basically same as "ts::None" but with the glyph
1358 mapping part.
1359 By default, advances and positions are not filled, but if
1361 "advances" option is set, fills the advances array with
1362 character glyph advances and the positions array with
1363 zeros.
1364 May fill the "fonts" array if the "polyfont" option is set.
1366 ts::Full
1368 Applies the unicode bidi algorithm, and runs the full
1369 shaping on the result. Ligation and kerning may occur.
1370 Always fills the advances and positions array; the
1371 "advances" option is ignored.
1372 If the system or the selected font does not support
1374 shaping, tries to ligate known arabic shapes using the
1375 fribidi library, when compiled with. Also in this case does
1376 not return the advances and positions by default, but if
1377 "advances" option is set, fills the advances array with
1378 character glyph advances and the positions array with
1379 zeros.
1380 May fill the "fonts" array if the "polyfont" option is set.
1382 pitch INTEGER
1384 When the "polyfont" is set (default) and font substitution is
1385 desired, filters only fonts that match "pitch", either
1386 "fp::Variable" or "fp::Fixed". By default will be set to
1387 "fp::Fixed" if the current for is monospaced, but to
1388 "fp::Default" matching all fonts, otherwise.
1389 polyfont BOOLEAN = true
1391 If set, scans if the currently selected font supports all
1392 unicode points, and if not, selects a substituions from a pre-
1393 populated list, taking into account the font pitch (see "pitch"
1394 above). In cases where the current font has not enough glyphs
1395 to shape all the requested unicode points, font substitution is
1396 made, and the result contains an extra array "fonts" (see
1397 "fonts" in Prima::Drawable). When the current font has all
1398 needed glyphs, the fonts array is not created.
1399 The font list access is available through "fontMapperPallette".
1401 Valid only with shaping levels "ts::Glyphs" and "ts::Full".
1403 reorder BOOLEAN = true
1405 When set, unicode bidi algorithm is used to reorder codepoints,
1406 and additionally RTL codepoints may be reversed (depending on
1407 direction context).
1408 When unset, no such reordering occurs, to emulate as much as
1410 possible a behavior that each text grapheme is being mapped to
1411 a glyph cluster exactly as it occurs in the input text, from
1412 left to right. Note that bidi reordering still may occur
1413 internally, since system shapers may reverse placement of RTL
1414 characters, so that the Prima reordering is needed to cancel
1415 this. In theory the caller shouldn't see the difference as
1416 these should cancel each other, but if Prima miscalculates the
1417 expected way the system shaper does the bidi processing it
1418 might.
1419 A similar effect can be reached by prepending the text with
1421 U+202D (LEFT-TO-RIGHT OVERRIDE).
1422 rtl BOOLEAN
1424 If set to 1, default text direction is assumed as RTL, and as
1425 LTR if set to 0. If unset, the text direction is taken from
1426 "textDirection" in Prima::Application.
1427 skip_if_simple BOOLEAN = false
1429 When set, checks whether the shaping result is identical to the
1430 input, in a sense that a call to "text_out(TEXT)" and a call to
1431 "text_shape_out(TEXT)" produce identical results. Majority of
1432 english text will fall into that category, and when that indeed
1433 happens, returns integer value 0 instead of a glyph object.
1434 See also "text_shape_out", "get_text_shape_width",
1436 "text_wrap_shape".
1437 text_shape_out TEXT, X, Y[, RTL]
1439 Runs shaping on TEXT character string with the RTL flag (or
1440 "$::application->textDirection". Draws the resulting glyph string
1441 at (X,Y).
1442 Returns success flag; if failed, $@ contains the error.
1444 Context used: color, backColor, font, rop, textOpaque,
1446 textOutBaseline
1447 Methods
1449 begin_paint
1450 Enters the enabled ( active paint ) state, returns success flag; if
1451 failed, $@ contains the error. Once the object is in enabled
1452 state, painting and drawing methods can perform write operations on
1453 a canvas.
1454 See also: "end_paint", "begin_paint_info", "Graphic context and
1456 canvas"
1457 begin_paint_info
1459 Enters the information state, returns success flag; if failed, $@
1460 contains the error. The object information state is same as
1461 enabled state ( see "begin_paint"), except painting and drawing
1462 methods do not change the object canvas.
1463 See also: "end_paint_info", "begin_paint", "Graphic context and
1465 canvas"
1466 end_paint
1468 Exits the enabled state and returns the object to a disabled state.
1469 See also: "begin_paint", "Graphic context and canvas"
1471 end_paint_info
1473 Exits the information state and returns the object to a disabled
1474 state.
1475 See also: "begin_paint_info", "Graphic context and canvas"
1477 font_match \%SOURCE, \%DEST, PICK = 1
1479 Performs merging of two font hashes, SOURCE and DEST. Returns the
1480 merge result. If PICK is true, matches the result with a system
1481 font repository.
1482 Called implicitly by "::font" on set-call, allowing the following
1484 example to work:
1485 $d-> font-> set( size => 10);
1487 $d-> font-> set( style => fs::Bold);
1488 In the example, the hash 'style => fs::Bold' does not overwrite the
1490 previous font context ( 'size => 10' ) but gets added to it ( by
1491 font_match()), providing the resulting font with both font
1492 properties set.
1493 fonts <FAMILY = "", ENCODING = "">
1495 Member of "Prima::Application" and "Prima::Printer", does not
1496 present in "Prima::Drawable".
1497 Returns an array of font metric hashes for a given font FAMILY and
1499 ENCODING. Every hash has full set of elements described in
1500 "Fonts".
1501 If called without parameters, returns an array of same hashes where
1503 each hash represents a member of font family from every system font
1504 set. It this special case, each font hash contains additional
1505 "encodings" entry, which points to an array of encodings available
1506 for the font.
1507 If called with FAMILY parameter set but no ENCODING is set,
1509 enumerates all combinations of fonts with all available encodings.
1510 If called with FAMILY set to an empty string, but ENCODING
1512 specified, returns only fonts that can be displayed with the
1513 encoding.
1514 Example:
1516 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1518 get_bpp
1520 Returns device color depth. 1 is for black-and-white monochrome, 24
1521 for true color, etc.
1522 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1524 Returns ABC font metrics for the given range, starting at
1525 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1526 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1527 responsible of representation of characters in 127-255 range. If
1528 0, the default, encoding-dependent characters are assumed. If 1,
1529 the U007F-U00FF glyphs from Latin-1 set are used.
1530 The result is an integer array reference, where every character
1532 glyph is referred by three integers, each triplet containing A, B
1533 and C values.
1534 For detailed explanation of ABC meaning, see "Font ABC metrics";
1536 Context used: font
1538 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1540 Same as "get_font_abc", but for vertical mertics. Is expensive on
1541 bitmap fonts, because to find out the correct values Prima has to
1542 render glyphs on bitmaps and scan for black and white pixels.
1543 Vector fonts are not subject to this, and the call is as effective
1545 as "get_font_abc".
1546 get_font_languages
1548 Returns array of ISO 639 strings that can be displayed using glyphs
1549 available in the currently selected font.
1550 get_font_ranges
1552 Returns array of integer pairs denoting unicode indices of glyphs
1553 covered by the currently selected font. Each pair is the first and
1554 the last index of a contiguous range.
1555 Context used: font
1557 get_nearest_color COLOR
1559 Returns a nearest possible solid color in representation of object-
1560 bound graphic device. Always returns same color if the device bit
1561 depth is equal or greater than 24.
1562 get_paint_state
1564 Returns paint state value on of ps:: constants - "ps::Disabled" if
1565 the object is in the disabled state, "ps::Enabled" for the enabled
1566 state, "ps::Information" for the information state.
1567 For brevity, mb::Disabled is equal to 0 so this allows for simple
1569 boolean testing whether one can get/set graphical properties on an
1570 object.
1571 See "Graphic context and canvas" for more.
1573 get_physical_palette
1575 Returns an anonymous array of integers, in (R,G,B) format, every
1576 color entry described by three values, in range 0 - 255.
1577 The physical palette array is non-empty only on paletted graphic
1579 devices, the true color devices return an empty array.
1580 The physical palette reflects the solid colors currently available
1582 to all programs in the system. The information is volatile if the
1583 system palette can change colors, since any other application may
1584 change the system colors at any moment.
1585 get_text_shape_width TEXT, [ FLAGS ]
1587 Runs shaping on TEXT character string with text direction either
1588 taken from "FLAGS & to::RTL" value, or from the or
1589 "$::application->textDirection". Returns the shaping result width
1590 as if it would be drawn using currently selected font.
1591 If "FLAGS & to::AddOverhangs" is set, the first character's
1593 absolute A value and the last character's absolute C value are
1594 added to the string if they are negative.
1595 get_text_width TEXT, ADD_OVERHANG = 0
1597 Returns TEXT string width if it would be drawn using currently
1598 selected font. TEXT is either a character string, or a
1599 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1600 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1601 If ADD_OVERHANG is 1, the first character's absolute A value and
1603 the last character's absolute C value are added to the string if
1604 they are negative.
1605 See more on ABC values at "Font ABC metrics".
1607 Context used: font
1609 get_text_box TEXT
1611 Returns TEXT string extensions if it would be drawn using currently
1612 selected font. TEXT is either a character string, or a
1613 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1614 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1615 The result is an anonymous array of 5 points ( 5 integer pairs in
1617 (X,Y) format). These 5 points are offsets for the following string
1618 extents, given the string is plotted at (0,0):
1619 1: start of string at ascent line ( top left )
1621 2: start of string at descent line ( bottom left )
1623 3: end of string at ascent line ( top right )
1625 4: end of string at descent line ( bottom right )
1627 5: concatenation point
1629 The concatenation point coordinates (XC,YC) are coordinated passed
1631 to consequent text_out() call so the conjoint string would plot as
1632 if it was a part of TEXT. Depending on the value of the
1633 "textOutBaseline" property, the concatenation point is located
1634 either on the baseline or on the descent line.
1635 Context used: font, textOutBaseline
1637 1 3 3 4
1639 ** ****
1640 * * *
1641 *** ***
1642 * * *
1643 **** **
1644 2 4 1 2
1645 render_glyph INDEX, %OPTIONS
1647 Returns glyph representation as an outline. The outline is an
1648 integer array, formed as a set of plotting commands. Each commnds
1649 is a "ggo::" constant, followed by number of points, followed by
1650 the 2D point coordinates in 1/64 pixels.
1651 Options recognized:
1653 glyph BOOL
1655 If set, INDEX is treated as the glyph index rather than
1656 character index. Default is false.
1657 hints BOOL
1659 Is set, hinting is enabled. Default is true.
1660 unicode BOOL
1662 If set, INDEX is threated as a utf8 character index, otherwise
1663 a locale-specific index. Default is false.
1664 The "ggo::" commands are:
1666 ggo::Move - move point
1668 ggo::Line - plot line
1669 ggo::Conic - plot 2-degree spline
1670 ggo::Cubic - plot 3-degree spline
1671 render_spline \@VERTICES, %OPTIONS
1673 Renders B-spline curve from set of VERTICES to a polyline with
1674 given options.
1675 The method is internally used by "spline" and "fill_spline", and is
1677 provided for cases when these are insufficient. See description of
1678 options in spline.
1679 text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
1681 Breaks TEXT string in chunks that would fit into WIDTH pixels wide
1682 box. TEXT is either character string, or a
1683 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1684 "Prima::Drawable::Glyphs->glyphs" strings of glyphs. In the glyph
1685 cases, some wrapping options are not applicable.
1686 The break algorithm and its result are governed by OPTIONS integer
1688 value which is a combination of "tw::" constants:
1689 tw::CalcMnemonic
1691 Use 'hot key' semantics, when a character preceded by ~ has
1692 special meaning - it gets underlined. If this bit is set, the
1693 first tilde character used as an escapement is not calculated,
1694 and never appeared in the result apart from the escaped
1695 character.
1696 Not applicable in glyph wrapping.
1698 tw::CollapseTilde
1700 In addition to tw::CalcMnemonic, removes '~' character from the
1701 resulting chunks.
1702 Not applicable in glyph wrapping.
1704 tw::CalcTabs
1706 If set, calculates a tab ('\t') character as TAB_INDENT times
1707 space characters.
1708 Not applicable in glyph wrapping.
1710 tw::ExpandTabs
1712 If set, expands tab ('\t') character as TAB_INDENT times space
1713 characters.
1714 Not applicable in glyph wrapping.
1716 tw::BreakSingle
1718 Defines procedure behavior when the text cannot be fit in
1719 WIDTH, does not affect anything otherwise.
1720 If set, returns an empty array. If unset, returns a text
1722 broken by minimum number of characters per chunk. In the
1723 latter case, the width of the resulting text blocks will exceed
1724 WIDTH.
1725 tw::NewLineBreak
1727 Forces new chunk after a newline character ('\n') is met. If
1728 UTF8 text is passed, unicode line break characters 0x2028 and
1729 0x2029 produce same effect as the newline character.
1730 Not applicable in glyph wrapping.
1732 tw::SpaceBreak
1734 Forces new chunk after a space character (' ') or a tab
1735 character ('\t') are met.
1736 Not applicable in glyph wrapping.
1738 tw::ReturnChunks
1740 Defines the result of text_wrap() function.
1741 If set, the array consists of integer pairs, each consists of a
1743 text offset within TEXT and a its length.
1744 If unset, the resulting array consists from text chunks.
1746 tw::ReturnLines
1748 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1749 Not applicable in glyph wrapping.
1751 tw::WordBreak
1753 If unset, the TEXT breaks as soon as the chunk width exceeds
1754 WIDTH. If set, tries to keep words in TEXT so they do not
1755 appear in two chunks, e.g. breaks TEXT by words, not by
1756 characters.
1757 Not applicable in glyph wrapping.
1759 tw::ReturnFirstLineLength
1761 If set, "text_wrap" proceeds until the first line is wrapped,
1762 either by width or ( if specified ) by break characters.
1763 Returns length of the resulting line. Used for efficiency when
1764 the reverse function to "get_text_width" is needed.
1765 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1767 the last scalar in the array result is a special hash reference.
1768 The hash contains extra information regarding the 'hot key'
1769 underline position - it is assumed that '~' - escapement denotes an
1770 underlined character. The hash contains the following keys:
1771 tildeLine
1773 Chunk index that contains the escaped character. Set to undef
1774 if no ~ - escapement was found. The other hash information is
1775 not relevant in this case.
1776 tildeStart
1778 Horizontal offset of a beginning of the line that underlines
1779 the escaped character.
1780 tildeEnd
1782 Horizontal offset of an end of the line that underlines the
1783 escaped character.
1784 tildeChar
1786 The escaped character.
1787 Context used: font
1789 text_wrap_shape TEXT, WIDTH, %OPTIONS
1791 Runs "text_shape" over results from "text_wrap" call, with "TEXT",
1792 "WIDTH", $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are
1793 used in "text_shape" call. Where "text_wrap" returns text
1794 substrings or positions, return glyphs objects or their positions
1795 instead.
1796 When called with "tw::CalcMnemonic" options, recalculates the tilde
1798 position so it adapts to glyph positions returned.
1799
1801 Dmitry Karasik, <dmitry@karasik.eu.org>.
1802
1804 Prima, Prima::Object, Prima::Image, Prima::Region,
1805 Prima::Drawable::Path, Prima::Drawable::Glyphs
1806perl v5.32.1 2021-01-27 pod::Prima::Drawable(3)