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 Antialiasing and alpha
208 If the system has capability for antialiased drawing and alpha
209 rendering, Prima can use it. The antialiasing can be turned on by
210 calling
211 $drawable->antialias(1)
213 which turns on the following effects:
215 • All primitives except images, "pixel", and "bar_alpha" are plotted
217 with antialiased edges (text is always antialiased when possible).
218 Arcs, lines, paths, all of them manifest adjacent pixels being
219 renderes with half-tones.
220 • Graphic coordinates are then used as floating point numbers, not
222 integers. That means that f ex a call
223 $drawable->rectangle(5.3, 5.3, 10, 10)
225 that had its coordinates automatically rounded to (5,5,10,10), now
227 will render the primitive with subpixel precision, where its two
228 edges will be divided between pixels 5 and 6, by using half-tones.
229 Another note on the rounding off coordinates: historically almost
231 all Prima pixel coordinates were integers, and implicit rounding of
232 the passed numbers were done usinc the "int" function, i e
233 int(0.7)=0 and int(-0.7)=0. This then changed for "polyline" and
234 "fillpoly", that could accept floating point arrays but round them
235 with a more consistent "round" function, where round(0.7)=1 and
236 round(-0.7)=-1. It would be cood idea to change the rounding for
237 the primitives too if not for the backward compatibility.
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 Monochrome bitmaps
249 Prima has special rules when drawing a monochrome Prima::DeviceBitmap.
250 Such objects don't possess an inherent color palette, and by definition
251 are bitmaps with only two pixel values present, 0s and 1s. When a
252 monochrome bitmap is drawn, 0s are painted using the color value of the
253 target canvas "color" property, and 1s using the "backColor" value.
254 That means that the following code
256 $bitmap-> color(0);
258 $bitmap-> line(0,0,100,100);
259 $target-> color(cl::Green);
260 $target-> put_image(0,0,$bitmap);
261 produces a green line on $target.
263 When using monochrome bitmaps for logical operations, note that the
265 target colors should not be explicit 0 and 0xffffff, nor "cl::Black"
266 and "cl::White", but "cl::Clear" and "cl::Set" instead. The reason is
267 that on paletted displays, system palette may not necessarily contain
268 the white color under palette index (2^ScreenDepth-1). "cl::Set" thus
269 signals that the value should be "all ones", no matter what color it
270 represents, because it will be used for logical operations.
271 Fonts
273 Prima maintains its own font naming convention, that usually does not
274 conform to the system's. Since Prima's goal is interoperability, it
275 might be so that some system fonts would not be accessible from within
276 the toolkit.
277 Prima::Drawable provides property "::font", that accepts/returns a
279 hash, that represents the state of a font in the system graphic
280 context. The font hash keys that are acceptable on set-call are:
281 name
283 The font name string. If there is no such font, a default font name
284 is used. To select default font, a 'Default' string can be passed
285 with the same result ( unless the system has a font named
286 'Default', of course).
287 height
289 An integer value from 1 to MAX_INT. Specifies the desired extent of
290 a font glyph between descent and ascent lines in pixels.
291 size
293 An integer value from 1 to MAX_INT. Specifies the desired extent of
294 a font glyph between descent and internal leading lines in points.
295 The relation between "size" and "height" is
296 height - internal_leading
298 size = --------------------------- * 72.27
299 resolution
300 That differs from some other system representations: Win32, for
302 example, rounds 72.27 constant to 72.
303 width
305 A integer value from 0 to MAX_INT. If greater than 0, specifies the
306 desired extent of a font glyph width in pixels. If 0, sets the
307 default ( designed ) width corresponding to the font size or
308 height.
309 style
311 A combination of "fs::" ( font style ) constants. The constants
312 fs::Normal
314 fs::Bold
315 fs::Thin
316 fs::Italic
317 fs::Underlined
318 fs::StruckOut
319 fs::Outline
320 can be OR-ed together to express the font style. fs::Normal equals
322 to 0 and usually never used. If some styles are not supported by a
323 system-dependent font subsystem, they are ignored.
324 pitch
326 One of three constants:
327 fp::Default
329 fp::Fixed
330 fp::Variable
331 "fp::Default" specifies no interest about font pitch selection.
333 "fp::Fixed" is set when a monospaced (all glyphs are of same width)
334 font is desired. "fp::Variable" pitch specifies a font with
335 different glyph widths. This key is of the highest priority; all
336 other keys may be altered for the consistency of the pitch key.
337 vector
339 One of three constants:
340 fv::Default
342 fv::Bitmap
343 fv::Outline
344 "fv::Default" specifies no interest about font type selection,
346 "fv::Bitmap" sets priority for the bitmap fonts, "fv::Outline" for
347 the vector fonts.
348 Additionally, font entries returned from "fonts" method may set
350 "vector" to "fv::ScalableBitmap", to distingush a bitmap font face
351 that comes with predefined bitmap sets from a scalable font.
352 direction
354 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
355 is pi, etc. If a font could not be rotated, it is usually
356 substituted with the one that can.
357 encoding
359 A string value, one of the strings returned by
360 "Prima::Application::font_encodings". Selects desired font
361 encoding; if empty, picks the first matched encoding, preferably
362 the locale set up by the user.
363 The encodings provided by different systems are different; in
365 addition, the only encodings are recognizable by the system, that
366 are represented by at least one font in the system.
367 Unix systems and the toolkit PostScript interface usually provide
369 the following encodings:
370 iso8859-1
372 iso8859-2
373 ... other iso8859 ...
374 fontspecific
375 Win32 returns the literal strings like
377 Western
379 Baltic
380 Cyrillic
381 Hebrew
382 Symbol
383 A hash that "::font" returns, is a tied hash, whose keys are also
385 available as separate properties. For example,
386 $x = $d-> font-> {style};
388 is equivalent to
390 $x = $d-> font-> style;
392 While the latter gives nothing but the arguable coding convenience, its
394 usage in set-call is much more usable:
395 $d-> font-> style( fs::Bold);
397 instead of
399 my %temp = %{$d-> font};
401 $temp{ style} = fs::Bold;
402 $d-> font( \%temp);
403 The properties of a font tied hash are also accessible through set()
405 call, like in Prima::Object:
406 $d-> font-> style( fs::Bold);
408 $d-> font-> width( 10);
409 is an equivalent to
411 $d-> font-> set(
413 style => fs::Bold,
414 width => 10,
415 );
416 When get-called, "::font" property returns a hash where more entries
418 than the described above can be found. These keys are read-only, their
419 values are ignored if passed to "::font" in a set-call.
420 In order to query the full list of fonts available to a graphic device,
422 the "::fonts" method is used. This method is not present in
423 Prima::Drawable namespace; it can be found in two built-in class
424 instances, "Prima::Application" and "Prima::Printer".
425 "Prima::Application::fonts" returns metrics for the fonts available to
427 the screen device, while "Prima::Printer::fonts" ( or its substitute
428 Prima::PS::Printer ) returns fonts for the printing device. The result
429 of this method is an array of font metrics, fully analogous to these
430 returned by "Prima::Drawable::font" method.
431 family
433 A string with font family name. The family is a secondary string
434 key, used for distinguishing between fonts with same name but of
435 different vendors ( for example, Adobe Courier and Microsoft
436 Courier).
437 ascent
439 Number of pixels between a glyph baseline and descent line.
440 descent
442 Number of pixels between a glyph baseline and descent line.
443 internalLeading
445 Number of pixels between ascent and internal leading lines.
446 Negative if the ascent line is below the internal leading line.
447 externalLeading
449 Number of pixels between ascent and external leading lines.
450 Negative if the ascent line is above the external leading line.
451 ------------- external leading line
453 $ ------------- ascent line
455 $ $
456 ------------- internal leading line
457 $
458 $$$
459 $ $
460 $ $ $
461 $$$$$$$ $$$
462 $ $ $ $
463 $ $ $ $
464 $ $ $$$ ---- baseline
465 $
466 $
467 $
468 $$$$ ---- descent line
469 weight
471 Font designed weight. Can be one of
472 fw::UltraLight
474 fw::ExtraLight
475 fw::Light
476 fw::SemiLight
477 fw::Medium
478 fw::SemiBold
479 fw::Bold
480 fw::ExtraBold
481 fw::UltraBold
482 constants.
484 maximalWidth
486 Maximal extent of a glyph in pixels. Equals to width in monospaced
487 fonts.
488 xDeviceRes
490 Designed horizontal font resolution in dpi.
491 yDeviceRes
493 Designed vertical font resolution in dpi.
494 firstChar
496 Index of the first glyph present in a font.
497 lastChar
499 Index of the last glyph present in a font.
500 breakChar
502 Index of the default character used to divide words. In a typical
503 western language font it is 32, ASCII space character.
504 defaultChar
506 Index of a glyph that is drawn instead of nonexistent glyph if its
507 index is passed to the text drawing routines.
508 Font ABC metrics
510 Besides these characteristics, every font glyph has an ABC-metric, the
511 three integer values that describe horizontal extents of a glyph's
512 black part relative to the glyph extent:
513 . . . . . . . .
515 . . $$$. . . . .
516 . . $$. $ . . . .
517 . . $$. . . . $$ . .
518 . $$$$$$$$$$. . .$$$$$ . .
519 . . $$ . . . $ $$ . .
520 . . $$ . . . .$$$$$ . .
521 . . $$ . . . . $$ . .
522 . .$$ . . . . $$$ $$$. .
523 $$ .$$ . . . $ $$ .
524 .$$$ . . . .$$$$$$$$. .
525 . . . . . . . .
526 <A>. .<C> <A>. .<C>
527 .<-.--B--.->. . .<--B--->. .
528 A = -3 A = 3
530 B = 13 B = 10
531 C = -3 C = 3
532 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
534 in picture on the left. A and C values are positive, if a glyph
535 contains empty space in front or behind the neighbor glyphs, like in
536 picture on the right. As can be seen, B is the width of a glyph's
537 black part.
538 ABC metrics returned by the get_font_abc() method.
540 The corresponding vertical metrics, called in Prima "DEF" metrics, are
542 returned by the get_font_def() method.
543 Raster operations
545 A drawable has two raster operation properties: "::rop" and "::rop2".
546 These define how the graphic primitives are plotted. "::rop" deals with
547 the foreground color drawing, and "::rop2" with the background.
548 Universal ROPs
550 The toolkit defines the following operations:
552 rop::Blackness # = 0
554 rop::NotOr # = !(src | dest)
555 rop::NotSrcAnd # &= !src
556 rop::NotPut # = !src
557 rop::NotDestAnd # = !dest & src
558 rop::Invert # = !dest
559 rop::XorPut # ^= src
560 rop::NotAnd # = !(src & dest)
561 rop::AndPut # &= src
562 rop::NotXor # = !(src ^ dest)
563 rop::NotSrcXor # alias for rop::NotXor
564 rop::NotDestXor # alias for rop::NotXor
565 rop::NoOper # = dest
566 rop::NotSrcOr # |= !src
567 rop::CopyPut # = src
568 rop::NotDestOr # = !dest | src
569 rop::OrPut # |= src
570 rop::Whiteness # = 1
571 Usually, however, graphic devices support only a small part of the
573 above set, limiting "::rop" to the most important operations: Copy,
574 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
575 only Copy and NoOp.
576 The raster operations apply to all graphic primitives except SetPixel.
578 Note for layering: using layered images and device bitmaps with
580 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
581 "rop::SrcOver" raster operations on OS-provided surfaces.
582 Also, "rop::AlphaCopy" operation is available for accessing alpha bits
584 only. When used, the source image is treated as alpha mask, and
585 therefore it has to be grayscale. It can be used to apply the alpha
586 bits independently, without need to construct an Icon object.
587 Additional ROPs
589 Prima implements extra features for compositing on images outside the
591 begin_paint/end_paint brackets. It supports the following 12 Porter-
592 Duff operators and some selected Photoshop blend operators:
593 rop::Clear rop::Add
595 rop::Xor rop::Multiply
596 rop::SrcOver rop::Screen
597 rop::DstOver rop::Overlay
598 rop::SrcCopy rop::Darken
599 rop::DstCopy rop::Lighten
600 rop::SrcIn rop::ColorDodge
601 rop::DstIn rop::ColorBurn
602 rop::SrcOut rop::HardLight
603 rop::DstOut rop::SoftLight
604 rop::SrcAtop rop::Difference
605 rop::DstAtop rop::Exclusion
606 Transparency control
608 There is defined a set of constants to apply a constant source and
609 destination alpha to when there is no alpha channel available:
610 rop::SrcAlpha
612 rop::SrcAlphaShift
613 rop::DstAlpha
614 rop::DstAlphaShift
615 Combine the rop constant using this formula:
617 $rop = rop::XXX |
619 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
620 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
621 or by calling "rop::alpha($rop, [ $src_alpha, [ $dst_alpha ]])"
623 that does the same.
624 Also, the function "rop::blend($alpha)" creates a rop constant for
626 simple blending of two images by the following formula:
627 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
629 "rop::alpha" also can be used for drawing on images outside
631 begin_paint/end_paint with all Porter-Duff and Photoshop raster
632 operators:
633 $image->rop( rop::alpha( rop::SrcOver, 128 ));
635 $image->ellipse( 5, 5, 5, 5 );
636 Note that when the raster operation is set to "rop::SrcOver"
638 (default), the fully identical effect can be achieved by
639 $image->alpha(128);
641 $image->ellipse( 5, 5, 5, 5 );
642 as well. In both cases, the values of "color" and "backColor" are
644 internally premultiplied with the alpha.
645 When used with icons, their source and/or destination alpha
647 channels are additionally multiplied with these values.
648 rop::Premultiply
650 When this bit is set, source pixels will be multiplied with alpha
651 before blending
652 rop::ConstantColor
654 This bit is used when the alpha is defined but the main bits
655 aren't. In this case, the main bits are filled from the
656 destination's image color, and the source image treated as the
657 source alpha channel. The following code applies a solid green
658 shade with a mask loaded from file.
659 $src->load('8-bit gray mask.png');
661 $dst->color(cl::LightGreen);
662 $dst->put_image( 0,0,$src,rop::SrcOver | rop::ConstantColor | rop::Premultiply);
663 Also, remember "rop::Premultiply" for proper results.
665 Coordinates
667 The Prima toolkit employs the XY grid, where X ascends rightwards and Y
668 ascends upwards. There, the (0,0) location is the bottom-left pixel of
669 a canvas.
670 All graphic primitives use inclusive-inclusive boundaries. For
672 example,
673 $d-> bar( 0, 0, 1, 1);
675 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
677 The coordinate origin can be shifted using "::translate" property, that
679 translates the (0,0) point to the given offset. Calls to "::translate",
680 "::clipRect" and "::region" always use the 'physical' (0,0) point,
681 whereas the plotting methods use the transformation result, the
682 'logical' (0,0) point.
683 As noted before, these three properties cannot be used in when an
685 object is in the disabled state.
686
688 Graphic context properties
689 alpha INTEGER
690 Sets alpha component of the brush, where 0 is fully transparent and
691 255 is fully opaque.
692 Note that premultiplication of "color" and "backColor" is not
694 necessary as it is done internally.
695 Default: 255
697 antialias BOOLEAN
699 Turns on and off antialiased drawing on all primitives, excluding
700 image, "pixel", and "bar_alpha" calls.
701 It will not be possible to turn the property on if the system does
703 not support it. Also, monochrome images won't support it as well.
704 See "Antialiasing and alpha".
706 backColor COLOR
708 Sets background color to the graphic context. All drawing routines
709 that use non-solid or transparent fill or line patterns use this
710 property value.
711 color COLOR
713 Sets foreground color to the graphic context. All drawing routines
714 use this property value.
715 clipRect X1, Y1, X2, Y2
717 Selects the clipping rectangle corresponding to the physical canvas
718 origin. On get-call, returns the extent of the clipping area, if
719 it is not rectangular, or the clipping rectangle otherwise. The
720 code
721 $d-> clipRect( 1, 1, 2, 2);
723 $d-> bar( 0, 0, 1, 1);
724 thus affects only one pixel at (1,1).
726 Set-call discards the previous "::region" value.
728 Note: "::clipRect" can not be used while the object is in the
730 paint-disabled state, its context is neither recorded nor used as a
731 template ( see "Graphic context and canvas") -- except on images.
732 fillMode INTEGER
734 Affects filling style of complex polygonal shapes filled by
735 "fillpoly". If "fm::Winding", the filled shape contains no holes;
736 if "fm::EvenOdd", holes are present where the shape edges cross.
737 "fm::Overlay" flag can be combined with these to counter an
739 intrinsic defect of filled shaped both in Win32 and X11 that don't
740 exactly follow polygon vertices. When supplied, it overlays a
741 polygon over the filled shape, so that the latter falls exactly in
742 the boundaries defined by vertices. This is desirable when one
743 wants to follow polygon vertices, but is not desirable when a shape
744 has holes in it connected in a way that the polygon overlay may
745 leave connection edges over them.
746 Default value: "fm::Winding|fm::Overlay"
748 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
750 Selects 8x8 fill pattern that affects primitives that plot filled
751 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
752 fill_sector(), floodfill().
753 Accepts either a "fp::" constant or a reference to an array of 8
755 integers, each representing 8 bits of each line in a pattern, where
756 the first integer is the topmost pattern line, and the bit 0x80 is
757 the leftmost pixel in the line.
758 There are some predefined patterns, that can be referred via "fp::"
760 constants:
761 fp::Empty
763 fp::Solid
764 fp::Line
765 fp::LtSlash
766 fp::Slash
767 fp::BkSlash
768 fp::LtBkSlash
769 fp::Hatch
770 fp::XHatch
771 fp::Interleave
772 fp::WideDot
773 fp::CloseDot
774 fp::SimpleDots
775 fp::Borland
776 fp::Parquet
777 ( the actual patterns are hardcoded in primguts.c ) The default
779 pattern is fp::Solid.
780 An example below shows encoding of fp::Parquet pattern:
782 # 76543210
784 84218421 Hex
785 0 $ $ $ 51
787 1 $ $ 22
788 2 $ $ $ 15
789 3 $ $ 88
790 4 $ $ $ 45
791 5 $ $ 22
792 6 $ $ $ 54
793 7 $ $ 88
794 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
796 On a get-call always returns an array, never a "fp::" constant.
798 fillPatternOffset X, Y
800 Origin coordinates for the "fillPattern", from 0 to 7.
801 font \%FONT
803 Manages font context. FONT hash acceptable values are "name",
804 "height", "size", "width", "style" and "pitch".
805 Synopsis:
807 $d-> font-> size( 10);
809 $d-> font-> name( 'Courier');
810 $d-> font-> set(
811 style => $x-> font-> style | fs::Bold,
812 width => 22
813 );
814 See "Fonts" for the detailed descriptions.
816 Applies to text_out(), get_text_width(), get_text_box(),
818 get_font_abc(), get_font_def(), render_glyph().
819 font_mapper
821 Returns a font mapper object that provides interface to fonts
822 collection used for substitution in polyfont shaping (see
823 "text_shape"). The fonts can be accessed there either by their font
824 hash (name and style only, currently), or the font's corresponding
825 index.
826 There are two font lists used in the substituion mechanism, passive
828 and active. The passive font list is initiated during the toolkit
829 start and is never changed. Each font there is addressed by an
830 index. When the actual search for a glyph is initiated, these fonts
831 are queried in the loop and are checked if they contain the
832 required glyphs. These queries are also cached, so that next time
833 lookups run much quicker. That way, an "active" font list is built,
834 and next substitutions use it before trying to look into the
835 passive list. Since the ordering of fonts is system based, and is
836 rather random, some fonts may not be a good or aesthetic
837 substition. Therefore the mapper can assist in adding or removing
838 particular fonts to the active list, potentially allowing an
839 application to store and load user-driven selection of substitution
840 fonts.
841 The following methods are available on the font mapper object:
843 activate %FONT
845 Adds the FONT into the active substitution list if the font is
846 not disabled
847 get INDEX
849 Returns the font hash registered under INDEX
850 count
852 Returns number of all fonts in the collection
853 index
855 Returns what index is assigned to the currently used font, if
856 any
857 passivate %FONT
859 Remove the font from the active substitution list
860 is_active %FONT
862 Returns whether the font is in the active substitution list or
863 not
864 enable %FONT
866 Enables the font entry, the font will be considered for the
867 polyfont lookup
868 disable %FONT
870 Disables the font entry, the font will not be considered for
871 the polyfont lookup
872 is_enabled %FONT
874 Returns whether the font is enabled or not
875 lineEnd VALUE
877 Selects a line ending cap for plotting primitives. VALUE can be one
878 of
879 le::Flat
881 le::Square
882 le::Round
883 constants. le::Round is the default value.
885 lineJoin VALUE
887 Selects a line joining style for polygons. VALUE can be one of
888 lj::Round
890 lj::Bevel
891 lj::Miter
892 constants. lj::Round is the default value.
894 linePattern PATTERN
896 Selects a line pattern for plotting primitives. PATTERN is either
897 a predefined "lp::" constant, or a string where each even byte is a
898 length of a dash, and each odd byte is a length of a gap.
899 The predefined constants are:
901 lp::Null # "" /* */
903 lp::Solid # "\1" /* ___________ */
904 lp::Dash # "\x9\3" /* __ __ __ __ */
905 lp::LongDash # "\x16\6" /* _____ _____ */
906 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
907 lp::Dot # "\1\3" /* . . . . . . */
908 lp::DotDot # "\1\1" /* ............ */
909 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
910 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
911 Not all systems are capable of accepting user-defined line
913 patterns, and in such situation the "lp::" constants are mapped to
914 the system-defined patterns. In Win9x, for example, lp::DashDotDot
915 is much different from its string definition.
916 Default value is lp::Solid.
918 lineWidth WIDTH
920 Selects a line width for plotting primitives. If a VALUE is 0,
921 then a cosmetic pen is used - the thinnest possible line that a
922 device can plot. If a VALUE is greater than 0, then a geometric pen
923 is used - the line width is set in device units. There is a subtle
924 difference between VALUE 0 and 1 in a way the lines are joined.
925 Default value is 0.
927 miterLimit VALUE
929 When path segments connect at a sharp angle, a miter join results
930 in a spike that extends well beyond the connection point. The
931 purpose of the miter limit is to cut off such spikes when they
932 become objectionably long. At any given corner, the miter length is
933 the distance from the point at which the inner edges of the stroke
934 intersect to the point at which the outside edges of the strokes
935 intersect-in other words, the diagonal length of the miter. This
936 distance increases as the angle between the segments decreases. If
937 the ratio of the miter length to the line width exceeds the miter
938 limit parameter, stroke treats the corner with a bevel join instead
939 of a miter join. The ratio of miter length to line width is
940 directly related to the angle j between the segments by the
941 formula:
942 r = 1/sin(j/2)
944 Default value is 10.0.
946 Asssuming line join is "lj::Miter" and line angle is 30 degrees:
948 miter limit = 1.0: \__/
950 miter limit = 9.0: \ /
952 \/
953 Note: does not work under X11.
955 palette [ @PALETTE ]
957 Selects solid colors in a system palette, as many as possible.
958 PALETTE is an array of integer triplets, where each is R, G and B
959 component. The call
960 $d-> palette([128, 240, 240]);
962 selects a gray-cyan color, for example.
964 The return value from get-call is the content of the previous set-
966 call, not the actual colors that were copied to the system palette.
967 region OBJECT
969 Selects a clipping region applied to all drawing and painting
970 routines. On setting, the OBJECT is either undef, then the clip
971 region is erased ( no clip ), or a Prima::Image object with a bit
972 depth of 1. The bit mask of OBJECT is applied to the system
973 clipping region. Or, it is a Prima::Region object. If the OBJECT
974 is smaller than the drawable, its exterior is assigned to clipped
975 area as well. Discards the previous "::clipRect" value; successive
976 get-calls to "::clipRect" return the boundaries of the region.
977 On getting, OBJECT is either undef or Prima::Region object.
979 Note: "::region" can not be used while the object is in the paint-
981 disabled state, its context is neither recorded nor used as a
982 template ( see "Graphic context and canvas").
983 resolution X, Y
985 A read-only property. Returns horizontal and vertical device
986 resolution in dpi.
987 rop OPERATION
989 Selects raster operation that applies to foreground color plotting
990 routines.
991 See also: "::rop2", "Raster operations".
993 rop2 OPERATION
995 Selects raster operation that applies to background color plotting
996 routines.
997 See also: "::rop", "Raster operations".
999 textOpaque FLAG
1001 If FLAG is 1, then text_out() fills the text background area with
1002 "::backColor" property value before drawing the text. Default value
1003 is 0, when text_out() plots text only.
1004 See get_text_box().
1006 textOutBaseline FLAG
1008 If FLAG is 1, then text_out() plots text on a given Y coordinate
1009 correspondent to font baseline. If FLAG is 0, a Y coordinate is
1010 mapped to font descent line. Default is 0.
1011 translate X_OFFSET, Y_OFFSET
1013 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
1014 affect "::clipRect" and "::region". Not cumulative, so the call
1015 sequence
1016 $d-> translate( 5, 5);
1018 $d-> translate( 15, 15);
1019 is equivalent to
1021 $d-> translate( 15, 15);
1023 Note: "::translate" can not be used while the object is in the
1025 paint-disabled state, its context is neither recorded nor used as a
1026 template ( see "Graphic context and canvas").
1027 Other properties
1029 height HEIGHT
1030 Selects the height of a canvas.
1031 size WIDTH, HEIGHT
1033 Selects the extent of a canvas.
1034 width WIDTH
1036 Selects the width of a canvas.
1037 Graphic primitives methods
1039 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1040 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
1041 from START_ANGLE to END_ANGLE.
1042 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1044 miterLimit, rop, rop2
1045 bar X1, Y1, X2, Y2
1047 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
1048 Context used: color, backColor, fillPattern, fillPatternOffset,
1050 rop, rop2
1051 bar_alpha ALPHA <X1, Y1, X2, Y2>
1053 Fills rectangle in the alpha channel, filled with ALPHA value
1054 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
1055 parameters, in this case fills all canvas area.
1056 Has only effect on layered surfaces.
1058 bars @RECTS
1060 Draws a set of filled rectangles. RECTS is an array of integer
1061 quartets in format (X1,Y1,X2,Y2).
1062 Context used: color, backColor, fillPattern, fillPatternOffset,
1064 rop, rop2
1065 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1067 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
1068 from START_ANGLE to END_ANGLE and connects its ends with the
1069 straight line.
1070 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1072 miterLimit, rop, rop2
1073 clear <X1, Y1, X2, Y2>
1075 Draws rectangle filled with pure background color within (X1,Y1) -
1076 (X2,Y2) extents. Can be called without parameters, in this case
1077 fills all canvas area.
1078 Context used: backColor, rop2
1080 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
1082 TAB_INDENT = 1 ]
1083 Draws several lines of text one under another with respect to align
1084 and break rules, specified in FLAGS and TAB_INDENT tab character
1085 expansion.
1086 "draw_text" is a convenience wrapper around "text_wrap" for drawing
1088 the wrapped text, and also provides the tilde ( ~ )- character
1089 underlining support.
1090 The FLAGS is a combination of the following constants:
1092 dt::Left - text is aligned to the left boundary
1094 dt::Right - text is aligned to the right boundary
1095 dt::Center - text is aligned horizontally in center
1096 dt::Top - text is aligned to the upper boundary
1097 dt::Bottom - text is aligned to the lower boundary
1098 dt::VCenter - text is aligned vertically in center
1099 dt::DrawMnemonic - tilde-escapement and underlining is used
1100 dt::DrawSingleChar - sets tw::BreakSingle option to
1101 Prima::Drawable::text_wrap call
1102 dt::NewLineBreak - sets tw::NewLineBreak option to
1103 Prima::Drawable::text_wrap call
1104 dt::SpaceBreak - sets tw::SpaceBreak option to
1105 Prima::Drawable::text_wrap call
1106 dt::WordBreak - sets tw::WordBreak option to
1107 Prima::Drawable::text_wrap call
1108 dt::ExpandTabs - performs tab character ( \t ) expansion
1109 dt::DrawPartial - draws the last line, if it is visible partially
1110 dt::UseExternalLeading - text lines positioned vertically with respect to
1111 the font external leading
1112 dt::UseClip - assign ::clipRect property to the boundary rectangle
1113 dt::QueryLinesDrawn - calculates and returns number of lines drawn
1114 ( contrary to dt::QueryHeight )
1115 dt::QueryHeight - if set, calculates and returns vertical extension
1116 of the lines drawn
1117 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
1118 dt::WordWrap - performs word wrapping by the width of the boundaries
1119 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
1120 dt::UseExternalLeading
1121 Context used: color, backColor, font, rop, textOpaque,
1123 textOutBaseline
1124 ellipse X, Y, DIAMETER_X, DIAMETER_Y
1126 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
1127 axes.
1128 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1130 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1132 Fills a chord outline with center in X, Y and DIAMETER_X and
1133 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see chord()).
1134 Context used: color, backColor, fillPattern, fillPatternOffset,
1136 rop, rop2
1137 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
1139 Fills an elliptical outline with center in X, Y and DIAMETER_X and
1140 DIAMETER_Y axes.
1141 Context used: color, backColor, fillPattern, fillPatternOffset,
1143 rop, rop2
1144 fillpoly \@POLYGON
1146 Fills a polygonal area defined by POLYGON set of points. POLYGON
1147 must present an array of integer pair in (X,Y) format. Example:
1148 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
1150 Context used: color, backColor, fillPattern, fillPatternOffset,
1152 rop, rop2, fillMode
1153 Returns success flag; if failed, $@ contains the error.
1155 See also: polyline().
1157 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1159 Fills a sector outline with center in X, Y and DIAMETER_X and
1160 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see sector()).
1161 Context used: color, backColor, fillPattern, fillPatternOffset,
1163 rop, rop2
1164 fill_spline \@VERTICES, %OPTIONS
1166 Fills a polygonal area defined by the curve, projected by applying
1167 B-spline curve based on set of VERTICES. VERTICES must present an
1168 array of integer pair in (X,Y) format. Example:
1169 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1171 Context used: color, backColor, fillPattern, fillPatternOffset,
1173 rop, rop2
1174 Returns success flag; if failed, $@ contains the error.
1176 See also: spline, render_spline
1178 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1180 Fills an area of the canvas using the current fill context. The
1181 area is assumed to be bounded as specified by the SINGLEBORDER
1182 parameter. SINGLEBORDER can be 0 or 1.
1183 SINGLEBORDER = 0: The fill area is bounded by the color specified
1185 by the COLOR parameter.
1186 SINGLEBORDER = 1: The fill area is defined by the color that is
1188 specified by COLOR. Filling continues outward in all directions as
1189 long as the color is encountered. This style is useful for filling
1190 areas with multicolored boundaries.
1191 Context used: color, backColor, fillPattern, fillPatternOffset,
1193 rop, rop2
1194 line X1, Y1, X2, Y2
1196 Plots the straight line from (X1,Y1) to (X2,Y2).
1197 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1199 lines \@LINES
1201 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1202 lines() plots the straight line per quartet.
1203 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1205 Returns success flag; if failed, $@ contains the error.
1207 new_aa_surface
1209 Returns a new antialiasing surface object for AA emulation. See
1210 Prima::Drawable::Antialias for usage and details.
1211 new_gradient
1213 Returns a new gradient object. See Prima::Drawable::Gradient for
1214 usage and details.
1215 new_path
1217 Returns a new path object. See Prima::Drawable::Path for usage and
1218 details.
1219 pixel X, Y, <COLOR>
1221 ::pixel is a property - on set-call it changes the pixel value at
1222 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1223 pixel value at (X,Y).
1224 No context is used. May return "cl::Invalid" to signal an error or
1226 the out-of-boundaries condition.
1227 polyline \@POLYGON
1229 Draws a polygonal area defined by the POLYGON set of points.
1230 POLYGON must contain an array of integer pairs in (X,Y) format.
1231 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1233 lineEnd, miterLimit, rop, rop2
1234 Returns success flag; if failed, $@ contains the error.
1236 See also: fillpoly().
1238 put_image X, Y, OBJECT, [ ROP ]
1240 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1241 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1242 specified, it is used. Otherwise, value of "::rop" property is
1243 used.
1244 Returns success flag; if failed, $@ contains the error.
1246 Context used: rop; color and backColor for a monochrome
1248 DeviceBitmap
1249 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1251 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1252 Draws the OBJECT's source rectangle into the destination rectangle,
1253 stretching or compressing the source bits to fit the dimensions of
1254 the destination rectangle, if necessary. The source rectangle
1255 starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide and
1256 SRC_HEIGHT pixels tall. The destination rectangle starts at (X,Y),
1257 and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT) pixels
1258 tall. If DEST_WIDTH or DEST_HEIGHT are negative, a mirroring by
1259 respective axis is performed.
1260 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1262 No context is used, except color and backColor for a monochrome
1264 DeviceBitmap
1265 Returns success flag; if failed, $@ contains the error.
1267 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1269 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1270 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1271 specified, paints an inferior rectangle with it, otherwise the
1272 inferior rectangle is not touched.
1273 Context used: rop; color and backColor for a monochrome
1275 DeviceBitmap
1276 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1278 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1279 line width.
1280 No context is used.
1282 rectangle X1, Y1, X2, Y2
1284 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1285 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1287 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1289 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1290 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1291 two straight lines.
1292 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1294 miterLimit, rop, rop2
1295 spline \@VERTICES, %OPTIONS
1297 Draws a B-spline curve defined by set of VERTICES control points.
1298 VERTICES must present an array of integer pair in (X,Y) format.
1299 The following options are supported:
1301 closed BOOL = undef
1303 When not set, checks if the first and the last vertices point
1304 to the same point, and if yes, assumes a closed shape. Note - a
1305 closed shape rendering is implemented by adding degree minus
1306 two points to the set; this is important if "weight" or "knots"
1307 are specificed.
1308 degree INTEGER = 2
1310 The B-spline degree. Default is 2 (quadratic). Number of points
1311 supplied must be at least degree plus one.
1312 knots \@INTEGERS
1314 Array of integers, number of points plus degree plus one, which
1315 makes the result a Bezier curve. By default, if the shape is
1316 opened (i.e. first and last points are different), is set to
1317 represent a clamped array, so that the first and last points of
1318 the final curve match the first and the last control points. If
1319 the shape is closed, set to represent an unclamped array, so
1320 that no control points lie directly on the curve.
1321 precision INTEGER = 24
1323 Defines number of steps to split the curve into. The value is
1324 multiplied to the number of points and the result is used as
1325 number of steps.
1326 weight \@INTEGERS = [ 1, 1, 1, ... ]
1328 Array of integers, one for each point supplied. Assigning these
1329 can be used to convert B-spline into a NURBS. By default set of
1330 ones.
1331 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1333 miterLimit, rop, rop2
1334 See also: fill_spline, render_spline.
1336 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1338 Draws the OBJECT on the destination rectangle, stretching or
1339 compressing the source bits to fit the dimensions of the
1340 destination rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT
1341 are negative, a mirroring is performed. The destination rectangle
1342 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1343 pixels tall.
1344 If ROP raster operation is specified, it is used. Otherwise, value
1346 of "::rop" property is used.
1347 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1349 Returns success flag; if failed, $@ contains the error.
1351 Context used: rop
1353 text_out TEXT, X, Y
1355 Draws TEXT string at (X,Y). TEXT is either character string, or a
1356 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1357 "Prima::Drawable::Glyphs->glyphs" strings of glyphs.
1358 Returns success flag; if failed, $@ contains the error.
1360 Context used: color, backColor, font, rop, textOpaque,
1362 textOutBaseline
1363 text_shape TEXT, %OPTIONS
1365 Converts TEXT into set of glyphs, returns either a
1366 "Prima::Drawable::Glyphs" object, or a 0 integer when shaping is
1367 not necessary, or "undef" as an error.
1368 When Prima is compiled with "libfribidi", the method runs unicode
1370 bidirectional algorithm on TEXT that properly positions embedded
1371 directional text (f.ex. a latin quote inside an arabic text), see
1372 Unicode Standard Annex #9 for the details. Without the library
1373 only does minimal RTL alignment.
1374 Glyphs returned are positioned according to RTL directions given in
1376 TEXT using characters from uncode block "General Punctuation U+2000
1377 .. U+206F". Additionally, character ligation may be performed so
1378 that one or more characters are respresented by one or more glyphs.
1379 Such syntatic units, clusters, are adopted in Prima where
1380 appropriate, instead of character units, for selection, navigation
1381 etc in f.ex. "Prima::InputLine" and "Prima::Edit". Helper routines
1382 that translate clusters, glyphs, and characters into each other are
1383 found in Prima::Drawable::Glyphs.
1384 Options recognized:
1386 advances BOOLEAN = false
1388 Shaping process may or may not fill integer array of advances
1389 and positions for each glyphs, depending on the implementation.
1390 The advances are needed to represent f.ex. combining graphemes,
1391 when TEXT consisting of two characters, "A" and combining grave
1392 accent U+300 should be drawn as a single À cluster but are
1393 represented by two glyphs "A" and "`". The grave glyph has its
1394 own advance for standalone usage, but in this case it should be
1395 ignored, and that is achieved by filling advance table where
1396 the "A" advance is the normal glyph advance, whereas the
1397 advance of the "`" is zero. Also, the position table
1398 additionaly shifts glyph position by X and Y coordinates, when
1399 that is needed (f.ex. it might be positioned differently by the
1400 vertical axis on "a" and "A").
1401 Setting this options to "true" will force fill advance and
1403 positioning tables. These tables can be manipulated later, and
1404 are respected by "text_out" and "get_text_width".
1405 language STRING = undef
1407 When set, shaping process can take in the account the language
1408 of the text. F.ex. text "ae" might be shaped as a single glyph
1409 æ for the Latin language, but never for the English.
1410 level INTEGER = ts::Full
1412 Selects the shaping (i.e. text to glyph conversion) level, how
1413 the system should treat the input text and how deep the shaping
1414 should go.
1415 One of the following "ts::XXX" options:
1417 ts::Bytes
1419 Treats input text as non-unicode locale-specific
1420 codepoints, characters higher than 255 are treated as
1421 chr(255). Reordering never happens, font substition never
1422 happens, kerning and ligation never happens; returns glyph
1423 indexes in a 1:1 mapping for each codepoint.
1424 ts::None
1426 Performs quick null shaping without mapping to the font
1427 glyphs, but only running bidirectional algorithm on the
1428 text. On the return, "glyphs", as well as eventual
1429 "advances" and "positions", are filled with zeros, but
1430 "indexes" are filled with the proper character offsets,
1431 effectively making it a visual-to-logical map since the
1432 number of glyphs will always be equal to the number of
1433 characters in TEXT, because ligation never happens here
1434 (except when TEXT contains unicode directional characters
1435 such as isolates etc - those are removed from the output).
1436 By default, advances and positions are not filled, but if
1438 the "advances" option is set, fills them with zeros.
1439 ts::Glyphs
1441 Applies the unicode bidi algoritm and maps the result onto
1442 font glyphs. Ligation and kerning doesn't happen here,
1443 it's basically same as "ts::None" but with the glyph
1444 mapping part.
1445 By default, advances and positions are not filled, but if
1447 "advances" option is set, fills the advances array with
1448 character glyph advances and the positions array with
1449 zeros.
1450 May fill the "fonts" array if the "polyfont" option is set.
1452 ts::Full
1454 Applies the unicode bidi algorithm, and runs the full
1455 shaping on the result. Ligation and kerning may occur.
1456 Always fills the advances and positions array; the
1457 "advances" option is ignored.
1458 If the system or the selected font does not support
1460 shaping, tries to ligate known arabic shapes using the
1461 fribidi library, if available. Also in this case does not
1462 return the advances and positions by default, but if
1463 "advances" option is set, fills the advances array with
1464 character glyph advances and the positions array with
1465 zeros.
1466 May fill the "fonts" array if the "polyfont" option is set.
1468 pitch INTEGER
1470 When the "polyfont" is set (default) and thus font substitution
1471 is desired, filters only fonts that match "pitch", either
1472 "fp::Variable" or "fp::Fixed". By default will be set to
1473 "fp::Fixed" if the current for is monospaced, but to
1474 "fp::Default" matching all fonts, otherwise.
1475 polyfont BOOLEAN = true
1477 If set, scans if the currently selected font supports all
1478 unicode points, and if not, selects a substituions from a pre-
1479 populated list, taking into account the font pitch (see "pitch"
1480 above). In cases where the current font has not enough glyphs
1481 to shape all the requested unicode points, font substitution is
1482 performed, and the result contains an extra array "fonts" (see
1483 "fonts" in Prima::Drawable::Glyphs). When the current font has
1484 all needed glyphs, the fonts array is not created.
1485 The font list access is available through "font_mapper".
1487 Valid only with shaping levels "ts::Glyphs" and "ts::Full".
1489 reorder BOOLEAN = true
1491 When set, unicode bidi algorithm is used to reorder codepoints,
1492 and additionally RTL codepoints may be reversed (depending on
1493 direction context).
1494 When unset, no such reordering occurs, to emulate as much as
1496 possible a behavior that each text grapheme is being mapped to
1497 a glyph cluster exactly as it occurs in the input text, from
1498 left to right. Note that bidi reordering still may occur
1499 internally, since system shapers may reverse placement of RTL
1500 characters, so that the Prima reordering is needed to cancel
1501 this. In theory the caller shouldn't see the difference as
1502 these should cancel each other, but if Prima miscalculates the
1503 expected way the system shaper does the bidi processing, it
1504 might.
1505 A similar effect can be reached by prepending the text with
1507 U+202D (LEFT-TO-RIGHT OVERRIDE).
1508 rtl BOOLEAN
1510 If set to 1, default text direction is assumed as RTL, and as
1511 LTR if set to 0. If unset, the text direction is taken from
1512 "textDirection" in Prima::Application.
1513 skip_if_simple BOOLEAN = false
1515 When set, checks whether the shaping result is identical to the
1516 input, in a sense that a call to "text_out(TEXT)" and a call to
1517 "text_shape_out(TEXT)" produce identical results. Majority of
1518 english text will fall into that category, and when that indeed
1519 happens, returns integer value 0 instead of a glyph object.
1520 See also "text_shape_out", "get_text_shape_width",
1522 "text_wrap_shape".
1523 text_shape_out TEXT, X, Y[, RTL]
1525 Runs shaping on TEXT character string with the RTL flag (or
1526 "$::application->textDirection". Draws the resulting glyph string
1527 at (X,Y).
1528 Returns success flag; if failed, $@ contains the error.
1530 Context used: color, backColor, font, rop, textOpaque,
1532 textOutBaseline
1533 Methods
1535 begin_paint
1536 Enters the enabled ( active paint ) state, returns success flag; if
1537 failed, $@ contains the error. Once the object is in enabled
1538 state, painting and drawing methods can perform write operations on
1539 a canvas.
1540 See also: "end_paint", "begin_paint_info", "Graphic context and
1542 canvas"
1543 begin_paint_info
1545 Enters the information state, returns success flag; if failed, $@
1546 contains the error. The object information state is same as
1547 enabled state ( see "begin_paint"), except painting and drawing
1548 methods do not change the object canvas.
1549 See also: "end_paint_info", "begin_paint", "Graphic context and
1551 canvas"
1552 can_draw_alpha
1554 Returns whether using alpha bits operation on the drawable will
1555 have any effect or not. Note that the drawable may not necessarily
1556 have an alpha channel, for example a normal RGB image is capable to
1557 be painted on with alpha while not having any alpha on its own. On
1558 unix, all non-1 bit drawables return true if Prima was compiled
1559 with XRender support and if that extension is present on the X
1560 server. On windows, all non-1 bit drawables return true
1561 unconditionally.
1562 See also: "has_alpha_layer"
1564 end_paint
1566 Exits the enabled state and returns the object to a disabled state.
1567 See also: "begin_paint", "Graphic context and canvas"
1569 end_paint_info
1571 Exits the information state and returns the object to a disabled
1572 state.
1573 See also: "begin_paint_info", "Graphic context and canvas"
1575 font_match \%SOURCE, \%DEST, PICK = 1
1577 Performs merging of two font hashes, SOURCE and DEST. Returns the
1578 merge result. If PICK is true, matches the result with a system
1579 font repository.
1580 Called implicitly by "::font" on set-call, allowing the following
1582 example to work:
1583 $d-> font-> set( size => 10);
1585 $d-> font-> set( style => fs::Bold);
1586 In the example, the hash 'style => fs::Bold' does not overwrite the
1588 previous font context ( 'size => 10' ) but gets added to it ( by
1589 font_match()), providing the resulting font with both font
1590 properties set.
1591 fonts <FAMILY = "", ENCODING = "">
1593 Member of "Prima::Application" and "Prima::Printer", does not
1594 present in "Prima::Drawable".
1595 Returns an array of font metric hashes for a given font FAMILY and
1597 ENCODING. Every hash has full set of elements described in
1598 "Fonts".
1599 If called without parameters, returns an array of same hashes where
1601 each hash represents a member of font family from every system font
1602 set. It this special case, each font hash contains additional
1603 "encodings" entry, which points to an array of encodings available
1604 for the font.
1605 If called with FAMILY parameter set but no ENCODING is set,
1607 enumerates all combinations of fonts with all available encodings.
1608 If called with FAMILY set to an empty string, but ENCODING
1610 specified, returns only fonts that can be displayed with the
1611 encoding.
1612 Example:
1614 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1616 get_bpp
1618 Returns device color depth. 1 is for black-and-white monochrome, 24
1619 for true color, etc.
1620 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1622 Returns ABC font metrics for the given range, starting at
1623 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1624 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1625 responsible of representation of characters in 127-255 range. If
1626 0, the default, encoding-dependent characters are assumed. If 1,
1627 the U007F-U00FF glyphs from Latin-1 set are used.
1628 The result is an integer array reference, where every character
1630 glyph is referred by three integers, each triplet containing A, B
1631 and C values.
1632 For detailed explanation of ABC meaning, see "Font ABC metrics";
1634 Context used: font
1636 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1638 Same as "get_font_abc", but for vertical mertics. Is expensive on
1639 bitmap fonts, because to find out the correct values Prima has to
1640 render glyphs on bitmaps and scan for black and white pixels.
1641 Vector fonts are not subject to this, and the call is as effective
1643 as "get_font_abc".
1644 get_font_languages
1646 Returns array of ISO 639 strings that can be displayed using glyphs
1647 available in the currently selected font.
1648 get_font_ranges
1650 Returns array of integer pairs denoting unicode indices of glyphs
1651 covered by the currently selected font. Each pair is the first and
1652 the last index of a contiguous range.
1653 Context used: font
1655 get_nearest_color COLOR
1657 Returns a nearest possible solid color in representation of the
1658 graphic device. Always returns same color if the device bit depth
1659 is equal or greater than 24.
1660 get_paint_state
1662 Returns paint state value on of ps:: constants - "ps::Disabled" if
1663 the object is in the disabled state, "ps::Enabled" for the enabled
1664 state, "ps::Information" for the information state.
1665 For brevity, mb::Disabled is equal to 0 so this allows for simple
1667 boolean testing whether one can get/set graphical properties on an
1668 object.
1669 See "Graphic context and canvas" for more.
1671 get_physical_palette
1673 Returns an array of integers in (R,G,B) format, where each color
1674 entry is in the 0 - 255 range.
1675 The physical palette array is non-empty only on paletted graphic
1677 devices, the true color devices return an empty array.
1678 The physical palette reflects the solid colors currently available
1680 to all programs in the system. The information is volatile if the
1681 system palette can change colors, since any other application may
1682 request to change the system colors at any moment.
1683 get_text_shape_width TEXT, [ FLAGS ]
1685 Runs shaping on TEXT character string with text direction either
1686 taken from "FLAGS & to::RTL" value, or from the or
1687 "$::application->textDirection". Returns the shaping result width
1688 as if it would be drawn using currently selected font.
1689 If "FLAGS & to::AddOverhangs" is set, the first character's
1691 absolute A value and the last character's absolute C value are
1692 added to the string if they are negative.
1693 get_text_width TEXT, ADD_OVERHANG = 0
1695 Returns TEXT string width if it would be drawn using currently
1696 selected font. TEXT is either a character string, or a
1697 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1698 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1699 If ADD_OVERHANG is 1, the first character's absolute A value and
1701 the last character's absolute C value are added to the string if
1702 they are negative.
1703 See more on ABC values at "Font ABC metrics".
1705 Context used: font
1707 get_text_box TEXT
1709 Returns TEXT string extensions if it would be drawn using currently
1710 selected font. TEXT is either a character string, or a
1711 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1712 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1713 The result is an anonymous array of 5 points ( 5 integer pairs in
1715 (X,Y) format). These 5 points are offsets for the following string
1716 extents, given the string is plotted at (0,0):
1717 1: start of string at ascent line ( top left )
1719 2: start of string at descent line ( bottom left )
1721 3: end of string at ascent line ( top right )
1723 4: end of string at descent line ( bottom right )
1725 5: concatenation point
1727 The concatenation point coordinates (XC,YC) are coordinated passed
1729 to consequent text_out() call so the conjoint string would plot as
1730 if it was a part of TEXT. Depending on the value of the
1731 "textOutBaseline" property, the concatenation point is located
1732 either on the baseline or on the descent line.
1733 Context used: font, textOutBaseline
1735 1 3 3 4
1737 ** ****
1738 * * *
1739 *** ***
1740 * * *
1741 **** **
1742 2 4 1 2
1743 has_alpha_layer
1745 Returns true if the drawable has an alpha channel. If the drawable
1746 is treated as a source, it means its alpha content will be
1747 respected when drawing on another surface. If the drawable is
1748 treated as a destination, it means that its alpha content will be
1749 updated if drawing on it uses alpha bits.
1750 See also: "can_draw_alpha".
1752 render_glyph INDEX, %OPTIONS
1754 Returns glyph representation as an outline. The outline is an
1755 integer array, formed as a set of plotting commands. Each commnds
1756 is a "ggo::" constant, followed by number of points, followed by
1757 the 2D point coordinates in 1/64 pixels.
1758 Options recognized:
1760 glyph BOOL
1762 If set, INDEX is treated as the glyph index rather than
1763 character index. Default is false.
1764 hints BOOL
1766 Is set, hinting is enabled. Default is true.
1767 unicode BOOL
1769 If set, INDEX is threated as a utf8 character index, otherwise
1770 a locale-specific index. Default is false.
1771 The "ggo::" commands are:
1773 ggo::Move - move point
1775 ggo::Line - plot line
1776 ggo::Conic - plot 2-degree spline
1777 ggo::Cubic - plot 3-degree spline
1778 render_polyline \@POLYLINE, %OPTIONS
1780 Performs calculations on POLYLINE, defined by OPTIONS. The
1781 following options are recognized:
1782 matrix A,B,C,D,U,V
1784 If supplied, performs matrix transformation on each polyline
1785 vertex:
1786 X' = AX + CY + U
1788 Y' = BX + DY + V
1789 and returns the new polyline
1791 box BOOLEAN
1793 If set, instead of polyline vertices, calculates the box
1794 extents of the polyline (either original or after the matrix
1795 transform, depending on whether "matrix" option was supplied or
1796 not), and returns 4 numerics for left,bottom,width,and height
1797 of the box enclosure.
1798 integer BOOLEAN
1800 By default the result is returned as a set of floating point
1801 numerics, however if integer results are needed, the results
1802 are transformed to integers using the int = float + ((float <
1803 0) ? -0.5 : 0.5) formula.
1804 render_spline \@VERTICES, %OPTIONS
1806 Renders B-spline curve from set of VERTICES to a polyline with
1807 given options.
1808 The method is internally used by "spline" and "fill_spline", and is
1810 provided for cases when these are insufficient. See description of
1811 options in spline.
1812 text_wrap TEXT, WIDTH, OPTIONS, [TAB_INDENT = 8, FROM = 0, LENGTH = -1,
1814 GLYPHS]
1815 Breaks TEXT string in chunks that must fit into WIDTH pixels wide
1816 box ( for WIDTH >= 0 ). TEXT is either character string, or a
1817 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1818 "Prima::Drawable::Glyphs->glyphs" strings of glyphs. In the glyph
1819 cases, some wrapping options are not applicable. It is possible to
1820 send both text as TEXT and its shaped representation as GLYPHS.
1821 The breaking algorithm and its result are governed by the OPTIONS
1823 integer value that is a combination of the following "tw::"
1824 constants:
1825 tw::CalcMnemonic
1827 Use 'hot key' semantics, when a character preceded by ~ has
1828 special meaning, f ex it gets underlined when used in menus.
1829 If this bit is set, the first tilde character used as an escape
1830 is not calculated, and never appears in the result apart from
1831 the escaped character.
1832 Not applicable in glyph wrapping.
1834 tw::CollapseTilde
1836 In addition to tw::CalcMnemonic, removes '~' character from the
1837 resulting chunks.
1838 Not applicable in glyph wrapping.
1840 tw::CalcTabs
1842 If set, calculates a tab ('\t') character as TAB_INDENT times
1843 space characters.
1844 Not applicable in glyph wrapping.
1846 tw::ExpandTabs
1848 If set, expands tab ('\t') character as TAB_INDENT times space
1849 characters.
1850 Not applicable in glyph wrapping.
1852 tw::BreakSingle
1854 Defines the method behavior when the text cannot be fit in
1855 WIDTH, does not affect anything else otherwise.
1856 If set, the method returns an empty array. If unset, it
1858 returns a text broken by minimum number of characters per
1859 chunk. In the latter case, the width of the resulting text
1860 blocks will exceed WIDTH.
1861 tw::NewLineBreak
1863 Forces creation of a new chunk after a newline character ('\n')
1864 is met. If UTF8 text is passed, unicode line break characters
1865 0x2028 and 0x2029 produce same effect as the newline character.
1866 Not applicable in glyph wrapping.
1868 tw::SpaceBreak
1870 Forces creation of a new chunk after a space character (' ') or
1871 a tab character ('\t') are met.
1872 Not applicable in glyph wrapping.
1874 tw::ReturnChunks
1876 Defines the result of the text_wrap() method.
1877 If set, the array consists of integer pairs, where each is a
1879 text offset within TEXT and its length.
1880 If unset, the resulting array consists of text chunks.
1882 tw::ReturnGlyphs
1884 If GLYPHS are set (only together with TEXT), this option
1885 becomes available to get the resulting chunks as sub-sets of
1886 GLYPHS.
1887 tw::ReturnLines
1889 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1890 In glyph wrapping means "tw::ReturnGlyphs".
1892 tw::WordBreak
1894 If unset, the TEXT breaks as soon as the chunk width exceeds
1895 WIDTH. If set, tries to keep words in TEXT so they do not
1896 appear in two chunks, e.g. breaks TEXT by words, not by
1897 characters.
1898 If Prima is compiled with the libthai library, and thai text is
1900 detected, Prima uses the library to detects the word
1901 boundaries, because the Thai language does not use spaces
1902 between words. This behavior can be disabled by running Prima
1903 with "--no-libthai".
1904 Not applicable in glyph wrapping.
1906 tw::ReturnFirstLineLength
1908 If set, "text_wrap" proceeds until the first line is wrapped,
1909 either by width or ( if specified ) by break characters.
1910 Returns the length of the resulting line. Used for efficiency
1911 as the inverted "get_text_width" function.
1912 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1914 the last scalar of the array is a special hash reference. The hash
1915 contains extra information regarding the 'hot key' underline
1916 position - it is assumed that '~' - escapement denotes the
1917 underlined character. The hash contains the following keys:
1918 tildeLine
1920 Chunk index that contains the escaped character. Set to undef
1921 if no ~ - escape was found; the rest of the information in the
1922 hash is not relevant in this case.
1923 tildeStart
1925 Horizontal offset of a beginning of the line that underlines
1926 the escaped character.
1927 tildeEnd
1929 Horizontal offset of an end of the line that underlines the
1930 escaped character.
1931 tildeChar
1933 The escaped character.
1934 Context used: font
1936 text_wrap_shape TEXT, WIDTH = -1, %OPTIONS
1938 Runs "text_shape" over results from "text_wrap" call, with "TEXT",
1939 "WIDTH", $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are
1940 used in "text_shape" call. Where "text_wrap" returns text
1941 substrings or positions, return glyphs objects or their positions
1942 instead.
1943 When called with "tw::CalcMnemonic" options, recalculates the tilde
1945 position so it adapts to the glyph positions returned.
1946 If $OPTIONS{kashida} is set, performs kashida justification on the
1948 last wrapped line, using optional $OPTIONS{min_kashida} value ( see
1949 "arabic_justify" in Prima::Drawable::Glyphs ).
1950 If $OPTIONS{letter} or $OPTIONS{word} is set, performs interspace
1952 justfication on all but the last wrapped line.
1953
1955 Dmitry Karasik, <dmitry@karasik.eu.org>.
1956
1958 Prima, Prima::Object, Prima::Image, Prima::Region,
1959 Prima::Drawable::Path, Prima::Drawable::Glyphs
1960perl v5.34.1 2022-04-20 pod::Prima::Drawable(3)