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 system graphic context and canvas through its methods and
20 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 system canvas. To return to
34 the disabled state, end_paint() method is called. The information
35 state can be managed by using begin_paint_info() and end_paint_info()
36 methods pair. An object cannot be triggered from the information state
37 to the enabled state ( and vice versa ) directly. These work
38 differently with the graphic context and the canvas.
39 Graphic context and canvas
41 The graphic context is the set of variables, that control how exactly
42 graphic primitives are rendered. The variable examples are color, font,
43 line width, etc. Another term used here is canvas - the graphic area
44 of a certain extent, connected to the Prima object, where the drawing
45 and painting methods are used on.
46 In all three states a graphic context is allowed to be modified, but in
48 different ways. In the disabled state a graphic context value is saved
49 as a template; when an object enters the information or the enabled
50 state, all values are preserved, but when the object is back to the
51 disabled state, the graphic context is restored to the values last
52 assigned before entering the enabled state. The code example below
53 illustrates the idea:
54 $d = Prima::Drawable-> create;
56 $d-> lineWidth( 5);
57 $d-> begin_paint_info;
58 # lineWidth is 5 here
59 $d-> lineWidth( 1);
60 # lineWidth is 1
61 $d-> end_paint_info;
62 # lineWidth is 5 again
63 ( Note: "::region", "::clipRect" and "::translate" properties are
65 exceptions. They cannot be used in the disabled state; their values
66 are neither recorded nor used as a template).
67 That is, in the disabled state any Drawable maintains only the graphic
69 context values. To draw on a canvas, the object must enter the enabled
70 state by calling begin_paint(). This function can be unsuccessful,
71 because the object binds with system resources during this stage, and
72 allocation of those may fail. Only after the enabled state is entered,
73 the canvas is accessible:
74 $d = Prima::Image-> create( width => 100, height => 100);
76 if ( $d-> begin_paint) {
77 $d-> color( cl::Black);
78 $d-> bar( 0, 0, $d-> size);
79 $d-> color( cl::White);
80 $d-> fill_ellipse( $d-> width / 2, $d-> height / 2, 30, 30);
81 $d-> end_paint;
82 } else {
83 die "can't draw on image:$@";
84 }
85 Different objects are mapped to different types of canvases -
87 "Prima::Image" canvas pertains its content after end_paint(),
88 "Prima::Widget" maps it to some screen area, which content is of more
89 transitory nature, etc.
90 The information state is as same as the enabled state, but the changes
92 to the canvas are not visible. Its sole purpose is to read, not to
93 write information. Because begin_paint() requires some amount of
94 system resources, there is a chance that a resource request can fail,
95 for any reason. The begin_paint_info() requires some resources as well,
96 but usually much less, and therefore if only information is desired, it
97 is usually faster and cheaper to obtain it inside the information
98 state. A notable example is get_text_width() method, that returns the
99 length of a text string in pixels. It works in both enabled and
100 information states, but code
101 $d = Prima::Image-> create( width => 10000, height => 10000);
103 $d-> begin_paint;
104 $x = $d-> get_text_width('A');
105 $d-> end_paint;
106 is much more 'expensive' than
108 $d = Prima::Image-> create( width => 10000, height => 10000);
110 $d-> begin_paint_info;
111 $x = $d-> get_text_width('A');
112 $d-> end_paint_info;
113 for the obvious reasons.
115 It must be noted that some information methods like get_text_width()
117 work even under the disabled state; the object is switched to the
118 information state implicitly if it is necessary.
119 Color space
121 Graphic context and canvas operations rely completely on a system
122 implementation. The internal canvas color representation is therefore
123 system-specific, and usually could not be described in Prima
124 definitions. Often the only information available about color space is
125 its color depth.
126 Therefore all color manipulations, including dithering and antialiasing
128 are subject to system implementation, and can not be controlled from
129 perl code. When a property is set on the object in the disabled state,
130 it is recorded verbatim; color properties are no exception. After the
131 object switched to the enabled state, a color value is translated to
132 the system color representation, which might be different from Prima's.
133 For example, if the display color depth is 15 bits, 5 bits for every
134 component, then the white color value 0xffffff is mapped to
135 11111000 11111000 11111000
137 --R----- --G----- --B-----
138 that equals to 0xf8f8f8, not 0xffffff ( See Prima::gp-problems for
140 inevident graphic issues discussion ).
141 The Prima::Drawable color format is RRGGBB, with each component
143 resolution of 8 bit, thus allowing 2^24 color combinations. If the
144 device color space depth is different, the color is truncated or
145 expanded automatically. In case the device color depth is insufficient,
146 dithering algorithms may apply.
147 Note: not only color properties, but all graphic context properties
149 allow all possible values in the disabled state, which are translated
150 into system-allowed values when entering the enabled and the
151 information states. This feature can be used to test if a graphic
152 device is capable of performing certain operations ( for example, if it
153 supports raster operations - the printers usually do not ). Example:
154 $d-> begin_paint;
156 $d-> rop( rop::Or);
157 if ( $d-> rop != rop::Or) { # this assertion is always false without
158 ... # begin_paint/end_paint brackets
159 }
160 $d-> end_paint;
161 There are ( at least ) two color properties on each drawable -
163 "::color" and "::backColor". The values they operate are unsigned
164 integers in the discussed above RRGGBB format, however, the toolkit
165 defines some mnemonic color constants as well:
166 cl::Black
168 cl::Blue
169 cl::Green
170 cl::Cyan
171 cl::Red
172 cl::Magenta
173 cl::Brown
174 cl::LightGray
175 cl::DarkGray
176 cl::LightBlue
177 cl::LightGreen
178 cl::LightCyan
179 cl::LightRed
180 cl::LightMagenta
181 cl::Yellow
182 cl::White
183 cl::Gray
184 As stated before, it is not unlikely that if a device color depth is
186 insufficient, where the primitives could be drawn with dithered or
187 incorrect colors. This usually happens on paletted displays, with 256
188 or less colors.
189 There exists two methods that facilitate the correct color
191 representation. The first way is to get as much information as
192 possible about the device. The methods get_nearest_color() and
193 get_physical_palette() provide possibility to avoid mixed colors
194 drawing by obtaining indirect information about solid colors, supported
195 by a device. Another method is to use "::palette" property. It works
196 by inserting the colors into the system palette, so if an application
197 knows the colors it needs beforehand, it can employ this method -
198 however this might result in system palette flash when a window focus
199 toggles.
200 Both of these methods are applicable both with drawing routines and
202 image output. An application that desires to display an image with
203 least distortion is advised to export its palette to an output device,
204 because images usually are not subject to automatic dithering
205 algorithms. Prima::ImageViewer module employs this scheme.
206 Monochrome bitmaps
208 Prima has special rules when drawing a monochrome Prima::DeviceBitmap.
209 Such objects don't possess an inherent color palette, and by definition
210 are bitmaps with only two pixel values present, 0s and 1s. When a
211 monochrome bitmap is drawn, 0s are painted using the color value of the
212 target canvas "color" property, and 1s using the "backColor" value.
213 That means that the following code
215 $bitmap-> color(0);
217 $bitmap-> line(0,0,100,100);
218 $target-> color(cl::Green);
219 $target-> put_image(0,0,$bitmap);
220 produces a green line on $target.
222 When using monochrome bitmaps for logical operations, note that the
224 target colors should not be explicit 0 and 0xffffff, nor "cl::Black"
225 and "cl::White", but "cl::Clear" and "cl::Set" instead. The reason is
226 that on paletted displays, system palette may not necessarily contain
227 the white color under palette index (2^ScreenDepth-1). "cl::Set" thus
228 signals that the value should be "all ones", no matter what color it
229 represents, because it will be used for logical operations.
230 Fonts
232 Prima maintains its own font naming convention, that usually does not
233 conform to the system's. Since Prima's goal is interoperability, it
234 might be so that some system fonts would not be accessible from within
235 the toolkit.
236 Prima::Drawable provides property "::font", that accepts/returns a
238 hash, that represents the state of a font in the system graphic
239 context. The font hash keys that are acceptable on set-call are:
240 name
242 The font name string. If there is no such font, a default font name
243 is used. To select default font, a 'Default' string can be passed
244 with the same result ( unless the system has a font named
245 'Default', of course).
246 height
248 An integer value from 1 to MAX_INT. Specifies the desired extent of
249 a font glyph between descent and ascent lines in pixels.
250 size
252 An integer value from 1 to MAX_INT. Specifies the desired extent of
253 a font glyph between descent and internal leading lines in points.
254 The relation between "size" and "height" is
255 height - internal_leading
257 size = --------------------------- * 72.27
258 resolution
259 That differs from some other system representations: Win32, for
261 example, rounds 72.27 constant to 72.
262 width
264 A integer value from 0 to MAX_INT. If greater than 0, specifies the
265 desired extent of a font glyph width in pixels. If 0, sets the
266 default ( designed ) width corresponding to the font size or
267 height.
268 style
270 A combination of "fs::" ( font style ) constants. The constants
271 fs::Normal
273 fs::Bold
274 fs::Thin
275 fs::Italic
276 fs::Underlined
277 fs::StruckOut
278 fs::Outline
279 can be OR-ed together to express the font style. fs::Normal equals
281 to 0 and usually never used. If some styles are not supported by a
282 system-dependent font subsystem, they are ignored.
283 pitch
285 One of three constants:
286 fp::Default
288 fp::Fixed
289 fp::Variable
290 "fp::Default" specifies no interest about font pitch selection.
292 "fp::Fixed" is set when a monospaced (all glyphs are of same width)
293 font is desired. "fp::Variable" pitch specifies a font with
294 different glyph widths. This key is of the highest priority; all
295 other keys may be altered for the consistency of the pitch key.
296 vector
298 One of three constants:
299 fv::Default
301 fv::Bitmap
302 fv::Outline
303 "fv::Default" specifies no interest about font type selection,
305 "fv::Bitmap" sets priority for the bitmap fonts, "fv::Outline" for
306 the vector fonts.
307 Additionally, font entries returned from "fonts" method may set
309 "vector" to "fv::ScalableBitmap", to distingush a bitmap font face
310 that comes with predefined bitmap sets from a scalable font.
311 direction
313 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
314 is pi, etc. If a font could not be rotated, it is usually
315 substituted with the one that can.
316 encoding
318 A string value, one of the strings returned by
319 "Prima::Application::font_encodings". Selects desired font
320 encoding; if empty, picks the first matched encoding, preferably
321 the locale set up by the user.
322 The encodings provided by different systems are different; in
324 addition, the only encodings are recognizable by the system, that
325 are represented by at least one font in the system.
326 Unix systems and the toolkit PostScript interface usually provide
328 the following encodings:
329 iso8859-1
331 iso8859-2
332 ... other iso8859 ...
333 fontspecific
334 Win32 returns the literal strings like
336 Western
338 Baltic
339 Cyrillic
340 Hebrew
341 Symbol
342 A hash that "::font" returns, is a tied hash, whose keys are also
344 available as separate properties. For example,
345 $x = $d-> font-> {style};
347 is equivalent to
349 $x = $d-> font-> style;
351 While the latter gives nothing but the arguable coding convenience, its
353 usage in set-call is much more usable:
354 $d-> font-> style( fs::Bold);
356 instead of
358 my %temp = %{$d-> font};
360 $temp{ style} = fs::Bold;
361 $d-> font( \%temp);
362 The properties of a font tied hash are also accessible through set()
364 call, like in Prima::Object:
365 $d-> font-> style( fs::Bold);
367 $d-> font-> width( 10);
368 is an equivalent to
370 $d-> font-> set(
372 style => fs::Bold,
373 width => 10,
374 );
375 When get-called, "::font" property returns a hash where more entries
377 than the described above can be found. These keys are read-only, their
378 values are ignored if passed to "::font" in a set-call.
379 In order to query the full list of fonts available to a graphic device,
381 the "::fonts" method is used. This method is not present in
382 Prima::Drawable namespace; it can be found in two built-in class
383 instances, "Prima::Application" and "Prima::Printer".
384 "Prima::Application::fonts" returns metrics for the fonts available to
386 the screen device, while "Prima::Printer::fonts" ( or its substitute
387 Prima::PS::Printer ) returns fonts for the printing device. The result
388 of this method is an array of font metrics, fully analogous to these
389 returned by "Prima::Drawable::font" method.
390 family
392 A string with font family name. The family is a secondary string
393 key, used for distinguishing between fonts with same name but of
394 different vendors ( for example, Adobe Courier and Microsoft
395 Courier).
396 ascent
398 Number of pixels between a glyph baseline and descent line.
399 descent
401 Number of pixels between a glyph baseline and descent line.
402 internalLeading
404 Number of pixels between ascent and internal leading lines.
405 Negative if the ascent line is below the internal leading line.
406 externalLeading
408 Number of pixels between ascent and external leading lines.
409 Negative if the ascent line is above the external leading line.
410 ------------- external leading line
412 $ ------------- ascent line
414 $ $
415 ------------- internal leading line
416 $
417 $$$
418 $ $
419 $ $ $
420 $$$$$$$ $$$
421 $ $ $ $
422 $ $ $ $
423 $ $ $$$ ---- baseline
424 $
425 $
426 $
427 $$$$ ---- descent line
428 weight
430 Font designed weight. Can be one of
431 fw::UltraLight
433 fw::ExtraLight
434 fw::Light
435 fw::SemiLight
436 fw::Medium
437 fw::SemiBold
438 fw::Bold
439 fw::ExtraBold
440 fw::UltraBold
441 constants.
443 maximalWidth
445 Maximal extent of a glyph in pixels. Equals to width in monospaced
446 fonts.
447 xDeviceRes
449 Designed horizontal font resolution in dpi.
450 yDeviceRes
452 Designed vertical font resolution in dpi.
453 firstChar
455 Index of the first glyph present in a font.
456 lastChar
458 Index of the last glyph present in a font.
459 breakChar
461 Index of the default character used to divide words. In a typical
462 western language font it is 32, ASCII space character.
463 defaultChar
465 Index of a glyph that is drawn instead of nonexistent glyph if its
466 index is passed to the text drawing routines.
467 Font ABC metrics
469 Besides these characteristics, every font glyph has an ABC-metric, the
470 three integer values that describe horizontal extents of a glyph's
471 black part relative to the glyph extent:
472 . . . . . . . .
474 . . $$$. . . . .
475 . . $$. $ . . . .
476 . . $$. . . . $$ . .
477 . $$$$$$$$$$. . .$$$$$ . .
478 . . $$ . . . $ $$ . .
479 . . $$ . . . .$$$$$ . .
480 . . $$ . . . . $$ . .
481 . .$$ . . . . $$$ $$$. .
482 $$ .$$ . . . $ $$ .
483 .$$$ . . . .$$$$$$$$. .
484 . . . . . . . .
485 <A>. .<C> <A>. .<C>
486 .<-.--B--.->. . .<--B--->. .
487 A = -3 A = 3
489 B = 13 B = 10
490 C = -3 C = 3
491 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
493 in picture on the left. A and C values are positive, if a glyph
494 contains empty space in front or behind the neighbor glyphs, like in
495 picture on the right. As can be seen, B is the width of a glyph's
496 black part.
497 ABC metrics returned by the get_font_abc() method.
499 The corresponding vertical metrics, called in Prima "DEF" metrics, are
501 returned by the get_font_def() method.
502 Raster operations
504 A drawable has two raster operation properties: "::rop" and "::rop2".
505 These define how the graphic primitives are plotted. "::rop" deals with
506 the foreground color drawing, and "::rop2" with the background.
507 Universal ROPs
509 The toolkit defines the following operations:
511 rop::Blackness # = 0
513 rop::NotOr # = !(src | dest)
514 rop::NotSrcAnd # &= !src
515 rop::NotPut # = !src
516 rop::NotDestAnd # = !dest & src
517 rop::Invert # = !dest
518 rop::XorPut # ^= src
519 rop::NotAnd # = !(src & dest)
520 rop::AndPut # &= src
521 rop::NotXor # = !(src ^ dest)
522 rop::NotSrcXor # alias for rop::NotXor
523 rop::NotDestXor # alias for rop::NotXor
524 rop::NoOper # = dest
525 rop::NotSrcOr # |= !src
526 rop::CopyPut # = src
527 rop::NotDestOr # = !dest | src
528 rop::OrPut # |= src
529 rop::Whiteness # = 1
530 Usually, however, graphic devices support only a small part of the
532 above set, limiting "::rop" to the most important operations: Copy,
533 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
534 only Copy and NoOp.
535 The raster operations apply to all graphic primitives except SetPixel.
537 Note for layering: using layered images and device bitmaps with
539 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
540 "rop::SrcOver" raster operations on OS-provided surfaces.
541 Also, "rop::AlphaCopy" operation is available for accessing alpha bits
543 only. When used, the source image is treated as alpha mask, and
544 therefore it has to be grayscale. It can be used to apply the alpha
545 bits independently, without need to construct an Icon object.
546 Additional ROPs
548 Prima implements extra features for compositing on images outside the
550 begin_paint/end_paint brackets. It supports the following 12 Porter-
551 Duff operators and some selected Photoshop blend operators:
552 rop::Clear rop::Add
554 rop::Xor rop::Multiply
555 rop::SrcOver rop::Screen
556 rop::DstOver rop::Overlay
557 rop::SrcCopy rop::Darken
558 rop::DstCopy rop::Lighten
559 rop::SrcIn rop::ColorDodge
560 rop::DstIn rop::ColorBurn
561 rop::SrcOut rop::HardLight
562 rop::DstOut rop::SoftLight
563 rop::SrcAtop rop::Difference
564 rop::DstAtop rop::Exclusion
565 Transparency control
567 There is defined a set of constants to apply a constant source and
568 destination alpha to when there is no alpha channel available:
569 rop::SrcAlpha
571 rop::SrcAlphaShift
572 rop::DstAlpha
573 rop::DstAlphaShift
574 Combine the rop constant using this formula:
576 $rop = rop::XXX |
578 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
579 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
580 or "rop::alpha($rop, [ $src_alpha, [ $dst_alpha ]])" call that does
582 the same.
583 Also, the function "rop::blend($alpha)" creates a rop constant for
585 simple blending of two images by the following formula:
586 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
588 "rop::alpha" also can be used for drawing on image outside
590 begin_paint/end_paint:
591 $image->rop( rop::alpha( rop::SrcOver, 128 ));
593 $image->ellipse( 5, 5, 5, 5 );
594 When used with icons, their source and/or destination alpha
596 channels are additionally multiplied with these values.
597 rop::Premultiply
599 When this bit is set, source pixels will be multiplied with alpha
600 before blending
601 rop::ConstantColor
603 This bit is used when the alpha is defined but the main bits
604 aren't. In this case, the main bits are filled from the
605 destination's image color, and the source image treated as alpha
606 channel. The following code applies a solid green shade with a mask
607 loaded from file.
608 $src->load('8-bit gray mask.png');
610 $dst->color(cl::LightGreen);
611 $dst->put_image( 0,0,$src,rop::SrcOver | rop::ConstantColor | rop::Premultiply);
612 Also, remember "rop::Premultiply" for proper results.
614 Coordinates
616 The Prima toolkit employs the XY grid, where X ascends rightwards and Y
617 ascends upwards. There, the (0,0) location is the bottom-left pixel of
618 a canvas.
619 All graphic primitives use inclusive-inclusive boundaries. For
621 example,
622 $d-> bar( 0, 0, 1, 1);
624 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
626 The coordinate origin can be shifted using "::translate" property, that
628 translates the (0,0) point to the given offset. Calls to "::translate",
629 "::clipRect" and "::region" always use the 'physical' (0,0) point,
630 whereas the plotting methods use the transformation result, the
631 'logical' (0,0) point.
632 As noted before, these three properties cannot be used in when an
634 object is in the disabled state.
635
637 Graphic context properties
638 backColor COLOR
639 Sets background color to the graphic context. All drawing routines
640 that use non-solid or transparent fill or line patterns use this
641 property value.
642 color COLOR
644 Sets foreground color to the graphic context. All drawing routines
645 use this property value.
646 clipRect X1, Y1, X2, Y2
648 Selects the clipping rectangle corresponding to the physical canvas
649 origin. On get-call, returns the extent of the clipping area, if
650 it is not rectangular, or the clipping rectangle otherwise. The
651 code
652 $d-> clipRect( 1, 1, 2, 2);
654 $d-> bar( 0, 0, 1, 1);
655 thus affects only one pixel at (1,1).
657 Set-call discards the previous "::region" value.
659 Note: "::clipRect" can not be used while the object is in the
661 paint-disabled state, its context is neither recorded nor used as a
662 template ( see "Graphic context and canvas") -- except on images.
663 fillMode INTEGER
665 Affects filling style of complex polygonal shapes filled by
666 "fillpoly". If "fm::Winding", the filled shape contains no holes;
667 if "fm::EvenOdd", holes are present where the shape edges cross.
668 "fm::Overlay" flag can be combined with these to counter an
670 intrinsic defect of filled shaped both in Win32 and X11 that don't
671 exactly follow polygon vertices. When supplied, it overlays a
672 polygon over the filled shape, so that the latter falls exactly in
673 the boundaries defined by vertices. This is desirable when one
674 wants to follow polygon vertices, but is not desirable when a shape
675 has holes in it connected in a way that the polygon overlay may
676 leave connection edges over them.
677 Default value: "fm::Winding|fm::Overlay"
679 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
681 Selects 8x8 fill pattern that affects primitives that plot filled
682 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
683 fill_sector(), floodfill().
684 Accepts either a "fp::" constant or a reference to an array of 8
686 integers, each representing 8 bits of each line in a pattern, where
687 the first integer is the topmost pattern line, and the bit 0x80 is
688 the leftmost pixel in the line.
689 There are some predefined patterns, that can be referred via "fp::"
691 constants:
692 fp::Empty
694 fp::Solid
695 fp::Line
696 fp::LtSlash
697 fp::Slash
698 fp::BkSlash
699 fp::LtBkSlash
700 fp::Hatch
701 fp::XHatch
702 fp::Interleave
703 fp::WideDot
704 fp::CloseDot
705 fp::SimpleDots
706 fp::Borland
707 fp::Parquet
708 ( the actual patterns are hardcoded in primguts.c ) The default
710 pattern is fp::Solid.
711 An example below shows encoding of fp::Parquet pattern:
713 # 76543210
715 84218421 Hex
716 0 $ $ $ 51
718 1 $ $ 22
719 2 $ $ $ 15
720 3 $ $ 88
721 4 $ $ $ 45
722 5 $ $ 22
723 6 $ $ $ 54
724 7 $ $ 88
725 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
727 On a get-call always returns an array, never a "fp::" constant.
729 fillPatternOffset X, Y
731 Origin coordinates for the "fillPattern", from 0 to 7.
732 font \%FONT
734 Manages font context. FONT hash acceptable values are "name",
735 "height", "size", "width", "style" and "pitch".
736 Synopsis:
738 $d-> font-> size( 10);
740 $d-> font-> name( 'Courier');
741 $d-> font-> set(
742 style => $x-> font-> style | fs::Bold,
743 width => 22
744 );
745 See "Fonts" for the detailed descriptions.
747 Applies to text_out(), get_text_width(), get_text_box(),
749 get_font_abc(), get_font_def(), render_glyph().
750 fontMapperPalette INDEX, [\%FONT | COMMAND]
752 A pseudo-property that manages access to a set of fonts used for
753 substitution in polyfont shaping (see "text_shape"). INDEX is the
754 same font index used in "fonts" array returned from "text_shape",
755 if polyfont was used (where 0 is the current font).
756 There are two font lists used in the substituion mechanism, passive
758 and active. The passive font list is initiated during the toolkit
759 start and is never changed. Each font there is addressed by
760 "INDEX". When the actual search for a glyph is initiated, these
761 fonts are queried in the loop and are checked if they contain the
762 required glyphs. These queries are cached, so that next time
763 lookups run much quicker. That way, an "active" font list is built,
764 and next substitutions use it before trying to look into the
765 passive list. Since the ordering of fonts is system based, and is
766 rather random, some fonts may not be a good or aesthetic
767 substition. Therefore "fontMapperPallette" can assist in adding or
768 removing particular fonts to the active list, potentially allowing
769 an application to store and load user-driven selection of
770 substitution fonts.
771 "fontMapperPallette" is a pseudo-property, such that it is not
773 symmetric as real properties are; its call formats are several and
774 not orthogonal to each other neither in syntax nor functionality.
775 Therefore these may change in future.
776 As a getter, the property returns the following depending on INDEX:
778 If it is -1, returns how many fonts are in the passive list. If 0,
779 which means the current font, returns the index of the current font
780 if it is found in the palette, or 0 otherwise. If greater than
781 zero, returns the substitution FONT record from the passive list.
782 As a setter, manages the active list, and uses COMMAND integer as a
784 second argument. If COMMAND is 0, removes the INDEXth font from
785 the active list, and if 1, marks it for immediate scanning and
786 adding to the active list. The font is added in the end of the
787 list, after the existing active entries.
788 lineEnd VALUE
790 Selects a line ending cap for plotting primitives. VALUE can be one
791 of
792 le::Flat
794 le::Square
795 le::Round
796 constants. le::Round is the default value.
798 lineJoin VALUE
800 Selects a line joining style for polygons. VALUE can be one of
801 lj::Round
803 lj::Bevel
804 lj::Miter
805 constants. lj::Round is the default value.
807 linePattern PATTERN
809 Selects a line pattern for plotting primitives. PATTERN is either
810 a predefined "lp::" constant, or a string where each even byte is a
811 length of a dash, and each odd byte is a length of a gap.
812 The predefined constants are:
814 lp::Null # "" /* */
816 lp::Solid # "\1" /* ___________ */
817 lp::Dash # "\x9\3" /* __ __ __ __ */
818 lp::LongDash # "\x16\6" /* _____ _____ */
819 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
820 lp::Dot # "\1\3" /* . . . . . . */
821 lp::DotDot # "\1\1" /* ............ */
822 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
823 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
824 Not all systems are capable of accepting user-defined line
826 patterns, and in such situation the "lp::" constants are mapped to
827 the system-defined patterns. In Win9x, for example, lp::DashDotDot
828 is much different from its string definition.
829 Default value is lp::Solid.
831 lineWidth WIDTH
833 Selects a line width for plotting primitives. If a VALUE is 0,
834 then a cosmetic pen is used - the thinnest possible line that a
835 device can plot. If a VALUE is greater than 0, then a geometric pen
836 is used - the line width is set in device units. There is a subtle
837 difference between VALUE 0 and 1 in a way the lines are joined.
838 Default value is 0.
840 miterLimit VALUE
842 When path segments connect at a sharp angle, a miter join results
843 in a spike that extends well beyond the connection point. The
844 purpose of the miter limit is to cut off such spikes when they
845 become objectionably long. At any given corner, the miter length is
846 the distance from the point at which the inner edges of the stroke
847 intersect to the point at which the outside edges of the strokes
848 intersect-in other words, the diagonal length of the miter. This
849 distance increases as the angle between the segments decreases. If
850 the ratio of the miter length to the line width exceeds the miter
851 limit parameter, stroke treats the corner with a bevel join instead
852 of a miter join. The ratio of miter length to line width is
853 directly related to the angle j between the segments by the
854 formula:
855 r = 1/sin(j/2)
857 Default value is 10.0.
859 Asssuming line join is "lj::Miter" and line angle is 30 degrees:
861 miter limit = 1.0: \__/
863 miter limit = 9.0: \ /
865 \/
866 Note: does not work under X11.
868 palette [ @PALETTE ]
870 Selects solid colors in a system palette, as many as possible.
871 PALETTE is an array of integer triplets, where each is R, G and B
872 component. The call
873 $d-> palette([128, 240, 240]);
875 selects a gray-cyan color, for example.
877 The return value from get-call is the content of the previous set-
879 call, not the actual colors that were copied to the system palette.
880 region OBJECT
882 Selects a clipping region applied to all drawing and painting
883 routines. On setting, the OBJECT is either undef, then the clip
884 region is erased ( no clip ), or a Prima::Image object with a bit
885 depth of 1. The bit mask of OBJECT is applied to the system
886 clipping region. Or, it is a Prima::Region object. If the OBJECT
887 is smaller than the drawable, its exterior is assigned to clipped
888 area as well. Discards the previous "::clipRect" value; successive
889 get-calls to "::clipRect" return the boundaries of the region.
890 On getting, OBJECT is either undef or Prima::Region object.
892 Note: "::region" can not be used while the object is in the paint-
894 disabled state, its context is neither recorded nor used as a
895 template ( see "Graphic context and canvas").
896 resolution X, Y
898 A read-only property. Returns horizontal and vertical device
899 resolution in dpi.
900 rop OPERATION
902 Selects raster operation that applies to foreground color plotting
903 routines.
904 See also: "::rop2", "Raster operations".
906 rop2 OPERATION
908 Selects raster operation that applies to background color plotting
909 routines.
910 See also: "::rop", "Raster operations".
912 textOpaque FLAG
914 If FLAG is 1, then text_out() fills the text background area with
915 "::backColor" property value before drawing the text. Default value
916 is 0, when text_out() plots text only.
917 See get_text_box().
919 textOutBaseline FLAG
921 If FLAG is 1, then text_out() plots text on a given Y coordinate
922 correspondent to font baseline. If FLAG is 0, a Y coordinate is
923 mapped to font descent line. Default is 0.
924 translate X_OFFSET, Y_OFFSET
926 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
927 affect "::clipRect" and "::region". Not cumulative, so the call
928 sequence
929 $d-> translate( 5, 5);
931 $d-> translate( 15, 15);
932 is equivalent to
934 $d-> translate( 15, 15);
936 Note: "::translate" can not be used while the object is in the
938 paint-disabled state, its context is neither recorded nor used as a
939 template ( see "Graphic context and canvas").
940 Other properties
942 height HEIGHT
943 Selects the height of a canvas.
944 size WIDTH, HEIGHT
946 Selects the extent of a canvas.
947 width WIDTH
949 Selects the width of a canvas.
950 Graphic primitives methods
952 alpha ALPHA <X1, Y1, X2, Y2>
953 Fills rectangle in the alpha channel, filled with ALPHA value
954 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
955 parameters, in this case fills all canvas area.
956 Has only effect on layered surfaces.
958 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
960 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
961 from START_ANGLE to END_ANGLE.
962 Context used: color, backColor, lineEnd, linePattern, lineWidth,
964 miterLimit, rop, rop2
965 bar X1, Y1, X2, Y2
967 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
968 Context used: color, backColor, fillPattern, fillPatternOffset,
970 rop, rop2
971 bars @RECTS
973 Draws a set of filled rectangles. RECTS is an array of integer
974 quartets in format (X1,Y1,X2,Y2).
975 Context used: color, backColor, fillPattern, fillPatternOffset,
977 rop, rop2
978 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
980 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
981 from START_ANGLE to END_ANGLE and connects its ends with the
982 straight line.
983 Context used: color, backColor, lineEnd, linePattern, lineWidth,
985 miterLimit, rop, rop2
986 clear <X1, Y1, X2, Y2>
988 Draws rectangle filled with pure background color within (X1,Y1) -
989 (X2,Y2) extents. Can be called without parameters, in this case
990 fills all canvas area.
991 Context used: backColor, rop2
993 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
995 TAB_INDENT = 1 ]
996 Draws several lines of text one under another with respect to align
997 and break rules, specified in FLAGS and TAB_INDENT tab character
998 expansion.
999 "draw_text" is a convenience wrapper around "text_wrap" for drawing
1001 the wrapped text, and also provides the tilde ( ~ )- character
1002 underlining support.
1003 The FLAGS is a combination of the following constants:
1005 dt::Left - text is aligned to the left boundary
1007 dt::Right - text is aligned to the right boundary
1008 dt::Center - text is aligned horizontally in center
1009 dt::Top - text is aligned to the upper boundary
1010 dt::Bottom - text is aligned to the lower boundary
1011 dt::VCenter - text is aligned vertically in center
1012 dt::DrawMnemonic - tilde-escapement and underlining is used
1013 dt::DrawSingleChar - sets tw::BreakSingle option to
1014 Prima::Drawable::text_wrap call
1015 dt::NewLineBreak - sets tw::NewLineBreak option to
1016 Prima::Drawable::text_wrap call
1017 dt::SpaceBreak - sets tw::SpaceBreak option to
1018 Prima::Drawable::text_wrap call
1019 dt::WordBreak - sets tw::WordBreak option to
1020 Prima::Drawable::text_wrap call
1021 dt::ExpandTabs - performs tab character ( \t ) expansion
1022 dt::DrawPartial - draws the last line, if it is visible partially
1023 dt::UseExternalLeading - text lines positioned vertically with respect to
1024 the font external leading
1025 dt::UseClip - assign ::clipRect property to the boundary rectangle
1026 dt::QueryLinesDrawn - calculates and returns number of lines drawn
1027 ( contrary to dt::QueryHeight )
1028 dt::QueryHeight - if set, calculates and returns vertical extension
1029 of the lines drawn
1030 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
1031 dt::WordWrap - performs word wrapping by the width of the boundaries
1032 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
1033 dt::UseExternalLeading
1034 Context used: color, backColor, font, rop, textOpaque,
1036 textOutBaseline
1037 ellipse X, Y, DIAMETER_X, DIAMETER_Y
1039 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
1040 axes.
1041 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1043 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1045 Fills a chord outline with center in X, Y and DIAMETER_X and
1046 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see chord()).
1047 Context used: color, backColor, fillPattern, fillPatternOffset,
1049 rop, rop2
1050 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
1052 Fills an elliptical outline with center in X, Y and DIAMETER_X and
1053 DIAMETER_Y axes.
1054 Context used: color, backColor, fillPattern, fillPatternOffset,
1056 rop, rop2
1057 fillpoly \@POLYGON
1059 Fills a polygonal area defined by POLYGON set of points. POLYGON
1060 must present an array of integer pair in (X,Y) format. Example:
1061 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
1063 Context used: color, backColor, fillPattern, fillPatternOffset,
1065 rop, rop2, fillMode
1066 Returns success flag; if failed, $@ contains the error.
1068 See also: polyline().
1070 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1072 Fills a sector outline with center in X, Y and DIAMETER_X and
1073 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see sector()).
1074 Context used: color, backColor, fillPattern, fillPatternOffset,
1076 rop, rop2
1077 fill_spline \@VERTICES, %OPTIONS
1079 Fills a polygonal area defined by the curve, projected by applying
1080 B-spline curve based on set of VERTICES. VERTICES must present an
1081 array of integer pair in (X,Y) format. Example:
1082 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1084 Context used: color, backColor, fillPattern, fillPatternOffset,
1086 rop, rop2
1087 Returns success flag; if failed, $@ contains the error.
1089 See also: spline, render_spline
1091 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1093 Fills an area of the canvas using the current fill context. The
1094 area is assumed to be bounded as specified by the SINGLEBORDER
1095 parameter. SINGLEBORDER can be 0 or 1.
1096 SINGLEBORDER = 0: The fill area is bounded by the color specified
1098 by the COLOR parameter.
1099 SINGLEBORDER = 1: The fill area is defined by the color that is
1101 specified by COLOR. Filling continues outward in all directions as
1102 long as the color is encountered. This style is useful for filling
1103 areas with multicolored boundaries.
1104 Context used: color, backColor, fillPattern, fillPatternOffset,
1106 rop, rop2
1107 line X1, Y1, X2, Y2
1109 Plots the straight line from (X1,Y1) to (X2,Y2).
1110 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1112 lines \@LINES
1114 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1115 lines() plots the straight line per quartet.
1116 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1118 Returns success flag; if failed, $@ contains the error.
1120 new_aa_surface
1122 Returns a new antialiasing surface object. See
1123 Prima::Drawable::Antialias for usage and details.
1124 new_gradient
1126 Returns a new gradient object. See Prima::Drawable::Gradient for
1127 usage and details.
1128 new_path
1130 Returns a new path object. See Prima::Drawable::Path for usage and
1131 details.
1132 pixel X, Y, <COLOR>
1134 ::pixel is a property - on set-call it changes the pixel value at
1135 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1136 pixel value at (X,Y).
1137 No context is used. May return "cl::Invalid" to signal an error or
1139 the out-of-boundaries condition.
1140 polyline \@POLYGON
1142 Draws a polygonal area defined by the POLYGON set of points.
1143 POLYGON must contain an array of integer pairs in (X,Y) format.
1144 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1146 lineEnd, miterLimit, rop, rop2
1147 Returns success flag; if failed, $@ contains the error.
1149 See also: fillpoly().
1151 put_image X, Y, OBJECT, [ ROP ]
1153 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1154 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1155 specified, it is used. Otherwise, value of "::rop" property is
1156 used.
1157 Returns success flag; if failed, $@ contains the error.
1159 Context used: rop; color and backColor for a monochrome
1161 DeviceBitmap
1162 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1164 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1165 Draws the OBJECT's source rectangle into the destination rectangle,
1166 stretching or compressing the source bits to fit the dimensions of
1167 the destination rectangle, if necessary. The source rectangle
1168 starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide and
1169 SRC_HEIGHT pixels tall. The destination rectangle starts at (X,Y),
1170 and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT) pixels
1171 tall. If DEST_WIDTH or DEST_HEIGHT are negative, a mirroring by
1172 respective axis is performed.
1173 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1175 No context is used, except color and backColor for a monochrome
1177 DeviceBitmap
1178 Returns success flag; if failed, $@ contains the error.
1180 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1182 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1183 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1184 specified, paints an inferior rectangle with it, otherwise the
1185 inferior rectangle is not touched.
1186 Context used: rop; color and backColor for a monochrome
1188 DeviceBitmap
1189 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1191 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1192 line width.
1193 No context is used.
1195 rectangle X1, Y1, X2, Y2
1197 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1198 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1200 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1202 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1203 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1204 two straight lines.
1205 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1207 miterLimit, rop, rop2
1208 spline \@VERTICES, %OPTIONS
1210 Draws a B-spline curve defined by set of VERTICES control points.
1211 VERTICES must present an array of integer pair in (X,Y) format.
1212 The following options are supported:
1214 closed BOOL = undef
1216 When not set, checks if the first and the last vertices point
1217 to the same point, and if yes, assumes a closed shape. Note - a
1218 closed shape rendering is implemented by adding degree minus
1219 two points to the set; this is important if "weight" or "knots"
1220 are specificed.
1221 degree INTEGER = 2
1223 The B-spline degree. Default is 2 (quadratic). Number of points
1224 supplied must be at least degree plus one.
1225 knots \@INTEGERS
1227 Array of integers, number of points plus degree plus one, which
1228 makes the result a Bezier curve. By default, if the shape is
1229 opened (i.e. first and last points are different), is set to
1230 represent a clamped array, so that the first and last points of
1231 the final curve match the first and the last control points. If
1232 the shape is closed, set to represent an unclamped array, so
1233 that no control points lie directly on the curve.
1234 precision INTEGER = 24
1236 Defines number of steps to split the curve into. The value is
1237 multiplied to the number of points and the result is used as
1238 number of steps.
1239 weight \@INTEGERS = [ 1, 1, 1, ... ]
1241 Array of integers, one for each point supplied. Assigning these
1242 can be used to convert B-spline into a NURBS. By default set of
1243 ones.
1244 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1246 miterLimit, rop, rop2
1247 See also: fill_spline, render_spline.
1249 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1251 Draws the OBJECT on the destination rectangle, stretching or
1252 compressing the source bits to fit the dimensions of the
1253 destination rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT
1254 are negative, a mirroring is performed. The destination rectangle
1255 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1256 pixels tall.
1257 If ROP raster operation is specified, it is used. Otherwise, value
1259 of "::rop" property is used.
1260 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1262 Returns success flag; if failed, $@ contains the error.
1264 Context used: rop
1266 text_out TEXT, X, Y
1268 Draws TEXT string at (X,Y). TEXT is either character string, or a
1269 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1270 "Prima::Drawable::Glyphs->glyphs" strings of glyphs.
1271 Returns success flag; if failed, $@ contains the error.
1273 Context used: color, backColor, font, rop, textOpaque,
1275 textOutBaseline
1276 text_shape TEXT, %OPTIONS
1278 Converts TEXT into set of glyphs, returns either a
1279 "Prima::Drawable::Glyphs" object, or a 0 integer when shaping is
1280 not necessary, or "undef" as an error.
1281 When Prima is compiled with "libfribidi", the method runs unicode
1283 bidirectional algorithm on TEXT that properly positions embedded
1284 directional text (f.ex. a latin quote inside an arabic text), see
1285 Unicode Standard Annex #9 for the details. Without the library
1286 only does minimal RTL alignment.
1287 Glyphs returned are positioned according to RTL directions given in
1289 TEXT using characters from uncode block "General Punctuation U+2000
1290 .. U+206F". Additionally, character ligation may be performed so
1291 that one or more characters are respresented by one or more glyphs.
1292 Such syntatic units, clusters, are adopted in Prima where
1293 appropriate, instead of character units, for selection, navigation
1294 etc in f.ex. "Prima::InputLine" and "Prima::Edit". Helper routines
1295 that translate clusters, glyphs, and characters into each other are
1296 found in Prima::Drawable::Glyphs.
1297 Options recognized:
1299 advances BOOLEAN = false
1301 Shaping process may or may not fill integer array of advances
1302 and positions for each glyphs, depending on the implementation.
1303 The advances are needed to represent f.ex. combining graphemes,
1304 when TEXT consisting of two characters, "A" and combining grave
1305 accent U+300 should be drawn as a single À cluster but are
1306 represented by two glyphs "A" and "`". The grave glyph has its
1307 own advance for standalone usage, but in this case it should be
1308 ignored, and that is achieved by filling advance table where
1309 the "A" advance is the normal glyph advance, whereas the
1310 advance of the "`" is zero. Also, the position table
1311 additionaly shifts glyph position by X and Y coordinates, when
1312 that is needed (f.ex. it might be positioned differently by the
1313 vertical axis on "a" and "A").
1314 Setting this options to "true" will force fill advance and
1316 positioning tables. These tables can be manipulated later, and
1317 are respected by "text_out" and "get_text_width".
1318 language STRING = undef
1320 When set, shaping process can take in the account the language
1321 of the text. F.ex. text "ae" might be shaped as a single glyph
1322 æ for the Latin language, but never for the English.
1323 level INTEGER = ts::Full
1325 Selects the shaping (i.e. text to glyph conversion) level, how
1326 the system should treat the input text and how deep the shaping
1327 should go.
1328 One of the following "ts::XXX" options:
1330 ts::Bytes
1332 Treats input text as non-unicode locale-specific
1333 codepoints, characters higher than 255 are treated as
1334 chr(255). Reordering never happens, font substition never
1335 happens, kerning and ligation never happens; returns glyph
1336 indexes in a 1:1 mapping for each codepoint.
1337 ts::None
1339 Performs quick null shaping without mapping to the font
1340 glyphs, but only running bidirectional algorithm on the
1341 text. On the return, "glyphs", as well as eventual
1342 "advances" and "positions", are filled with zeros, but
1343 "indexes" are filled with the proper character offsets,
1344 effectively making it a visual-to-logical map since the
1345 number of glyphs will always be equal to the number of
1346 characters in TEXT, because ligation never happens here
1347 (except when TEXT contains unicode directional characters
1348 such as isolates etc - those are removed from the output).
1349 By default, advances and positions are not filled, but if
1351 the "advances" option is set, fills them with zeros.
1352 ts::Glyphs
1354 Applies the unicode bidi algoritm and maps the result onto
1355 font glyphs. Ligation and kerning doesn't happen here,
1356 it's basically same as "ts::None" but with the glyph
1357 mapping part.
1358 By default, advances and positions are not filled, but if
1360 "advances" option is set, fills the advances array with
1361 character glyph advances and the positions array with
1362 zeros.
1363 May fill the "fonts" array if the "polyfont" option is set.
1365 ts::Full
1367 Applies the unicode bidi algorithm, and runs the full
1368 shaping on the result. Ligation and kerning may occur.
1369 Always fills the advances and positions array; the
1370 "advances" option is ignored.
1371 If the system or the selected font does not support
1373 shaping, tries to ligate known arabic shapes using the
1374 fribidi library, if available. Also in this case does not
1375 return the advances and positions by default, but if
1376 "advances" option is set, fills the advances array with
1377 character glyph advances and the positions array with
1378 zeros.
1379 May fill the "fonts" array if the "polyfont" option is set.
1381 pitch INTEGER
1383 When the "polyfont" is set (default) and thus font substitution
1384 is desired, filters only fonts that match "pitch", either
1385 "fp::Variable" or "fp::Fixed". By default will be set to
1386 "fp::Fixed" if the current for is monospaced, but to
1387 "fp::Default" matching all fonts, otherwise.
1388 polyfont BOOLEAN = true
1390 If set, scans if the currently selected font supports all
1391 unicode points, and if not, selects a substituions from a pre-
1392 populated list, taking into account the font pitch (see "pitch"
1393 above). In cases where the current font has not enough glyphs
1394 to shape all the requested unicode points, font substitution is
1395 performed, and the result contains an extra array "fonts" (see
1396 "fonts" in Prima::Drawable::Glyphs). When the current font has
1397 all needed glyphs, the fonts array is not created.
1398 The font list access is available through "fontMapperPallette".
1400 Valid only with shaping levels "ts::Glyphs" and "ts::Full".
1402 reorder BOOLEAN = true
1404 When set, unicode bidi algorithm is used to reorder codepoints,
1405 and additionally RTL codepoints may be reversed (depending on
1406 direction context).
1407 When unset, no such reordering occurs, to emulate as much as
1409 possible a behavior that each text grapheme is being mapped to
1410 a glyph cluster exactly as it occurs in the input text, from
1411 left to right. Note that bidi reordering still may occur
1412 internally, since system shapers may reverse placement of RTL
1413 characters, so that the Prima reordering is needed to cancel
1414 this. In theory the caller shouldn't see the difference as
1415 these should cancel each other, but if Prima miscalculates the
1416 expected way the system shaper does the bidi processing, it
1417 might.
1418 A similar effect can be reached by prepending the text with
1420 U+202D (LEFT-TO-RIGHT OVERRIDE).
1421 rtl BOOLEAN
1423 If set to 1, default text direction is assumed as RTL, and as
1424 LTR if set to 0. If unset, the text direction is taken from
1425 "textDirection" in Prima::Application.
1426 skip_if_simple BOOLEAN = false
1428 When set, checks whether the shaping result is identical to the
1429 input, in a sense that a call to "text_out(TEXT)" and a call to
1430 "text_shape_out(TEXT)" produce identical results. Majority of
1431 english text will fall into that category, and when that indeed
1432 happens, returns integer value 0 instead of a glyph object.
1433 See also "text_shape_out", "get_text_shape_width",
1435 "text_wrap_shape".
1436 text_shape_out TEXT, X, Y[, RTL]
1438 Runs shaping on TEXT character string with the RTL flag (or
1439 "$::application->textDirection". Draws the resulting glyph string
1440 at (X,Y).
1441 Returns success flag; if failed, $@ contains the error.
1443 Context used: color, backColor, font, rop, textOpaque,
1445 textOutBaseline
1446 Methods
1448 begin_paint
1449 Enters the enabled ( active paint ) state, returns success flag; if
1450 failed, $@ contains the error. Once the object is in enabled
1451 state, painting and drawing methods can perform write operations on
1452 a canvas.
1453 See also: "end_paint", "begin_paint_info", "Graphic context and
1455 canvas"
1456 begin_paint_info
1458 Enters the information state, returns success flag; if failed, $@
1459 contains the error. The object information state is same as
1460 enabled state ( see "begin_paint"), except painting and drawing
1461 methods do not change the object canvas.
1462 See also: "end_paint_info", "begin_paint", "Graphic context and
1464 canvas"
1465 can_draw_alpha
1467 Returns whether using alpha bits operation on the drawable will
1468 have any effect or not. Note that the drawable might not
1469 necessarily have an alpha channel, for example a normal RGB image
1470 is capable to be painted on wil alpha while not having any alpha on
1471 its own. On unix, all non-1 bit drawables return true if Prima was
1472 compiled with XRender support and if that extension is present on
1473 the X server. On windows, all non-1 bit drawables return true
1474 unconditionally.
1475 See also: "has_alpha_layer"
1477 end_paint
1479 Exits the enabled state and returns the object to a disabled state.
1480 See also: "begin_paint", "Graphic context and canvas"
1482 end_paint_info
1484 Exits the information state and returns the object to a disabled
1485 state.
1486 See also: "begin_paint_info", "Graphic context and canvas"
1488 font_match \%SOURCE, \%DEST, PICK = 1
1490 Performs merging of two font hashes, SOURCE and DEST. Returns the
1491 merge result. If PICK is true, matches the result with a system
1492 font repository.
1493 Called implicitly by "::font" on set-call, allowing the following
1495 example to work:
1496 $d-> font-> set( size => 10);
1498 $d-> font-> set( style => fs::Bold);
1499 In the example, the hash 'style => fs::Bold' does not overwrite the
1501 previous font context ( 'size => 10' ) but gets added to it ( by
1502 font_match()), providing the resulting font with both font
1503 properties set.
1504 fonts <FAMILY = "", ENCODING = "">
1506 Member of "Prima::Application" and "Prima::Printer", does not
1507 present in "Prima::Drawable".
1508 Returns an array of font metric hashes for a given font FAMILY and
1510 ENCODING. Every hash has full set of elements described in
1511 "Fonts".
1512 If called without parameters, returns an array of same hashes where
1514 each hash represents a member of font family from every system font
1515 set. It this special case, each font hash contains additional
1516 "encodings" entry, which points to an array of encodings available
1517 for the font.
1518 If called with FAMILY parameter set but no ENCODING is set,
1520 enumerates all combinations of fonts with all available encodings.
1521 If called with FAMILY set to an empty string, but ENCODING
1523 specified, returns only fonts that can be displayed with the
1524 encoding.
1525 Example:
1527 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1529 get_bpp
1531 Returns device color depth. 1 is for black-and-white monochrome, 24
1532 for true color, etc.
1533 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1535 Returns ABC font metrics for the given range, starting at
1536 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1537 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1538 responsible of representation of characters in 127-255 range. If
1539 0, the default, encoding-dependent characters are assumed. If 1,
1540 the U007F-U00FF glyphs from Latin-1 set are used.
1541 The result is an integer array reference, where every character
1543 glyph is referred by three integers, each triplet containing A, B
1544 and C values.
1545 For detailed explanation of ABC meaning, see "Font ABC metrics";
1547 Context used: font
1549 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1551 Same as "get_font_abc", but for vertical mertics. Is expensive on
1552 bitmap fonts, because to find out the correct values Prima has to
1553 render glyphs on bitmaps and scan for black and white pixels.
1554 Vector fonts are not subject to this, and the call is as effective
1556 as "get_font_abc".
1557 get_font_languages
1559 Returns array of ISO 639 strings that can be displayed using glyphs
1560 available in the currently selected font.
1561 get_font_ranges
1563 Returns array of integer pairs denoting unicode indices of glyphs
1564 covered by the currently selected font. Each pair is the first and
1565 the last index of a contiguous range.
1566 Context used: font
1568 get_nearest_color COLOR
1570 Returns a nearest possible solid color in representation of the
1571 graphic device. Always returns same color if the device bit depth
1572 is equal or greater than 24.
1573 get_paint_state
1575 Returns paint state value on of ps:: constants - "ps::Disabled" if
1576 the object is in the disabled state, "ps::Enabled" for the enabled
1577 state, "ps::Information" for the information state.
1578 For brevity, mb::Disabled is equal to 0 so this allows for simple
1580 boolean testing whether one can get/set graphical properties on an
1581 object.
1582 See "Graphic context and canvas" for more.
1584 get_physical_palette
1586 Returns an array of integers in (R,G,B) format, where each color
1587 entry is in the 0 - 255 range.
1588 The physical palette array is non-empty only on paletted graphic
1590 devices, the true color devices return an empty array.
1591 The physical palette reflects the solid colors currently available
1593 to all programs in the system. The information is volatile if the
1594 system palette can change colors, since any other application may
1595 request to change the system colors at any moment.
1596 get_text_shape_width TEXT, [ FLAGS ]
1598 Runs shaping on TEXT character string with text direction either
1599 taken from "FLAGS & to::RTL" value, or from the or
1600 "$::application->textDirection". Returns the shaping result width
1601 as if it would be drawn using currently selected font.
1602 If "FLAGS & to::AddOverhangs" is set, the first character's
1604 absolute A value and the last character's absolute C value are
1605 added to the string if they are negative.
1606 get_text_width TEXT, ADD_OVERHANG = 0
1608 Returns TEXT string width if it would be drawn using currently
1609 selected font. TEXT is either a character string, or a
1610 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1611 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1612 If ADD_OVERHANG is 1, the first character's absolute A value and
1614 the last character's absolute C value are added to the string if
1615 they are negative.
1616 See more on ABC values at "Font ABC metrics".
1618 Context used: font
1620 get_text_box TEXT
1622 Returns TEXT string extensions if it would be drawn using currently
1623 selected font. TEXT is either a character string, or a
1624 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1625 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1626 The result is an anonymous array of 5 points ( 5 integer pairs in
1628 (X,Y) format). These 5 points are offsets for the following string
1629 extents, given the string is plotted at (0,0):
1630 1: start of string at ascent line ( top left )
1632 2: start of string at descent line ( bottom left )
1634 3: end of string at ascent line ( top right )
1636 4: end of string at descent line ( bottom right )
1638 5: concatenation point
1640 The concatenation point coordinates (XC,YC) are coordinated passed
1642 to consequent text_out() call so the conjoint string would plot as
1643 if it was a part of TEXT. Depending on the value of the
1644 "textOutBaseline" property, the concatenation point is located
1645 either on the baseline or on the descent line.
1646 Context used: font, textOutBaseline
1648 1 3 3 4
1650 ** ****
1651 * * *
1652 *** ***
1653 * * *
1654 **** **
1655 2 4 1 2
1656 has_alpha_layer
1658 Returns true if the drawable has an alpha channel. If the drawable
1659 is treated as a source, it means its alpha content will be
1660 respected when drawing on another surface. If the drawable is
1661 treated as a destination, it means that its alpha content will be
1662 updated if drawing on it uses alpha bits.
1663 See also: "can_draw_alpha".
1665 render_glyph INDEX, %OPTIONS
1667 Returns glyph representation as an outline. The outline is an
1668 integer array, formed as a set of plotting commands. Each commnds
1669 is a "ggo::" constant, followed by number of points, followed by
1670 the 2D point coordinates in 1/64 pixels.
1671 Options recognized:
1673 glyph BOOL
1675 If set, INDEX is treated as the glyph index rather than
1676 character index. Default is false.
1677 hints BOOL
1679 Is set, hinting is enabled. Default is true.
1680 unicode BOOL
1682 If set, INDEX is threated as a utf8 character index, otherwise
1683 a locale-specific index. Default is false.
1684 The "ggo::" commands are:
1686 ggo::Move - move point
1688 ggo::Line - plot line
1689 ggo::Conic - plot 2-degree spline
1690 ggo::Cubic - plot 3-degree spline
1691 render_polyline \@POLYLINE, %OPTIONS
1693 Performs calculations on POLYLINE, defined by OPTIONS. The
1694 following options are recognized:
1695 matrix A,B,C,D,U,V
1697 If supplied, performs matrix transformation on each polyline
1698 vertex:
1699 X' = AX + CY + U
1701 Y' = BX + DY + V
1702 and returns the new polyline
1704 box BOOLEAN
1706 If set, instead of polyline vertices, calculates the box
1707 extents of the polyline (either original or after the matrix
1708 transform, depending on whether "matrix" option was supplied or
1709 not), and returns 4 numerics for left,bottom,width,and height
1710 of the box enclosure.
1711 integer BOOLEAN
1713 By default the result is returned as a set of floating point
1714 numerics, however if integer results are needed, the results
1715 are transformed to integers using the int = float + ((float <
1716 0) ? -0.5 : 0.5) formula.
1717 render_spline \@VERTICES, %OPTIONS
1719 Renders B-spline curve from set of VERTICES to a polyline with
1720 given options.
1721 The method is internally used by "spline" and "fill_spline", and is
1723 provided for cases when these are insufficient. See description of
1724 options in spline.
1725 text_wrap TEXT, WIDTH, OPTIONS, [TAB_INDENT = 8, FROM = 0, LENGTH = -1,
1727 GLYPHS]
1728 Breaks TEXT string in chunks that must fit into WIDTH pixels wide
1729 box ( for WIDTH >= 0 ). TEXT is either character string, or a
1730 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1731 "Prima::Drawable::Glyphs->glyphs" strings of glyphs. In the glyph
1732 cases, some wrapping options are not applicable. It is possible to
1733 send both text as TEXT and its shaped representation as GLYPHS.
1734 The break algorithm and its result are governed by OPTIONS integer
1736 value which is a combination of "tw::" constants:
1737 tw::CalcMnemonic
1739 Use 'hot key' semantics, when a character preceded by ~ has
1740 special meaning, f ex it gets underlined when used in menus.
1741 If this bit is set, the first tilde character used as an escape
1742 is not calculated, and never appears in the result apart from
1743 the escaped character.
1744 Not applicable in glyph wrapping.
1746 tw::CollapseTilde
1748 In addition to tw::CalcMnemonic, removes '~' character from the
1749 resulting chunks.
1750 Not applicable in glyph wrapping.
1752 tw::CalcTabs
1754 If set, calculates a tab ('\t') character as TAB_INDENT times
1755 space characters.
1756 Not applicable in glyph wrapping.
1758 tw::ExpandTabs
1760 If set, expands tab ('\t') character as TAB_INDENT times space
1761 characters.
1762 Not applicable in glyph wrapping.
1764 tw::BreakSingle
1766 Defines procedure behavior when the text cannot be fit in
1767 WIDTH, does not affect anything otherwise.
1768 If set, returns an empty array. If unset, returns a text
1770 broken by minimum number of characters per chunk. In the
1771 latter case, the width of the resulting text blocks will exceed
1772 WIDTH.
1773 tw::NewLineBreak
1775 Forces new chunk after a newline character ('\n') is met. If
1776 UTF8 text is passed, unicode line break characters 0x2028 and
1777 0x2029 produce same effect as the newline character.
1778 Not applicable in glyph wrapping.
1780 tw::SpaceBreak
1782 Forces new chunk after a space character (' ') or a tab
1783 character ('\t') are met.
1784 Not applicable in glyph wrapping.
1786 tw::ReturnChunks
1788 Defines the result of text_wrap() function.
1789 If set, the array consists of integer pairs, where each is a
1791 text offset within TEXT and its length.
1792 If unset, the resulting array consists of text chunks.
1794 tw::ReturnGlyphs
1796 If GLYPHS are set (only together with TEXT), this option
1797 becomes available to get the resulting chunks as sub-sets of
1798 GLYPHS.
1799 tw::ReturnLines
1801 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1802 In glyph wrapping means "tw::ReturnGlyphs".
1804 tw::WordBreak
1806 If unset, the TEXT breaks as soon as the chunk width exceeds
1807 WIDTH. If set, tries to keep words in TEXT so they do not
1808 appear in two chunks, e.g. breaks TEXT by words, not by
1809 characters.
1810 Not applicable in glyph wrapping.
1812 tw::ReturnFirstLineLength
1814 If set, "text_wrap" proceeds until the first line is wrapped,
1815 either by width or ( if specified ) by break characters.
1816 Returns the length of the resulting line. Used for efficiency
1817 as the inverted "get_text_width" function.
1818 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1820 the last scalar of the array is a special hash reference. The hash
1821 contains extra information regarding the 'hot key' underline
1822 position - it is assumed that '~' - escapement denotes the
1823 underlined character. The hash contains the following keys:
1824 tildeLine
1826 Chunk index that contains the escaped character. Set to undef
1827 if no ~ - escape was found; the rest of the information in the
1828 hash is not relevant in this case.
1829 tildeStart
1831 Horizontal offset of a beginning of the line that underlines
1832 the escaped character.
1833 tildeEnd
1835 Horizontal offset of an end of the line that underlines the
1836 escaped character.
1837 tildeChar
1839 The escaped character.
1840 Context used: font
1842 text_wrap_shape TEXT, WIDTH = -1, %OPTIONS
1844 Runs "text_shape" over results from "text_wrap" call, with "TEXT",
1845 "WIDTH", $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are
1846 used in "text_shape" call. Where "text_wrap" returns text
1847 substrings or positions, return glyphs objects or their positions
1848 instead.
1849 When called with "tw::CalcMnemonic" options, recalculates the tilde
1851 position so it adapts to the glyph positions returned.
1852 If $OPTIONS{kashida} is set, performs kashida justification on the
1854 last wrapped line, using optional $OPTIONS{min_kashida} value ( see
1855 "arabic_justify" in Prima::Drawable::Glyphs ).
1856 If $OPTIONS{letter} or $OPTIONS{word} is set, performs interspace
1858 justfication on all but the last wrapped line.
1859
1861 Dmitry Karasik, <dmitry@karasik.eu.org>.
1862
1864 Prima, Prima::Object, Prima::Image, Prima::Region,
1865 Prima::Drawable::Path, Prima::Drawable::Glyphs
1866perl v5.34.0 2021-07-22 pod::Prima::Drawable(3)