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 See also: "graphic_context".
121 Color space
123 Graphic context and canvas operations rely completely on a system
124 implementation. The internal canvas color representation is therefore
125 system-specific, and usually could not be described in Prima
126 definitions. Often the only information available about color space is
127 its color depth.
128 Therefore all color manipulations, including dithering and antialiasing
130 are subject to system implementation, and can not be controlled from
131 perl code. When a property is set on the object in the disabled state,
132 it is recorded verbatim; color properties are no exception. After the
133 object switched to the enabled state, a color value is translated to
134 the system color representation, which might be different from Prima's.
135 For example, if the display color depth is 15 bits, 5 bits for every
136 component, then the white color value 0xffffff is 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 insufficient,
148 dithering algorithms may apply.
149 Note: not only color properties, but all graphic context properties
151 allow all possible values in the disabled state, which are translated
152 into system-allowed values when entering the enabled and the
153 information states. This feature can be used to test if a graphic
154 device is capable of performing certain operations ( for example, if it
155 supports raster 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 unsigned
166 integers in the discussed above RRGGBB format, however, the toolkit
167 defines some mnemonic color constants as well:
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 insufficient, where the primitives could be drawn with dithered or
189 incorrect colors. This usually happens on paletted displays, with 256
190 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 application that desires to display an image with
205 least distortion is advised to export its palette to an output device,
206 because images usually are not subject to automatic dithering
207 algorithms. Prima::ImageViewer module employs this scheme.
208 Antialiasing and alpha
210 If the system has capability for antialiased drawing and alpha
211 rendering, Prima can use it. The render mode can be turned on by
212 calling
213 $drawable->antialias(1)
215 which turns on the following effects:
217 • All primitives except images, "pixel", and "bar_alpha" are plotted
219 with antialiased edges (text is always antialiased when possible).
220 Arcs, lines, paths, all of them manifest adjacent pixels being
221 rendered with half-tones.
222 • Graphic coordinates are then used as floating point numbers, not
224 integers. That means that f ex a call
225 $drawable->rectangle(5.3, 5.3, 10, 10)
227 that had its coordinates automatically rounded to (5,5,10,10), now
229 will render the primitive with subpixel precision, where its two
230 edges will be divided between pixels 5 and 6, by using half-tones.
231 Another note on the rounding off coordinates: historically almost
233 all Prima pixel coordinates were integers, and implicit rounding of
234 the passed numbers were done using the "int" function, i e
235 int(0.7)=0 and int(-0.7)=0. This was later changed, breaking some
236 backward compatibility, and now the rounding function is a more
237 robust "R = floor(x + 0.5)", where "R(0.7) = 1" and "R(-0.7) = -1".
238 For the cases where system does not support antialiasing, Prima
240 provides Prima::Drawable::Antialias emulation class, available through
241 the "new_aa_surface" call. Internal image painting routines uses this
242 facility as well.
243 To see if alpha and antialiasing is supported on the system, check
245 "sv::Antialias" value. To see if a particular drawable supports alpha
246 layering, check "can_draw_alpha" method.
247 Note that in the render mode, all painting operations treat alpha
249 channel differently, which can have a dramatic difference on layered
250 surfaces. In the normal mode, the alpha channel is completely ignored,
251 and using normal mode paints on a layered widget always produces a
252 translucent window, because the alpha value will always be 0 and color
253 bits are assumed to be already premultiplied. In the render mode, alpha
254 channel is addressed by "alpha" property when drawing primitives, or in
255 "mask" property when drawing icons (again, drawing images and non-
256 layered bitmaps assumes alpha = 0). The same is valid for fill pattern
257 images and fill pattern icons.
258 Monochrome bitmaps
260 Prima has special rules when drawing a monochrome Prima::DeviceBitmap.
261 Such objects don't possess an inherent color palette, and by definition
262 are bitmaps with only two pixel values present, 0s and 1s. When a
263 monochrome bitmap is drawn, 0s are painted using the color value of the
264 target canvas "color" property, and 1s using the "backColor" value.
265 That means that the following code
267 $bitmap-> color(0);
269 $bitmap-> line(0,0,100,100);
270 $target-> color(cl::Green);
271 $target-> put_image(0,0,$bitmap);
272 produces a green line on $target.
274 When using monochrome bitmaps for logical operations, note that the
276 target colors should not be explicit 0 and 0xffffff, nor "cl::Black"
277 and "cl::White", but "cl::Clear" and "cl::Set" instead. The reason is
278 that on paletted displays, system palette may not necessarily contain
279 the white color under palette index (2^ScreenDepth-1). "cl::Set" thus
280 signals that the value should be "all ones", no matter what color it
281 represents, because it will be used for logical operations.
282 Fonts
284 Prima maintains its own font naming convention, that usually does not
285 conform to the system's. Since Prima's goal is interoperability, it
286 might be so that some system fonts would not be accessible from within
287 the toolkit.
288 Prima::Drawable provides property "::font", that accepts/returns a
290 hash, that represents the state of a font in the system graphic
291 context. The font hash keys that are acceptable on set-call are:
292 name
294 The font name string. If there is no such font, a default font name
295 is used. To select default font, a 'Default' string can be passed
296 with the same result ( unless the system has a font named
297 'Default', of course).
298 height
300 An integer value from 1 to MAX_INT. Specifies the desired extent of
301 a font glyph between descent and ascent lines in pixels.
302 size
304 An integer value from 1 to MAX_INT. Specifies the desired extent of
305 a font glyph between descent and internal leading lines in points.
306 The relation between "size" and "height" is
307 height - internal_leading
309 size = --------------------------- * 72.27
310 resolution
311 That differs from some other system representations: Win32, for
313 example, rounds 72.27 constant to 72.
314 width
316 A integer value from 0 to MAX_INT. If greater than 0, specifies the
317 desired extent of a font glyph width in pixels. If 0, sets the
318 default ( designed ) width corresponding to the font size or
319 height.
320 style
322 A combination of "fs::" ( font style ) constants. The constants
323 fs::Normal
325 fs::Bold
326 fs::Thin
327 fs::Italic
328 fs::Underlined
329 fs::StruckOut
330 fs::Outline
331 can be OR-ed together to express the font style. fs::Normal equals
333 to 0 and usually never used. If some styles are not supported by a
334 system-dependent font subsystem, they are ignored.
335 pitch
337 One of three constants:
338 fp::Default
340 fp::Fixed
341 fp::Variable
342 "fp::Default" specifies no interest about font pitch selection.
344 "fp::Fixed" is set when a monospaced (all glyphs are of same width)
345 font is desired. "fp::Variable" pitch specifies a font with
346 different glyph widths. This key is of the highest priority; all
347 other keys may be altered for the consistency of the pitch key.
348 vector
350 One of three constants:
351 fv::Default
353 fv::Bitmap
354 fv::Outline
355 "fv::Default" specifies no interest about font type selection,
357 "fv::Bitmap" sets priority for the bitmap fonts, "fv::Outline" for
358 the vector fonts.
359 Additionally, font entries returned from "fonts" method may set
361 "vector" to "fv::ScalableBitmap", to distinguish a bitmap font face
362 that comes with predefined bitmap sets from a scalable font.
363 direction
365 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
366 is pi, etc. If a font could not be rotated, it is usually
367 substituted with the one that can.
368 encoding
370 A string value, one of the strings returned by
371 "Prima::Application::font_encodings". Selects desired font
372 encoding; if empty, picks the first matched encoding, preferably
373 the locale set up by the user.
374 The encodings provided by different systems are different; in
376 addition, the only encodings are recognizable by the system, that
377 are represented by at least one font in the system.
378 Unix systems and the toolkit PostScript interface usually provide
380 the following encodings:
381 iso8859-1
383 iso8859-2
384 ... other iso8859 ...
385 fontspecific
386 Win32 returns the literal strings like
388 Western
390 Baltic
391 Cyrillic
392 Hebrew
393 Symbol
394 A hash that "::font" returns, is a tied hash, whose keys are also
396 available as separate properties. For example,
397 $x = $d-> font-> {style};
399 is equivalent to
401 $x = $d-> font-> style;
403 While the latter gives nothing but the arguable coding convenience, its
405 usage in set-call is much more usable:
406 $d-> font-> style( fs::Bold);
408 instead of
410 my %temp = %{$d-> font};
412 $temp{ style} = fs::Bold;
413 $d-> font( \%temp);
414 The properties of a font tied hash are also accessible through set()
416 call, like in Prima::Object:
417 $d-> font-> style( fs::Bold);
419 $d-> font-> width( 10);
420 is an equivalent to
422 $d-> font-> set(
424 style => fs::Bold,
425 width => 10,
426 );
427 When get-called, "::font" property returns a hash where more entries
429 than the described above can be found. These keys are read-only, their
430 values are ignored if passed to "::font" in a set-call.
431 In order to query the full list of fonts available to a graphic device,
433 the "::fonts" method is used. This method is not present in
434 Prima::Drawable namespace; it can be found in two built-in class
435 instances, "Prima::Application" and "Prima::Printer".
436 "Prima::Application::fonts" returns metrics for the fonts available to
438 the screen device, while "Prima::Printer::fonts" ( or its substitute
439 Prima::PS::Printer ) returns fonts for the printing device. The result
440 of this method is an array of font metrics, fully analogous to these
441 returned by "Prima::Drawable::font" method.
442 family
444 A string with font family name. The family is a secondary string
445 key, used for distinguishing between fonts with same name but of
446 different vendors ( for example, Adobe Courier and Microsoft
447 Courier).
448 ascent
450 Number of pixels between a glyph baseline and descent line.
451 descent
453 Number of pixels between a glyph baseline and descent line.
454 internalLeading
456 Number of pixels between ascent and internal leading lines.
457 Negative if the ascent line is below the internal leading line.
458 externalLeading
460 Number of pixels between ascent and external leading lines.
461 Negative if the ascent line is above the external leading line.
462 ------------- external leading line
464 $ ------------- ascent line
466 $ $
467 ------------- internal leading line
468 $
469 $$$
470 $ $
471 $ $ $
472 $$$$$$$ $$$
473 $ $ $ $
474 $ $ $ $
475 $ $ $$$ ---- baseline
476 $
477 $
478 $
479 $$$$ ---- descent line
480 weight
482 Font designed weight. Can be one of
483 fw::UltraLight
485 fw::ExtraLight
486 fw::Light
487 fw::SemiLight
488 fw::Medium
489 fw::SemiBold
490 fw::Bold
491 fw::ExtraBold
492 fw::UltraBold
493 constants.
495 maximalWidth
497 Maximal extent of a glyph in pixels. Equals to width in monospaced
498 fonts.
499 xDeviceRes
501 Designed horizontal font resolution in dpi.
502 yDeviceRes
504 Designed vertical font resolution in dpi.
505 firstChar
507 Index of the first glyph present in a font.
508 lastChar
510 Index of the last glyph present in a font.
511 breakChar
513 Index of the default character used to divide words. In a typical
514 western language font it is 32, ASCII space character.
515 defaultChar
517 Index of a glyph that is drawn instead of nonexistent glyph if its
518 index is passed to the text drawing routines.
519 Font ABC metrics
521 Besides these characteristics, every font glyph has an ABC-metric, the
522 three integer values that describe horizontal extents of a glyph's
523 black part relative to the glyph extent:
524 . . . . . . . .
526 . . $$$. . . . .
527 . . $$. $ . . . .
528 . . $$. . . . $$ . .
529 . $$$$$$$$$$. . .$$$$$ . .
530 . . $$ . . . $ $$ . .
531 . . $$ . . . .$$$$$ . .
532 . . $$ . . . . $$ . .
533 . .$$ . . . . $$$ $$$. .
534 $$ .$$ . . . $ $$ .
535 .$$$ . . . .$$$$$$$$. .
536 . . . . . . . .
537 <A>. .<C> <A>. .<C>
538 .<-.--B--.->. . .<--B--->. .
539 A = -3 A = 3
541 B = 13 B = 10
542 C = -3 C = 3
543 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
545 in picture on the left. A and C values are positive, if a glyph
546 contains empty space in front or behind the neighbor glyphs, like in
547 picture on the right. As can be seen, B is the width of a glyph's
548 black part.
549 ABC metrics returned by the get_font_abc() method.
551 The corresponding vertical metrics, called in Prima "DEF" metrics, are
553 returned by the get_font_def() method.
554 Raster operations
556 A drawable has two raster operation properties: "::rop" and "::rop2".
557 These define how the graphic primitives are plotted. "::rop" deals with
558 the foreground color drawing, and "::rop2" with the background.
559 Universal ROPs
561 The toolkit defines the following operations:
563 rop::Blackness # = 0
565 rop::NotOr # = !(src | dest)
566 rop::NotSrcAnd # &= !src
567 rop::NotPut # = !src
568 rop::NotDestAnd # = !dest & src
569 rop::Invert # = !dest
570 rop::XorPut # ^= src
571 rop::NotAnd # = !(src & dest)
572 rop::AndPut # &= src
573 rop::NotXor # = !(src ^ dest)
574 rop::NotSrcXor # alias for rop::NotXor
575 rop::NotDestXor # alias for rop::NotXor
576 rop::NoOper # = dest
577 rop::NotSrcOr # |= !src
578 rop::CopyPut # = src
579 rop::NotDestOr # = !dest | src
580 rop::OrPut # |= src
581 rop::Whiteness # = 1
582 Usually, however, graphic devices support only a small part of the
584 above set, limiting "::rop" to the most important operations: Copy,
585 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
586 only Copy and NoOp.
587 The raster operations apply to all graphic primitives except SetPixel.
589 Note for layering: using layered images and device bitmaps with
591 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
592 "rop::Blend" raster operations on OS-provided surfaces. See more on
593 "rop::Blend" below.
594 Also, "rop::AlphaCopy" operation is available for accessing alpha bits
596 only. When used, the source image is treated as alpha mask, and
597 therefore it has to be grayscale. It can be used to apply the alpha
598 bits independently, without need to construct an Icon object.
599 rop::Blend
601 "rop::Blend" is same as "rop::SrcCopy" except the source pixels are
603 assumed to be already premultiplied with the source alpha. This is the
604 default ROP when drawing with 8-bit icon masks or on layered surfaces,
605 and it reflects the expectation of the OS that images come
606 premultiplied.
607 This is the only blending operator supported on the widgets and
609 bitmaps, and it is advised to premultiply image pixels prior to drawing
610 images using it with calls to "Image.premultiply_alpha". Image drawing
611 supports this operator in case these premultiplied images are to be
612 used not only on native surfaces but also on Prima images.
613 Additional ROPs
615 Prima implements extra features for compositing on images outside the
617 begin_paint/end_paint brackets. It supports the following 12+1 Porter-
618 Duff operators and some selected Photoshop blend operators:
619 rop::Blend
621 rop::Clear rop::Add
622 rop::Xor rop::Multiply
623 rop::SrcOver rop::Screen
624 rop::DstOver rop::Overlay
625 rop::SrcCopy rop::Darken
626 rop::DstCopy rop::Lighten
627 rop::SrcIn rop::ColorDodge
628 rop::DstIn rop::ColorBurn
629 rop::SrcOut rop::HardLight
630 rop::DstOut rop::SoftLight
631 rop::SrcAtop rop::Difference
632 rop::DstAtop rop::Exclusion
633 Transparency control
635 There is defined a set of constants to apply a constant source and
636 destination alpha to when there is no alpha channel available:
637 rop::SrcAlpha
639 rop::SrcAlphaShift
640 rop::DstAlpha
641 rop::DstAlphaShift
642 Combine the rop constant using this formula:
644 $rop = rop::XXX |
646 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
647 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
648 or by calling "rop::alpha($rop, [ $src_alpha, [ $dst_alpha ]])"
650 that does the same.
651 Also, the function rop::blend($alpha) creates a rop constant for
653 simple blending of two images by the following formula:
654 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
656 "rop::alpha" also can be used for drawing on images outside
658 begin_paint/end_paint with all Porter-Duff and Photoshop raster
659 operators:
660 $image->rop( rop::alpha( rop::SrcOver, 128 ));
662 $image->ellipse( 5, 5, 5, 5 );
663 Note that when the raster operation is set to "rop::SrcOver", the
665 fully identical effect can be achieved by
666 $image->alpha(128);
668 $image->ellipse( 5, 5, 5, 5 );
669 as well.
671 When used with icons, their source and/or destination alpha
673 channels are additionally multiplied with these values.
674 rop::ConstantColor
676 This bit is used when the alpha is defined but the main bits
677 aren't. In this case, the main bits are filled from the
678 destination's image color, and the source image treated as the
679 source alpha channel. The following code applies a solid green
680 shade with a mask loaded from file.
681 $src->load('8-bit gray mask.png');
683 $dst->color(cl::LightGreen);
684 $dst->put_image( 0,0,$src,rop::SrcOver | rop::ConstantColor);
685 Coordinates
687 The Prima toolkit employs the XY grid, where X ascends rightwards and Y
688 ascends upwards. There, the (0,0) location is the bottom-left pixel of
689 a canvas.
690 All graphic primitives use inclusive-inclusive boundaries. For
692 example,
693 $d-> bar( 0, 0, 1, 1);
695 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
697 The coordinate origin can be shifted using "::matrix" property, that
699 translates the (0,0) point to the given offset. Calls to "::matrix",
700 "::clipRect" and "::region" always use the 'physical' (0,0) point,
701 whereas the plotting methods use the transformation result, the
702 'logical' (0,0) point.
703 As noted before, these three properties cannot be used in when an
705 object is in the disabled state.
706 Matrix
708 At the very bottom "Prima::Drawable" accepts matrix scalars in form of
710 6-item arrays, that constitute the following 2-D transformation matrix
711 A B DX
713 C D DY
714 0 0 1
715 where the coordinate transformation follows this formula:
717 x' = A x + B x + DX
719 y' = C y + D y + DY
720 . There are two accessors, "get_matrix" and "set_matrix" that return a
722 copy, or copy a new matrix, correspondintly, from and to the drawable
723 object.
724 The 6-item array that "get_matrix" returns is also a blessed object or
726 type "Prima::matrix" ( see "Prima::matrix" in Prima::types ) that is a
727 separate copy of the object matrix. "Prima::matrix" objects feature a
728 set of oprations such as "rotate" and "translate" that transform the
729 matrix further. In order to apply this matrix, one calls
730 "$drawable->set_matrix($matrix)" or "$matrix->apply($drawable)".
731 There is also a property "matrix", that is not really orthogonal to the
733 "get_matrix"/ "set_matrix" method pair, as "matrix" returns a
734 "Prima::Matrix" object, that, contrary to a "Prima::matrix" object
735 return by "get_matrix", is a direct accessor to the drawable's matrix:
736 my $m = $self->get_matrix;
738 $m->translate(1,2);
739 $self->set_matrix($m); # or $self->matrix($m);
740 is the same as
742 $self->matrix->translate(1,2);
744 and does not need an explicit call to "set_matrix" or "apply".
746 This class has all the methods the "Prima::matrix" has. See more in
748 "Prima::Matrix" in Prima::types.
749 Custom line end styles
751 Prima uses its own plotting mechanism in Prima::Drawable::Path to
752 produce all primitive shapes, including lines. The way lines are
753 plotted is governed by properties "lineEnd", "lineJoin", "linePattern",
754 and "miterLimit". All of these properties are described below, however
755 "lineEnd" provides rich capabilities to generate custom line ends, and
756 this is what described in this section.
757 le:: namespace
759 There are 3 predefined "le::" integer constants
760 le::Flat
762 le::Square
763 le::Round
764 that are hardcoded in Prima, that are accepted by the "lineEnd"
766 property. These constants are somewhat limited in the way one can
767 operate them, for the sake of efficiency.
768 It is also possible to supply an array descriptor that defines a
770 set of primitives that plots a line cap, automatically transformed
771 with respect to the current line tangent and width. Details of the
772 descriptor syntax itself are given in the next section, while here
773 the set of non-hardcoded line end functions is listed, that is also
774 suitable for use in the "lineEnd" property.
775 le::Arrow
777 le::Cusp
778 le::InvCusp
779 le::Knob
780 le::Rect
781 le::RoundRect
782 le::Spearhead
783 le::Tail
784 These descriptors could be arbitrarily transformed (f ex scaled):
786 # all three lines produce the same effect
788 $x->lineEnd( le::scale( Arrow => 1.5 ) );
789 $x->lineEnd( le::transform( le::Arrow, [1.5,0,0,1.5,0,0] ) );
790 $x->lineEnd( le::transform( le::Arrow, Prima::matrix->new->scale(1.5) ) );
791 lineEnd accessors
793 The "lineEnd" property can accept up to 4 line end definitions,
794 depending on syntax. When Prima plots lines, depending on the
795 location of a line end, one of these 4 definitions is selected.
796 Each definition also has its own property - see "lineHead",
797 "lineTail", "arrowHead", and "arrowTail", or a index-based accessor
798 "lineEndIndex":
799 [ lineHeads and lineTails ]
801 \____ ____ ___ __ ____ ___\
802 / /
803 arrowTail arrowHead
804 Line end syntax
806 The syntax for custom line end style is:
807 syntax ::= array of pairs
809 pair ::= command, array of points
810 command ::= line or conic or cubic
811 points ::= set of x,y coordinate pairs (vertices)
812 and individual commands accept arbitrary number of vertices, but no
814 less than 1 for "line", 2 for "conic", and 3 for "cubic".
815 The commands are executed sequentially on a coordinate grid where
817 line width is assumed to be 1, the plotting starts from point at
818 (1,0), and ends at (-1,0).
819 For example, this is the definition of "le::Arrow":
821 [
823 conic => [1,0,2.5,0,2.5,-0.5],
824 line => [0,2.5],
825 conic => [-2.5,-0.5,-2.5,0,-1,0]
826 ]
827
829 Graphic context properties
830 alpha INTEGER
831 Sets alpha component of the brush, where 0 is fully transparent and
832 255 is fully opaque.
833 Note that premultiplication of "color" and "backColor" is not
835 necessary as it is done internally.
836 Default: 255
838 antialias BOOLEAN
840 Turns on and off antialiased drawing on all primitives, excluding
841 image, "pixel", and "bar_alpha" calls.
842 It will not be possible to turn the property on if the system does
844 not support it. Also, monochrome images won't support it as well.
845 See "Antialiasing and alpha".
847 arrowHead
849 Defines the style to paint line heads on starting or ending points
850 used to define a line or polygon. Is never used on closed shapes.
851 If "undef", the heads are painted with the same style as "lineHead"
852 Default value: "le::Round". Cannot be "undef".
854 arrowTail
856 Defines the style to paint line tails on starting or ending points
857 used to define a line or polygon. Is never used on closed shapes.
858 If "undef", the heads are painted with the same style as
859 "lineTail"; if it is also "undef", then the style of "lineHead" is
860 used.
861 Default value: "undef"
863 backColor COLOR
865 Sets background color to the graphic context. All drawing routines
866 that use non-solid or transparent fill or line patterns use this
867 property value.
868 color COLOR
870 Sets foreground color to the graphic context. All drawing routines
871 use this property value.
872 clipRect X1, Y1, X2, Y2
874 Selects the clipping rectangle corresponding to the physical canvas
875 origin. On get-call, returns the extent of the clipping area, if
876 it is not rectangular, or the clipping rectangle otherwise. The
877 code
878 $d-> clipRect( 1, 1, 2, 2);
880 $d-> bar( 0, 0, 1, 1);
881 thus affects only one pixel at (1,1).
883 Set-call discards the previous "::region" value.
885 Note: "::clipRect" can not be used while the object is in the
887 paint-disabled state, its context is neither recorded nor used as a
888 template ( see "Graphic context and canvas") -- except on images.
889 fillMode INTEGER
891 Affects filling style of complex polygonal shapes filled by
892 "fillpoly". If "fm::Winding", the filled shape contains no holes;
893 if "fm::Alternate", holes are present where the shape edges cross.
894 "fm::Overlay" flag can be combined with these to counter an
896 intrinsic defect of filled shaped both in Win32 and X11 that don't
897 exactly follow polygon vertices. When supplied, it overlays a
898 polygon over the filled shape, so that the latter falls exactly in
899 the boundaries defined by vertices. This is desirable when one
900 wants the shape to be defined exactly by polygon vertices, but is
901 not desirable when a shape has holes in it and is connected in a
902 way that the polygon overlay may leave visible connection edges
903 over them.
904 Default value: "fm::Winding|fm::Overlay"
906 fillPattern ( [ @PATTERN ] ) or ( fp::XXX ) or IMAGE
908 Selects 8x8 fill pattern that affects primitives that plot filled
909 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
910 fill_sector(), floodfill().
911 Accepts either a "fp::" constant or a reference to an array of 8
913 integers, or an image reference. In all cases, except where the
914 image is colored, treats 0s in the pattern as the currently
915 selected "backColor", and 1s as "color". When "rop2" is set to
916 "rop::NoOper", treats 0s as fully transparent pixels.
917 Additionally, in the render mode respects the "alpha" property.
918 Note: Drawing over monochome bitmap or image will not respect its
920 "rop" on Win32.
921 Depending on the parameters, treats the input as follows:
923 fp:: constant
925 There are some predefined patterns, that can be referred via
926 "fp::" constants:
927 fp::Empty
929 fp::Solid
930 fp::Line
931 fp::LtSlash
932 fp::Slash
933 fp::BkSlash
934 fp::LtBkSlash
935 fp::Hatch
936 fp::XHatch
937 fp::Interleave
938 fp::WideDot
939 fp::CloseDot
940 fp::SimpleDots
941 fp::Borland
942 fp::Parquet
943 ( the actual patterns are hardcoded in primguts.c ) The default
945 pattern is fp::Solid.
946 On a get-call, does not return the "fp::" value but the
948 corresponding array (see below). If a constant value is needed
949 to be recovered, use "fp::builtin" function that would return
950 the constant from the array. There is also two shortcut
951 functions, "fp::is_solid" and "fp::is_empty" that check if the
952 fill pattern is all-ones or all-zeros, correspondingly.
953 Array
955 Wants an 8-item array where each item is a byte value,
956 representing 8 bits of each line in a pattern. The first
957 integer is the topmost pattern line, and the bit 0x80 is the
958 leftmost pixel in the line.
959 An example below shows encoding of fp::Parquet pattern:
961 # 76543210
963 84218421 Hex
964 0 $ $ $ 51
966 1 $ $ 22
967 2 $ $ $ 15
968 3 $ $ 88
969 4 $ $ $ 45
970 5 $ $ 22
971 6 $ $ $ 54
972 7 $ $ 88
973 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
975 Monochrome image
977 Like the array above, wants an image consisting of 0s and 1s
978 where these would represent canvas' "backColor" and "color",
979 correspondinly, when rendered. In the same fashion, when "rop2"
980 is set to "rop::NoOper", zeros will be treated as transparent
981 pixels.
982 Color image
984 Ignores color, and backColor, and rop2. Just uses the tiles
985 and the current "alpha" value.
986 Icon
988 Ignores color, backColor, and rop2. Uses the alpha pixel values
989 from the icon's mask and the current "alpha" value.
990 fillPatternOffset X, Y
992 Origin coordinates for the "fillPattern". Image patterns origin
993 (0,0) is system-dependent.
994 font \%FONT
996 Manages font context. FONT hash acceptable values are "name",
997 "height", "size", "width", "style" and "pitch".
998 Synopsis:
1000 $d-> font-> size( 10);
1002 $d-> font-> name( 'Courier');
1003 $d-> font-> set(
1004 style => $x-> font-> style | fs::Bold,
1005 width => 22
1006 );
1007 See "Fonts" for the detailed descriptions.
1009 Applies to text_out(), get_text_width(), get_text_box(),
1011 get_font_abc(), get_font_def(), render_glyph().
1012 font_mapper
1014 Returns a font mapper object that provides interface to fonts
1015 collection used for substitution in polyfont shaping (see
1016 "text_shape"). The fonts can be accessed there either by their font
1017 hash (name and style only, currently), or the font's corresponding
1018 index.
1019 There are two font lists used in the substitution mechanism,
1021 passive and active. The passive font list is initiated during the
1022 toolkit start and is never changed. Each font there is addressed by
1023 an index. When the actual search for a glyph is initiated, these
1024 fonts are queried in the loop and are checked if they contain the
1025 required glyphs. These queries are also cached, so that next time
1026 lookups run much quicker. That way, an "active" font list is built,
1027 and next substitutions use it before trying to look into the
1028 passive list. Since the ordering of fonts is system based, and is
1029 rather random, some fonts may not be a good or aesthetic
1030 substitution. Therefore the mapper can assist in adding or
1031 removing particular fonts to the active list, potentially allowing
1032 an application to store and load user-driven selection of
1033 substitution fonts.
1034 The following methods are available on the font mapper object:
1036 activate %FONT
1038 Adds the FONT into the active substitution list if the font is
1039 not disabled
1040 get INDEX
1042 Returns the font hash registered under INDEX
1043 count
1045 Returns number of all fonts in the collection
1046 index
1048 Returns what index is assigned to the currently used font, if
1049 any
1050 passivate %FONT
1052 Remove the font from the active substitution list
1053 is_active %FONT
1055 Returns whether the font is in the active substitution list or
1056 not
1057 enable %FONT
1059 Enables the font entry, the font will be considered for the
1060 polyfont lookup
1061 disable %FONT
1063 Disables the font entry, the font will not be considered for
1064 the polyfont lookup
1065 is_enabled %FONT
1067 Returns whether the font is enabled or not
1068 lineHead
1070 Defines the style to paint line heads in patterned lines only, on
1071 line segments that do not lie on line starting or ending points
1072 used to define a line or polygon.
1073 Default value: "undef"
1075 lineEnd VALUE
1077 Selects a line ending cap for plotting primitives. VALUE can be one
1078 of
1079 le::Arrow
1081 le::Cusp
1082 le::InvCusp
1083 le::Flat
1084 le::Knob
1085 le::Rect
1086 le::RoundRect
1087 le::Spearhead
1088 le::Square
1089 le::Round
1090 le::Tail
1091 constants, "undef", a custom line end description, or an array of
1093 four where each entry is one of the values above.
1094 The "undef" value is only accepted in the array syntax, and not for
1096 the index 0 ("lineHead"). The other indexes behave differently if
1097 are set to "undef" - see more in "lineTail", "arrowHead",
1098 "arrowTail", "lineEndIndex".
1099 "le::Round" is the default value.
1101 See also: "Custom line end styles".
1103 lineEndIndex INDEX, VALUE
1105 Same as "lineEnd" except only addresses a single line ending style.
1106 Allows VALUE to be "undef" for indexes greater than 0; depending on
1108 the index, the line style will be different ( see more in
1109 "lineTail", "arrowHead", "arrowTail" ).
1110 Allows special INDEX values or'ed with "le::Only", that behave
1112 differently if the line end style is "undef": while normal INDEX
1113 queries may return "undef", or possibly affect neighbor indexing
1114 (if these are, in turn, "undef"s), the calls with the "le::Only"
1115 bit set never return "undef" on get-calls, and never affect
1116 neighbor styles on set-calls.
1117 The following lookup rules are used if a line end style is undef:
1119 lei::LineTail - can never be undef
1121 lei::LineHead - if undef, same as lei::LineTail
1122 lei::ArrowTail - if undef, same as lei::LineTail
1123 lei::ArrowHead - if undef, same as lei::LineHead, and if it also is undef, then same as lei::LineTail
1124 lineJoin VALUE
1126 Selects a line joining style for polygons. VALUE can be one of
1127 lj::Round
1129 lj::Bevel
1130 lj::Miter
1131 constants. lj::Round is the default value.
1133 linePattern PATTERN
1135 Selects a line pattern for plotting primitives. PATTERN is either
1136 a predefined "lp::" constant, or a string where each even byte is a
1137 length of a dash, and each odd byte is a length of a gap.
1138 The predefined constants are:
1140 lp::Null # "" /* */
1142 lp::Solid # "\1" /* ___________ */
1143 lp::Dash # "\x9\3" /* __ __ __ __ */
1144 lp::LongDash # "\x16\6" /* _____ _____ */
1145 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
1146 lp::Dot # "\1\3" /* . . . . . . */
1147 lp::DotDot # "\1\1" /* ............ */
1148 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
1149 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
1150 Not all systems are capable of accepting user-defined line
1152 patterns, and in such situation the "lp::" constants are mapped to
1153 the system-defined patterns. In Win9x, for example, lp::DashDotDot
1154 is much different from its string definition.
1155 Default value is lp::Solid.
1157 lineTail
1159 Defines the style to paint line tails in patterned lines only, on
1160 line segments that do not lie on line starting or ending points
1161 used to define a line or polygon. If "undef", line tails are
1162 painted with the same style as "lineHead".
1163 Default value: "undef"
1165 lineWidth WIDTH
1167 Selects a line width for plotting primitives. If a VALUE is 0,
1168 then a cosmetic pen is used - the thinnest possible line that a
1169 device can plot. If a VALUE is greater than 0, then a geometric pen
1170 is used - the line width is set in device units. There is a subtle
1171 difference between VALUE 0 and 1 in a way the lines are joined.
1172 Default value is 0.
1174 matrix [A,B,C,D,X,Y] | Prima::Matrix
1176 Sets current matrix transformation that is used in all plotting
1177 operations except "clipRect" and "region". Returns a "Matrix" in
1178 Prima object.
1179 Default value is (1,0,0,1,0,0) or "Prima::matrix::identity".
1181 See also: "Prima::matrix" in Prima::types and
1183 "Prima::types/Prima::Matrix".
1184 miterLimit VALUE
1186 When path segments connect at a sharp angle, a miter join results
1187 in a spike that extends well beyond the connection point. The
1188 purpose of the miter limit is to cut off such spikes when they
1189 become objectionably long. At any given corner, the miter length is
1190 the distance from the point at which the inner edges of the stroke
1191 intersect to the point at which the outside edges of the strokes
1192 intersect-in other words, the diagonal length of the miter. This
1193 distance increases as the angle between the segments decreases. If
1194 the ratio of the miter length to the line width exceeds the miter
1195 limit parameter, stroke treats the corner with a bevel join instead
1196 of a miter join. The ratio of miter length to line width is
1197 directly related to the angle j between the segments by the
1198 formula:
1199 r = 1/sin(j/2)
1201 Default value is 10.0.
1203 Assuming line join is "lj::Miter" and line angle is 30 degrees:
1205 miter limit = 1.0: \__/
1207 miter limit = 9.0: \ /
1209 \/
1210 Note: does not work under X11.
1212 palette [ @PALETTE ]
1214 Selects solid colors in a system palette, as many as possible.
1215 PALETTE is an array of integer triplets, where each is R, G and B
1216 component. The call
1217 $d-> palette([128, 240, 240]);
1219 selects a gray-cyan color, for example.
1221 The return value from get-call is the content of the previous set-
1223 call, not the actual colors that were copied to the system palette.
1224 region OBJECT
1226 Selects a clipping region applied to all drawing and painting
1227 routines. On setting, the OBJECT is either undef, then the clip
1228 region is erased ( no clip ), or a Prima::Image object with a bit
1229 depth of 1. The bit mask of OBJECT is applied to the system
1230 clipping region. Or, it is a Prima::Region object. If the OBJECT
1231 is smaller than the drawable, its exterior is assigned to clipped
1232 area as well. Discards the previous "::clipRect" value; successive
1233 get-calls to "::clipRect" return the boundaries of the region.
1234 On getting, OBJECT is either undef or Prima::Region object.
1236 Note: "::region" can not be used while the object is in the paint-
1238 disabled state, its context is neither recorded nor used as a
1239 template ( see "Graphic context and canvas").
1240 resolution X, Y
1242 A read-only property. Returns horizontal and vertical device
1243 resolution in dpi.
1244 rop OPERATION
1246 Selects raster operation that applies to foreground color plotting
1247 routines.
1248 See also: "::rop2", "Raster operations".
1250 rop2 OPERATION
1252 Selects raster operation that applies to background color plotting
1253 routines.
1254 See also: "::rop", "Raster operations".
1256 textOpaque FLAG
1258 If FLAG is 1, then text_out() fills the text background area with
1259 "::backColor" property value before drawing the text. Default value
1260 is 0, when text_out() plots text only.
1261 See get_text_box().
1263 textOutBaseline FLAG
1265 If FLAG is 1, then text_out() plots text on a given Y coordinate
1266 correspondent to font baseline. If FLAG is 0, a Y coordinate is
1267 mapped to font descent line. Default is 0.
1268 translate X_OFFSET, Y_OFFSET
1270 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
1271 affect "::clipRect" and "::region". Not cumulative, so the call
1272 sequence
1273 $d-> translate( 5, 5);
1275 $d-> translate( 15, 15);
1276 is equivalent to
1278 $d-> translate( 15, 15);
1280 Note: "::translate" can not be used while the object is in the
1282 paint-disabled state, its context is neither recorded nor used as a
1283 template ( see "Graphic context and canvas").
1284 Other properties
1286 height HEIGHT
1287 Selects the height of a canvas.
1288 size WIDTH, HEIGHT
1290 Selects the extent of a canvas.
1291 width WIDTH
1293 Selects the width of a canvas.
1294 Graphic primitives methods
1296 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1297 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
1298 from START_ANGLE to END_ANGLE.
1299 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1301 miterLimit, rop, rop2
1302 bar X1, Y1, X2, Y2
1304 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
1305 Context used: color, backColor, fillPattern, fillPatternOffset,
1307 rop, rop2
1308 bar_alpha ALPHA <X1, Y1, X2, Y2>
1310 Fills rectangle in the alpha channel, filled with ALPHA value
1311 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
1312 parameters, in this case fills all canvas area.
1313 Has only effect on layered surfaces.
1315 bars @RECTS
1317 Draws a set of filled rectangles. RECTS is an array of integer
1318 quartets in format (X1,Y1,X2,Y2).
1319 Context used: color, backColor, fillPattern, fillPatternOffset,
1321 rop, rop2
1322 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1324 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
1325 from START_ANGLE to END_ANGLE and connects its ends with the
1326 straight line.
1327 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1329 miterLimit, rop, rop2
1330 clear <X1, Y1, X2, Y2>
1332 Draws rectangle filled with pure background color within (X1,Y1) -
1333 (X2,Y2) extents. Can be called without parameters, in this case
1334 fills all canvas area.
1335 Context used: backColor, rop2
1337 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
1339 TAB_INDENT = 1 ]
1340 Draws several lines of text one under another with respect to align
1341 and break rules, specified in FLAGS and TAB_INDENT tab character
1342 expansion.
1343 "draw_text" is a convenience wrapper around "text_wrap" for drawing
1345 the wrapped text, and also provides the tilde ( ~ )- character
1346 underlining support.
1347 The FLAGS is a combination of the following constants:
1349 dt::Left - text is aligned to the left boundary
1351 dt::Right - text is aligned to the right boundary
1352 dt::Center - text is aligned horizontally in center
1353 dt::Top - text is aligned to the upper boundary
1354 dt::Bottom - text is aligned to the lower boundary
1355 dt::VCenter - text is aligned vertically in center
1356 dt::DrawMnemonic - tilde-escapement and underlining is used
1357 dt::DrawSingleChar - sets tw::BreakSingle option to
1358 Prima::Drawable::text_wrap call
1359 dt::NewLineBreak - sets tw::NewLineBreak option to
1360 Prima::Drawable::text_wrap call
1361 dt::SpaceBreak - sets tw::SpaceBreak option to
1362 Prima::Drawable::text_wrap call
1363 dt::WordBreak - sets tw::WordBreak option to
1364 Prima::Drawable::text_wrap call
1365 dt::ExpandTabs - performs tab character ( \t ) expansion
1366 dt::DrawPartial - draws the last line, if it is visible partially
1367 dt::UseExternalLeading - text lines positioned vertically with respect to
1368 the font external leading
1369 dt::UseClip - assign ::clipRect property to the boundary rectangle
1370 dt::QueryLinesDrawn - calculates and returns number of lines drawn
1371 ( contrary to dt::QueryHeight )
1372 dt::QueryHeight - if set, calculates and returns vertical extension
1373 of the lines drawn
1374 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
1375 dt::WordWrap - performs word wrapping by the width of the boundaries
1376 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
1377 dt::UseExternalLeading
1378 Context used: color, backColor, font, rop, textOpaque,
1380 textOutBaseline
1381 ellipse X, Y, DIAMETER_X, DIAMETER_Y
1383 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
1384 axes.
1385 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1387 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1389 Fills a chord outline with center in X, Y and DIAMETER_X and
1390 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see chord()).
1391 Context used: color, backColor, fillPattern, fillPatternOffset,
1393 rop, rop2
1394 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
1396 Fills an elliptical outline with center in X, Y and DIAMETER_X and
1397 DIAMETER_Y axes.
1398 Context used: color, backColor, fillPattern, fillPatternOffset,
1400 rop, rop2
1401 fillpoly \@POLYGON
1403 Fills a polygonal area defined by POLYGON set of points. POLYGON
1404 must present an array of integer pair in (X,Y) format. Example:
1405 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
1407 Context used: color, backColor, fillPattern, fillPatternOffset,
1409 rop, rop2, fillMode
1410 Returns success flag; if failed, $@ contains the error.
1412 See also: polyline().
1414 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1416 Fills a sector outline with center in X, Y and DIAMETER_X and
1417 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see sector()).
1418 Context used: color, backColor, fillPattern, fillPatternOffset,
1420 rop, rop2
1421 fill_spline \@VERTICES, %OPTIONS
1423 Fills a polygonal area defined by the curve, projected by applying
1424 B-spline curve based on set of VERTICES. VERTICES must present an
1425 array of integer pair in (X,Y) format. Example:
1426 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1428 Context used: color, backColor, fillPattern, fillPatternOffset,
1430 rop, rop2
1431 Returns success flag; if failed, $@ contains the error.
1433 See also: spline, render_spline
1435 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1437 Fills an area of the canvas using the current fill context. The
1438 area is assumed to be bounded as specified by the SINGLEBORDER
1439 parameter. SINGLEBORDER can be 0 or 1.
1440 SINGLEBORDER = 0: The fill area is bounded by the color specified
1442 by the COLOR parameter.
1443 SINGLEBORDER = 1: The fill area is defined by the color that is
1445 specified by COLOR. Filling continues outward in all directions as
1446 long as the color is encountered. This style is useful for filling
1447 areas with multicolored boundaries.
1448 Context used: color, backColor, fillPattern, fillPatternOffset,
1450 rop, rop2
1451 line X1, Y1, X2, Y2
1453 Plots the straight line from (X1,Y1) to (X2,Y2).
1454 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1456 lines \@LINES
1458 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1459 lines() plots the straight line per quartet.
1460 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1462 Returns success flag; if failed, $@ contains the error.
1464 new_aa_surface
1466 Returns a new antialiasing surface object for AA emulation. See
1467 Prima::Drawable::Antialias for usage and details.
1468 new_gradient
1470 Returns a new gradient object. See Prima::Drawable::Gradient for
1471 usage and details.
1472 new_path
1474 Returns a new path object. See Prima::Drawable::Path for usage and
1475 details.
1476 pixel X, Y, <COLOR>
1478 ::pixel is a property - on set-call it changes the pixel value at
1479 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1480 pixel value at (X,Y).
1481 No context is used. May return "cl::Invalid" to signal an error or
1483 the out-of-boundaries condition.
1484 polyline \@POLYGON
1486 Draws a polygonal area defined by the POLYGON set of points.
1487 POLYGON must contain an array of integer pairs in (X,Y) format.
1488 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1490 lineEnd, miterLimit, rop, rop2
1491 Returns success flag; if failed, $@ contains the error.
1493 See also: fillpoly().
1495 put_image X, Y, OBJECT, [ ROP ]
1497 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1498 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1499 specified, it is used. Otherwise, value of "::rop" property is
1500 used.
1501 Returns success flag; if failed, $@ contains the error.
1503 Context used: rop; color and backColor for a monochrome
1505 DeviceBitmap
1506 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1508 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1509 Draws the OBJECT's source rectangle into the destination rectangle,
1510 stretching or compressing the source bits to fit the dimensions of
1511 the destination rectangle, if necessary. The source rectangle
1512 starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide and
1513 SRC_HEIGHT pixels tall. The destination rectangle starts at (X,Y),
1514 and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT) pixels
1515 tall. If DEST_WIDTH or DEST_HEIGHT are negative, a mirroring by
1516 respective axis is performed.
1517 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1519 No context is used, except color and backColor for a monochrome
1521 DeviceBitmap
1522 Returns success flag; if failed, $@ contains the error.
1524 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1526 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1527 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1528 specified, paints an inferior rectangle with it, otherwise the
1529 inferior rectangle is not touched.
1530 Context used: rop; color and backColor for a monochrome
1532 DeviceBitmap
1533 rect_fill X1, Y1, X2, Y2, BORDER_WIDTH, FOREGROUND, BACKGROUND
1535 Draws a rectangle with outline color FOREGROUND and BORDER_WIDTH
1536 pixels, and fills it with color BACKGROUND. If FOREGROUND and/or
1537 BACKGROUND are undefined, currect colors are used. BORDER_WIDTH is
1538 1 pixel if omitted.
1539 Contrary to a call to rectangle() with line width greater than 1,
1541 never paints pixels outside the given rectange; border is painted
1542 inwards.
1543 Context used: rop, fillPattern
1545 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1547 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1548 line width.
1549 No context is used.
1551 rect_solid X1, Y1, X2, Y2, BORDER_WIDTH, FOREGROUND
1553 Draws a rectangle with outline color FOREGROUND and BORDER_WIDTH
1554 pixels. If FOREGROUND is undefined, currect color is used.
1555 BORDER_WIDTH is 1 pixel if omitted.
1556 Contrary to a call to rectangle() with line width greater than 1,
1558 never paints pixels outside the given rectange; border is painted
1559 inwards.
1560 Context used: rop
1562 rectangle X1, Y1, X2, Y2
1564 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1565 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1567 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1569 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1570 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1571 two straight lines.
1572 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1574 miterLimit, rop, rop2
1575 spline \@VERTICES, %OPTIONS
1577 Draws a B-spline curve defined by set of VERTICES control points.
1578 VERTICES must present an array of integer pair in (X,Y) format.
1579 The following options are supported:
1581 closed BOOL = undef
1583 When not set, checks if the first and the last vertices point
1584 to the same point, and if yes, assumes a closed shape. Note - a
1585 closed shape rendering is implemented by adding degree minus
1586 two points to the set; this is important if "weight" or "knots"
1587 are specified.
1588 degree INTEGER = 2
1590 The B-spline degree. Default is 2 (quadratic). Number of points
1591 supplied must be at least degree plus one.
1592 knots \@INTEGERS
1594 Array of integers, number of points plus degree plus one, which
1595 makes the result a Bezier curve. By default, if the shape is
1596 opened (i.e. first and last points are different), is set to
1597 represent a clamped array, so that the first and last points of
1598 the final curve match the first and the last control points. If
1599 the shape is closed, set to represent an unclamped array, so
1600 that no control points lie directly on the curve.
1601 precision INTEGER = 24
1603 Defines number of steps to split the curve into. The value is
1604 multiplied to the number of points and the result is used as
1605 number of steps.
1606 weight \@INTEGERS = [ 1, 1, 1, ... ]
1608 Array of integers, one for each point supplied. Assigning these
1609 can be used to convert B-spline into a NURBS. By default set of
1610 ones.
1611 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1613 miterLimit, rop, rop2
1614 See also: fill_spline, render_spline.
1616 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1618 Draws the OBJECT on the destination rectangle, stretching or
1619 compressing the source bits to fit the dimensions of the
1620 destination rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT
1621 are negative, a mirroring is performed. The destination rectangle
1622 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1623 pixels tall.
1624 If ROP raster operation is specified, it is used. Otherwise, value
1626 of "::rop" property is used.
1627 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1629 Returns success flag; if failed, $@ contains the error.
1631 Context used: rop
1633 text_out TEXT, X, Y
1635 Draws TEXT string at (X,Y). TEXT is either character string, or a
1636 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1637 "Prima::Drawable::Glyphs->glyphs" strings of glyphs.
1638 Returns success flag; if failed, $@ contains the error.
1640 Context used: color, backColor, font, rop, textOpaque,
1642 textOutBaseline
1643 text_shape TEXT, %OPTIONS
1645 Converts TEXT into set of glyphs, returns either a
1646 "Prima::Drawable::Glyphs" object, or a 0 integer when shaping is
1647 not necessary, or "undef" as an error.
1648 When Prima is compiled with "libfribidi", the method runs unicode
1650 bidirectional algorithm on TEXT that properly positions embedded
1651 directional text (f.ex. a latin quote inside an arabic text), see
1652 Unicode Standard Annex #9 for the details. Without the library
1653 only does minimal RTL alignment.
1654 Glyphs returned are positioned according to RTL directions given in
1656 TEXT using characters from unicode block "General Punctuation
1657 U+2000 .. U+206F". Additionally, character ligation may be
1658 performed so that one or more characters are represented by one or
1659 more glyphs. Such syntactic units, clusters, are adopted in Prima
1660 where appropriate, instead of character units, for selection,
1661 navigation etc in f.ex. "Prima::InputLine" and "Prima::Edit".
1662 Helper routines that translate clusters, glyphs, and characters
1663 into each other are found in Prima::Drawable::Glyphs.
1664 Options recognized:
1666 advances BOOLEAN = false
1668 Shaping process may or may not fill integer array of advances
1669 and positions for each glyphs, depending on the implementation.
1670 The advances are needed to represent f.ex. combining graphemes,
1671 when TEXT consisting of two characters, "A" and combining grave
1672 accent U+300 should be drawn as a single À cluster but are
1673 represented by two glyphs "A" and "`". The grave glyph has its
1674 own advance for standalone usage, but in this case it should be
1675 ignored, and that is achieved by filling advance table where
1676 the "A" advance is the normal glyph advance, whereas the
1677 advance of the "`" is zero. Also, the position table
1678 additionally shifts glyph position by X and Y coordinates, when
1679 that is needed (f.ex. it might be positioned differently by the
1680 vertical axis on "a" and "A").
1681 Setting this options to "true" will force fill advance and
1683 positioning tables. These tables can be manipulated later, and
1684 are respected by "text_out" and "get_text_width".
1685 language STRING = undef
1687 When set, shaping process can take in the account the language
1688 of the text. F.ex. text "ae" might be shaped as a single glyph
1689 æ for the Latin language, but never for the English.
1690 level INTEGER = ts::Full
1692 Selects the shaping (i.e. text to glyph conversion) level, how
1693 the system should treat the input text and how deep the shaping
1694 should go.
1695 One of the following "ts::XXX" options:
1697 ts::Bytes
1699 Treats input text as non-unicode locale-specific
1700 codepoints, characters higher than 255 are treated as
1701 chr(255). Reordering never happens, font substitution
1702 never happens, kerning and ligation never happens; returns
1703 glyph indexes in a 1:1 mapping for each codepoint.
1704 ts::None
1706 Performs quick null shaping without mapping to the font
1707 glyphs, but only running bidirectional algorithm on the
1708 text. On the return, "glyphs", as well as eventual
1709 "advances" and "positions", are filled with zeros, but
1710 "indexes" are filled with the proper character offsets,
1711 effectively making it a visual-to-logical map since the
1712 number of glyphs will always be equal to the number of
1713 characters in TEXT, because ligation never happens here
1714 (except when TEXT contains unicode directional characters
1715 such as isolates etc - those are removed from the output).
1716 By default, advances and positions are not filled, but if
1718 the "advances" option is set, fills them with zeros.
1719 ts::Glyphs
1721 Applies the unicode bidi algorithm and maps the result onto
1722 font glyphs. Ligation and kerning doesn't happen here,
1723 it's basically same as "ts::None" but with the glyph
1724 mapping part.
1725 By default, advances and positions are not filled, but if
1727 "advances" option is set, fills the advances array with
1728 character glyph advances and the positions array with
1729 zeros.
1730 May fill the "fonts" array if the "polyfont" option is set.
1732 ts::Full
1734 Applies the unicode bidi algorithm, and runs the full
1735 shaping on the result. Ligation and kerning may occur.
1736 Always fills the advances and positions array; the
1737 "advances" option is ignored.
1738 If the system or the selected font does not support
1740 shaping, tries to ligate known arabic shapes using the
1741 fribidi library, if available. Also in this case does not
1742 return the advances and positions by default, but if
1743 "advances" option is set, fills the advances array with
1744 character glyph advances and the positions array with
1745 zeros.
1746 May fill the "fonts" array if the "polyfont" option is set.
1748 pitch INTEGER
1750 When the "polyfont" is set (default) and thus font substitution
1751 is desired, filters only fonts that match "pitch", either
1752 "fp::Variable" or "fp::Fixed". By default will be set to
1753 "fp::Fixed" if the current for is monospaced, but to
1754 "fp::Default" matching all fonts, otherwise.
1755 polyfont BOOLEAN = true
1757 If set, scans if the currently selected font supports all
1758 unicode points, and if not, selects a substitutions from a pre-
1759 populated list, taking into account the font pitch (see "pitch"
1760 above). In cases where the current font has not enough glyphs
1761 to shape all the requested unicode points, font substitution is
1762 performed, and the result contains an extra array "fonts" (see
1763 "fonts" in Prima::Drawable::Glyphs). When the current font has
1764 all needed glyphs, the fonts array is not created.
1765 The font list access is available through "font_mapper".
1767 Valid only with shaping levels "ts::Glyphs" and "ts::Full".
1769 reorder BOOLEAN = true
1771 When set, unicode bidi algorithm is used to reorder codepoints,
1772 and additionally RTL codepoints may be reversed (depending on
1773 direction context).
1774 When unset, no such reordering occurs, to emulate as much as
1776 possible a behavior that each text grapheme is being mapped to
1777 a glyph cluster exactly as it occurs in the input text, from
1778 left to right. Note that bidi reordering still may occur
1779 internally, since system shapers may reverse placement of RTL
1780 characters, so that the Prima reordering is needed to cancel
1781 this. In theory the caller shouldn't see the difference as
1782 these should cancel each other, but if Prima miscalculates the
1783 expected way the system shaper does the bidi processing, it
1784 might.
1785 A similar effect can be reached by prepending the text with
1787 U+202D (LEFT-TO-RIGHT OVERRIDE).
1788 replace_tabs INTEGER = -1
1790 If set to 0 or more, replaces tabs by spaces width widths
1791 multiplied by the option value. Since it needs advances to
1792 operate, automatically sets the "advances" option. If the
1793 string passed indeed contains tab characters, also turns off
1794 "skip_if_simple" option.
1795 Note: if using the result later in "text_wrap", set the
1797 "tabIndent" parameters there to 1 to avoid double
1798 multipliciaton of the tab character width.
1799 rtl BOOLEAN
1801 If set to 1, default text direction is assumed as RTL, and as
1802 LTR if set to 0. If unset, the text direction is taken from
1803 "textDirection" in Prima::Application.
1804 skip_if_simple BOOLEAN = false
1806 When set, checks whether the shaping result is identical to the
1807 input, in a sense that a call to text_out(TEXT) and a call to
1808 text_shape_out(TEXT) produce identical results. Majority of
1809 english text will fall into that category, and when that indeed
1810 happens, returns integer value 0 instead of a glyph object.
1811 See also "text_shape_out", "get_text_shape_width",
1813 "text_wrap_shape".
1814 text_shape_out TEXT, X, Y[, RTL]
1816 Runs shaping on TEXT character string with the RTL flag (or
1817 "$::application->textDirection". Draws the resulting glyph string
1818 at (X,Y).
1819 Returns success flag; if failed, $@ contains the error.
1821 Context used: color, backColor, font, rop, textOpaque,
1823 textOutBaseline
1824 Methods
1826 begin_paint
1827 Enters the enabled ( active paint ) state, returns success flag; if
1828 failed, $@ contains the error. Once the object is in enabled
1829 state, painting and drawing methods can perform write operations on
1830 a canvas.
1831 See also: "end_paint", "begin_paint_info", "Graphic context and
1833 canvas"
1834 begin_paint_info
1836 Enters the information state, returns success flag; if failed, $@
1837 contains the error. The object information state is same as
1838 enabled state ( see "begin_paint"), except painting and drawing
1839 methods do not change the object canvas.
1840 See also: "end_paint_info", "begin_paint", "Graphic context and
1842 canvas"
1843 can_draw_alpha
1845 Returns whether using alpha bits operation on the drawable will
1846 have any effect or not. Note that the drawable may not necessarily
1847 have an alpha channel, for example a normal RGB image is capable to
1848 be painted on with alpha while not having any alpha on its own. On
1849 unix, all non-1 bit drawables return true if Prima was compiled
1850 with XRender support and if that extension is present on the X
1851 server. On windows, all non-1 bit drawables return true
1852 unconditionally.
1853 See also: "has_alpha_layer"
1855 end_paint
1857 Exits the enabled state and returns the object to a disabled state.
1858 See also: "begin_paint", "Graphic context and canvas"
1860 end_paint_info
1862 Exits the information state and returns the object to a disabled
1863 state.
1864 See also: "begin_paint_info", "Graphic context and canvas"
1866 font_match \%SOURCE, \%DEST, PICK = 1
1868 Performs merging of two font hashes, SOURCE and DEST. Returns the
1869 merge result. If PICK is true, matches the result with a system
1870 font repository.
1871 Called implicitly by "::font" on set-call, allowing the following
1873 example to work:
1874 $d-> font-> set( size => 10);
1876 $d-> font-> set( style => fs::Bold);
1877 In the example, the hash 'style => fs::Bold' does not overwrite the
1879 previous font context ( 'size => 10' ) but gets added to it ( by
1880 font_match()), providing the resulting font with both font
1881 properties set.
1882 fonts <FAMILY = "", ENCODING = "">
1884 Member of "Prima::Application" and "Prima::Printer", does not
1885 present in "Prima::Drawable".
1886 Returns an array of font metric hashes for a given font FAMILY and
1888 ENCODING. Every hash has full set of elements described in
1889 "Fonts".
1890 If called without parameters, returns an array of same hashes where
1892 each hash represents a member of font family from every system font
1893 set. It this special case, each font hash contains additional
1894 "encodings" entry, which points to an array of encodings available
1895 for the font.
1896 If called with FAMILY parameter set but no ENCODING is set,
1898 enumerates all combinations of fonts with all available encodings.
1899 If called with FAMILY set to an empty string, but ENCODING
1901 specified, returns only fonts that can be displayed with the
1902 encoding.
1903 Example:
1905 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1907 get_bpp
1909 Returns device color depth. 1 is for black-and-white monochrome, 24
1910 for true color, etc.
1911 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1913 Returns ABC font metrics for the given range, starting at
1914 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1915 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1916 responsible of representation of characters in 127-255 range. If
1917 0, the default, encoding-dependent characters are assumed. If 1,
1918 the U007F-U00FF glyphs from Latin-1 set are used.
1919 The result is an integer array reference, where every character
1921 glyph is referred by three integers, each triplet containing A, B
1922 and C values.
1923 For detailed explanation of ABC meaning, see "Font ABC metrics";
1925 Context used: font
1927 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1929 Same as "get_font_abc", but for vertical metrics. Is expensive on
1930 bitmap fonts, because to find out the correct values Prima has to
1931 render glyphs on bitmaps and scan for black and white pixels.
1932 Vector fonts are not subject to this, and the call is as effective
1934 as "get_font_abc".
1935 get_font_languages
1937 Returns array of ISO 639 strings that can be displayed using glyphs
1938 available in the currently selected font.
1939 get_font_ranges
1941 Returns array of integer pairs denoting unicode indices of glyphs
1942 covered by the currently selected font. Each pair is the first and
1943 the last index of a contiguous range.
1944 Context used: font
1946 get_nearest_color COLOR
1948 Returns a nearest possible solid color in representation of the
1949 graphic device. Always returns same color if the device bit depth
1950 is equal or greater than 24.
1951 get_paint_state
1953 Returns paint state value on of ps:: constants - "ps::Disabled" if
1954 the object is in the disabled state, "ps::Enabled" for the enabled
1955 state, "ps::Information" for the information state.
1956 For brevity, mb::Disabled is equal to 0 so this allows for simple
1958 boolean testing whether one can get/set graphical properties on an
1959 object.
1960 See "Graphic context and canvas" for more.
1962 get_physical_palette
1964 Returns an array of integers in (R,G,B) format, where each color
1965 entry is in the 0 - 255 range.
1966 The physical palette array is non-empty only on paletted graphic
1968 devices, the true color devices return an empty array.
1969 The physical palette reflects the solid colors currently available
1971 to all programs in the system. The information is volatile if the
1972 system palette can change colors, since any other application may
1973 request to change the system colors at any moment.
1974 get_text_shape_width TEXT, [ FLAGS ]
1976 Runs shaping on TEXT character string with text direction either
1977 taken from "FLAGS & to::RTL" value, or from the or
1978 "$::application->textDirection". Returns the shaping result width
1979 as if it would be drawn using currently selected font.
1980 If "FLAGS & to::AddOverhangs" is set, the first character's
1982 absolute A value and the last character's absolute C value are
1983 added to the string if they are negative.
1984 get_text_width TEXT, ADD_OVERHANG = 0
1986 Returns TEXT string width if it would be drawn using currently
1987 selected font. TEXT is either a character string, or a
1988 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1989 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1990 If ADD_OVERHANG is 1, the first character's absolute A value and
1992 the last character's absolute C value are added to the string if
1993 they are negative.
1994 See more on ABC values at "Font ABC metrics".
1996 Context used: font
1998 get_text_box TEXT
2000 Returns TEXT string extensions if it would be drawn using currently
2001 selected font. TEXT is either a character string, or a
2002 "Prima::Drawable::Glyphs" object returned from "text_shape", or
2003 "Prima::Drawable::Glyphs-> glyphs" glyph string.
2004 The result is an anonymous array of 5 points ( 5 integer pairs in
2006 (X,Y) format). These 5 points are offsets for the following string
2007 extents, given the string is plotted at (0,0):
2008 1: start of string at ascent line ( top left )
2010 2: start of string at descent line ( bottom left )
2012 3: end of string at ascent line ( top right )
2014 4: end of string at descent line ( bottom right )
2016 5: concatenation point
2018 The concatenation point coordinates (XC,YC) are coordinated passed
2020 to consequent text_out() call so the conjoint string would plot as
2021 if it was a part of TEXT. Depending on the value of the
2022 "textOutBaseline" property, the concatenation point is located
2023 either on the baseline or on the descent line.
2024 Context used: font, textOutBaseline
2026 1 3 3 4
2028 ** ****
2029 * * *
2030 *** ***
2031 * * *
2032 **** **
2033 2 4 1 2
2034 graphic_context %GC, $CALLBACK
2036 A shortcut method that saves the graphic context, applies changes
2037 in %GC, calls $CALLBACK, and finally restores the context. F ex:
2038 $self->graphic_context( fillPattern => fp::Solid, sub { $self-> bar(..) } );
2040 graphic_context_pop
2042 Restores the graphic context properties from the stack.
2043 graphic_context_push
2045 Saves the graphic context properties on the stack.
2046 has_alpha_layer
2048 Returns true if the drawable has an alpha channel. If the drawable
2049 is treated as a source, it means its alpha content will be
2050 respected when drawing on another surface. If the drawable is
2051 treated as a destination, it means that its alpha content will be
2052 updated if drawing on it uses alpha bits.
2053 See also: "can_draw_alpha".
2055 render_glyph INDEX, %OPTIONS
2057 Returns glyph representation as an outline. The outline is an
2058 integer array, formed as a set of plotting commands. Each command
2059 is a "ggo::" constant, followed by number of points, followed by
2060 the 2D point coordinates in 1/64 pixels.
2061 Options recognized:
2063 glyph BOOL
2065 If set, INDEX is treated as the glyph index rather than
2066 character index. Default is false.
2067 hints BOOL
2069 Is set, hinting is enabled. Default is true.
2070 unicode BOOL
2072 If set, INDEX is treated as a utf8 character index, otherwise a
2073 locale-specific index. Default is false.
2074 The "ggo::" commands are:
2076 ggo::Move - move point
2078 ggo::Line - plot line
2079 ggo::Conic - plot 2-degree spline
2080 ggo::Cubic - plot 3-degree spline
2081 render_pattern IMAGE|ICON|ARRAY|INDEX, %OPTIONS
2083 Takes a fill pattern represented by one of "fp::XXX" constant, an
2084 array of 8 bytes, or an image (or icon); same syntax as in
2085 "fillPattern".
2086 Uses %OPTIONS to generate a new rectangular pattern that can be
2088 used in "fillPattern" property. Since Prima does not provide an
2089 individual property that would govern specifically the matrix of a
2090 fill pattern, this method can be used to implement this
2091 functionality.
2092 Also respects "preserveType" property and if it is set, changes the
2094 resulting pattern image type back to the original type. In case
2095 where fillPattern is given by ARRAY or INDEX, always generates a
2096 "im::BW" image, so it can be used both in "rop2" transparent and
2097 opaque modes, like the original pattern.
2098 Options:
2100 color COLOR, alpha 0-255
2102 If "margin" is used, pre-fills target image with this color.
2103 "alpha" is used to pre-fill the target image's mask with this
2104 value, if the image is an icon.
2105 margin XY | [ X, Y ]
2107 Set margins in X and Y pixels before applying the
2108 transformation
2109 matrix MATRIX
2111 2D matrix to transform IMAGE
2112 render_polyline \@POLYLINE, %OPTIONS
2114 Performs calculations on POLYLINE, defined by OPTIONS. The
2115 following options are recognized:
2116 matrix A,B,C,D,U,V
2118 If supplied, performs matrix transformation on each polyline
2119 vertex:
2120 X' = AX + CY + U
2122 Y' = BX + DY + V
2123 and returns the new polyline
2125 box BOOLEAN
2127 If set, instead of polyline vertices, calculates the box
2128 extents of the polyline (either original or after the matrix
2129 transform, depending on whether "matrix" option was supplied or
2130 not), and returns 4 numerics for left,bottom,width,and height
2131 of the box enclosure.
2132 integer BOOLEAN
2134 By default the result is returned as a set of floating point
2135 numerics, however if integer results are needed, the results
2136 are transformed to integers using the int = float + ((float <
2137 0) ? -0.5 : 0.5) formula.
2138 path BOOLEAN
2140 If set, treats polyline as a path that will get applied
2141 "lineEnd", "lineJoin", "linePattern",and "miterLimit"
2142 properties (either from the object or from %OPTIONS) and
2143 returns a set of commands that would represent the final shape.
2144 The commands are: arc (6 arguments, same as the "arc"
2145 primitive), line with 1 argument, a polyline array (respects
2146 the "integer" option), and open with no arguments.
2147 See "widen" in Prima::Drawable::Path for usage.
2149 render_spline \@VERTICES, %OPTIONS
2151 Renders B-spline curve from set of VERTICES to a polyline with
2152 given options.
2153 The method is internally used by "spline" and "fill_spline", and is
2155 provided for cases when these are insufficient. See description of
2156 options in "spline".
2157 text_wrap TEXT, WIDTH, OPTIONS, [TAB_INDENT = 8, FROM = 0, LENGTH = -1,
2159 GLYPHS]
2160 Breaks TEXT string in chunks that must fit into WIDTH pixels wide
2161 box ( for WIDTH >= 0 ). TEXT is either character string, or a
2162 "Prima::Drawable::Glyphs" object returned from "text_shape", or
2163 "Prima::Drawable::Glyphs->glyphs" strings of glyphs. In the glyph
2164 cases, some wrapping options are not applicable. It is possible to
2165 send both text as TEXT and its shaped representation as GLYPHS.
2166 The breaking algorithm and its result are governed by the OPTIONS
2168 integer value that is a combination of the following "tw::"
2169 constants:
2170 tw::CalcMnemonic
2172 Use 'hot key' semantics, when a character preceded by ~ has
2173 special meaning, f ex it gets underlined when used in menus.
2174 If this bit is set, the first tilde character used as an escape
2175 is not calculated, and never appears in the result apart from
2176 the escaped character.
2177 Not applicable in glyph wrapping.
2179 tw::CollapseTilde
2181 In addition to tw::CalcMnemonic, removes '~' character from the
2182 resulting chunks.
2183 Not applicable in glyph wrapping.
2185 tw::CalcTabs
2187 If set, calculates a tab ('\t') character as TAB_INDENT times
2188 space characters.
2189 Not applicable in glyph wrapping.
2191 tw::ExpandTabs
2193 If set, expands tab ('\t') character as TAB_INDENT times space
2194 characters.
2195 Not applicable in glyph wrapping.
2197 tw::BreakSingle
2199 Defines the method behavior when the text cannot be fit in
2200 WIDTH, does not affect anything else otherwise.
2201 If set, the method returns an empty array. If unset, it
2203 returns a text broken by minimum number of characters per
2204 chunk. In the latter case, the width of the resulting text
2205 blocks will exceed WIDTH.
2206 tw::NewLineBreak
2208 Forces creation of a new chunk after a newline character ('\n')
2209 is met. If UTF8 text is passed, unicode line break characters
2210 0x2028 and 0x2029 produce same effect as the newline character.
2211 Not applicable in glyph wrapping.
2213 tw::SpaceBreak
2215 Forces creation of a new chunk after a space character (' ') or
2216 a tab character ('\t') are met.
2217 Not applicable in glyph wrapping.
2219 tw::ReturnChunks
2221 Defines the result of the text_wrap() method.
2222 If set, the array consists of integer pairs, where each is a
2224 text offset within TEXT and its length.
2225 If unset, the resulting array consists of text chunks.
2227 tw::ReturnGlyphs
2229 If GLYPHS are set (only together with TEXT), this option
2230 becomes available to get the resulting chunks as sub-sets of
2231 GLYPHS.
2232 tw::ReturnLines
2234 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
2235 In glyph wrapping means "tw::ReturnGlyphs".
2237 tw::WordBreak
2239 If unset, the TEXT breaks as soon as the chunk width exceeds
2240 WIDTH. If set, tries to keep words in TEXT so they do not
2241 appear in two chunks, e.g. breaks TEXT by words, not by
2242 characters.
2243 If Prima is compiled with the libthai library, and thai text is
2245 detected, Prima uses the library to detects the word
2246 boundaries, because the Thai language does not use spaces
2247 between words. This behavior can be disabled by running Prima
2248 with "--no-libthai".
2249 Not applicable in glyph wrapping.
2251 tw::ReturnFirstLineLength
2253 If set, "text_wrap" proceeds until the first line is wrapped,
2254 either by width or ( if specified ) by break characters.
2255 Returns the length of the resulting line. Used for efficiency
2256 as the inverted "get_text_width" function.
2257 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
2259 the last scalar of the array is a special hash reference. The hash
2260 contains extra information regarding the 'hot key' underline
2261 position - it is assumed that '~' - escapement denotes the
2262 underlined character. The hash contains the following keys:
2263 tildeLine
2265 Chunk index that contains the escaped character. Set to undef
2266 if no ~ - escape was found; the rest of the information in the
2267 hash is not relevant in this case.
2268 tildeStart
2270 Horizontal offset of a beginning of the line that underlines
2271 the escaped character.
2272 tildeEnd
2274 Horizontal offset of an end of the line that underlines the
2275 escaped character.
2276 tildeChar
2278 The escaped character.
2279 Context used: font
2281 text_wrap_shape TEXT, WIDTH = -1, %OPTIONS
2283 Runs "text_shape" over results from "text_wrap" call, with "TEXT",
2284 "WIDTH", $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are
2285 used in "text_shape" call. Where "text_wrap" returns text
2286 substrings or positions, return glyphs objects or their positions
2287 instead.
2288 When called with "tw::CalcMnemonic" options, recalculates the tilde
2290 position so it adapts to the glyph positions returned.
2291 If $OPTIONS{kashida} is set, performs kashida justification on the
2293 last wrapped line, using optional $OPTIONS{min_kashida} value ( see
2294 "arabic_justify" in Prima::Drawable::Glyphs ).
2295 If $OPTIONS{letter} or $OPTIONS{word} is set, performs interspace
2297 justification on all but the last wrapped line.
2298
2300 Dmitry Karasik, <dmitry@karasik.eu.org>.
2301
2303 Prima, Prima::Object, Prima::Image, Prima::Region,
2304 Prima::Drawable::Path, Prima::Drawable::Glyphs
2305perl v5.38.0 2023-07-21 pod::Prima::Drawable(3)