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 "::translate" property, that
699 translates the (0,0) point to the given offset. Calls to "::translate",
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 Custom line end styles
708 Prima uses its own plotting mechanism in Prima::Drawable::Path to
709 produce all primitive shapes, including lines. The way lines are
710 plotted is governed by properties "lineEnd", "lineJoin", "linePattern",
711 and "miterLimit". All of these properties are described below, however
712 "lineEnd" provides rich capabilities to generate custom line ends, and
713 this is what described in this section.
714 le:: namespace
716 There are 3 predefined "le::" integer constants
717 le::Flat
719 le::Square
720 le::Round
721 that are hardcoded in Prima, that are accepted by the "lineEnd"
723 property. These constants are somewhat limited in the way one can
724 operate them, for the sake of efficiency.
725 It is also possible to supply an array descriptor that defines a
727 set of primitives that plots a line cap, automatically transformed
728 with respect to the current line tangent and width. Details of the
729 descriptor syntax itself are given in the next section, while here
730 the set of non-hardcoded line end functions is listed, that is also
731 suitable for use in the "lineEnd" property.
732 le::Arrow
734 le::Cusp
735 le::InvCusp
736 le::Knob
737 le::Rect
738 le::RoundRect
739 le::Spearhead
740 le::Tail
741 These descriptors could be arbitrarily transformed (f ex scaled):
743 # all three lines produce the same effect
745 $x->lineEnd( le::scale( Arrow => 1.5 ) );
746 $x->lineEnd( le::transform( le::Arrow, [1.5,0,0,1.5,0,0] ) );
747 $x->lineEnd( le::transform( le::Arrow, Prima::matrix->new->scale(1.5) ) );
748 lineEnd accessors
750 The "lineEnd" property can accept up to 4 line end definitions,
751 depending on syntax. When Prima plots lines, depending on the
752 location of a line end, one of these 4 definitions is selected.
753 Each definition also has its own property - see "lineHead",
754 "lineTail", "arrowHead", and "arrowTail", or a index-based accessor
755 "lineEndIndex":
756 [ lineHeads and lineTails ]
758 \____ ____ ___ __ ____ ___\
759 / /
760 arrowTail arrowHead
761 Line end syntax
763 The syntax for custom line end style is:
764 syntax ::= array of pairs
766 pair ::= command, array of points
767 command ::= line or conic or cubic
768 points ::= set of x,y coordinate pairs (vertices)
769 and individual commands accept arbitrary number of vertices, but no
771 less than 1 for "line", 2 for "conic", and 3 for "cubic".
772 The commands are executed sequentially on a coordinate grid where
774 line width is assumed to be 1, the plotting starts from point at
775 (1,0), and ends at (-1,0).
776 For example, this is the definition of "le::Arrow":
778 [
780 conic => [1,0,2.5,0,2.5,-0.5],
781 line => [0,2.5],
782 conic => [-2.5,-0.5,-2.5,0,-1,0]
783 ]
784
786 Graphic context properties
787 alpha INTEGER
788 Sets alpha component of the brush, where 0 is fully transparent and
789 255 is fully opaque.
790 Note that premultiplication of "color" and "backColor" is not
792 necessary as it is done internally.
793 Default: 255
795 antialias BOOLEAN
797 Turns on and off antialiased drawing on all primitives, excluding
798 image, "pixel", and "bar_alpha" calls.
799 It will not be possible to turn the property on if the system does
801 not support it. Also, monochrome images won't support it as well.
802 See "Antialiasing and alpha".
804 arrowHead
806 Defines the style to paint line heads on starting or ending points
807 used to define a line or polygon. Is never used on closed shapes.
808 If "undef", the heads are painted with the same style as "lineHead"
809 Default value: "le::Round". Cannot be "undef".
811 arrowTail
813 Defines the style to paint line tails on starting or ending points
814 used to define a line or polygon. Is never used on closed shapes.
815 If "undef", the heads are painted with the same style as
816 "lineTail"; if it is also "undef", then the style of "lineHead" is
817 used.
818 Default value: "undef"
820 backColor COLOR
822 Sets background color to the graphic context. All drawing routines
823 that use non-solid or transparent fill or line patterns use this
824 property value.
825 color COLOR
827 Sets foreground color to the graphic context. All drawing routines
828 use this property value.
829 clipRect X1, Y1, X2, Y2
831 Selects the clipping rectangle corresponding to the physical canvas
832 origin. On get-call, returns the extent of the clipping area, if
833 it is not rectangular, or the clipping rectangle otherwise. The
834 code
835 $d-> clipRect( 1, 1, 2, 2);
837 $d-> bar( 0, 0, 1, 1);
838 thus affects only one pixel at (1,1).
840 Set-call discards the previous "::region" value.
842 Note: "::clipRect" can not be used while the object is in the
844 paint-disabled state, its context is neither recorded nor used as a
845 template ( see "Graphic context and canvas") -- except on images.
846 fillMode INTEGER
848 Affects filling style of complex polygonal shapes filled by
849 "fillpoly". If "fm::Winding", the filled shape contains no holes;
850 if "fm::Alternate", holes are present where the shape edges cross.
851 "fm::Overlay" flag can be combined with these to counter an
853 intrinsic defect of filled shaped both in Win32 and X11 that don't
854 exactly follow polygon vertices. When supplied, it overlays a
855 polygon over the filled shape, so that the latter falls exactly in
856 the boundaries defined by vertices. This is desirable when one
857 wants the shape to be defined exactly by polygon vertices, but is
858 not desirable when a shape has holes in it and is connected in a
859 way that the polygon overlay may leave visible connection edges
860 over them.
861 Default value: "fm::Winding|fm::Overlay"
863 fillPattern ( [ @PATTERN ] ) or ( fp::XXX ) or IMAGE
865 Selects 8x8 fill pattern that affects primitives that plot filled
866 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
867 fill_sector(), floodfill().
868 Accepts either a "fp::" constant or a reference to an array of 8
870 integers, or an image reference. In all cases, except where the
871 image is colored, treats 0s in the pattern as the currently
872 selected "backColor", and 1s as "color". When "rop2" is set to
873 "rop::NoOper", treats 0s as fully transparent pixels.
874 Additionally, in the render mode respects the "alpha" property.
875 Note: Drawing over monochome bitmap or image will not respect its
877 "rop" on Win32.
878 Depending on the parameters, treats the input as follows:
880 fp:: constant
882 There are some predefined patterns, that can be referred via
883 "fp::" constants:
884 fp::Empty
886 fp::Solid
887 fp::Line
888 fp::LtSlash
889 fp::Slash
890 fp::BkSlash
891 fp::LtBkSlash
892 fp::Hatch
893 fp::XHatch
894 fp::Interleave
895 fp::WideDot
896 fp::CloseDot
897 fp::SimpleDots
898 fp::Borland
899 fp::Parquet
900 ( the actual patterns are hardcoded in primguts.c ) The default
902 pattern is fp::Solid.
903 On a get-call, does not return the "fp::" value but the
905 corresponding array (see below). If a constant value is needed
906 to be recovered, use "fp::builtin" function that would return
907 the constant from the array. There is also two shortcut
908 functions, "fp::is_solid" and "fp::is_empty" that check if the
909 fill pattern is all-ones or all-zeros, correspondingly.
910 Array
912 Wants an 8-item array where each item is a byte value,
913 representing 8 bits of each line in a pattern. The first
914 integer is the topmost pattern line, and the bit 0x80 is the
915 leftmost pixel in the line.
916 An example below shows encoding of fp::Parquet pattern:
918 # 76543210
920 84218421 Hex
921 0 $ $ $ 51
923 1 $ $ 22
924 2 $ $ $ 15
925 3 $ $ 88
926 4 $ $ $ 45
927 5 $ $ 22
928 6 $ $ $ 54
929 7 $ $ 88
930 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
932 Monochrome image
934 Like the array above, wants an image consisting of 0s and 1s
935 where these would represent canvas' "backColor" and "color",
936 correspondinly, when rendered. In the same fashion, when "rop2"
937 is set to "rop::NoOper", zeros will be treated as transparent
938 pixels.
939 Color image
941 Ignores color, and backColor, and rop2. Just uses the tiles
942 and the current "alpha" value.
943 Icon
945 Ignores color, backColor, and rop2. Uses the alpha pixel values
946 from the icon's mask and the current "alpha" value.
947 fillPatternOffset X, Y
949 Origin coordinates for the "fillPattern". Image patterns origin
950 (0,0) is system-dependent.
951 font \%FONT
953 Manages font context. FONT hash acceptable values are "name",
954 "height", "size", "width", "style" and "pitch".
955 Synopsis:
957 $d-> font-> size( 10);
959 $d-> font-> name( 'Courier');
960 $d-> font-> set(
961 style => $x-> font-> style | fs::Bold,
962 width => 22
963 );
964 See "Fonts" for the detailed descriptions.
966 Applies to text_out(), get_text_width(), get_text_box(),
968 get_font_abc(), get_font_def(), render_glyph().
969 font_mapper
971 Returns a font mapper object that provides interface to fonts
972 collection used for substitution in polyfont shaping (see
973 "text_shape"). The fonts can be accessed there either by their font
974 hash (name and style only, currently), or the font's corresponding
975 index.
976 There are two font lists used in the substitution mechanism,
978 passive and active. The passive font list is initiated during the
979 toolkit start and is never changed. Each font there is addressed by
980 an index. When the actual search for a glyph is initiated, these
981 fonts are queried in the loop and are checked if they contain the
982 required glyphs. These queries are also cached, so that next time
983 lookups run much quicker. That way, an "active" font list is built,
984 and next substitutions use it before trying to look into the
985 passive list. Since the ordering of fonts is system based, and is
986 rather random, some fonts may not be a good or aesthetic
987 substitution. Therefore the mapper can assist in adding or
988 removing particular fonts to the active list, potentially allowing
989 an application to store and load user-driven selection of
990 substitution fonts.
991 The following methods are available on the font mapper object:
993 activate %FONT
995 Adds the FONT into the active substitution list if the font is
996 not disabled
997 get INDEX
999 Returns the font hash registered under INDEX
1000 count
1002 Returns number of all fonts in the collection
1003 index
1005 Returns what index is assigned to the currently used font, if
1006 any
1007 passivate %FONT
1009 Remove the font from the active substitution list
1010 is_active %FONT
1012 Returns whether the font is in the active substitution list or
1013 not
1014 enable %FONT
1016 Enables the font entry, the font will be considered for the
1017 polyfont lookup
1018 disable %FONT
1020 Disables the font entry, the font will not be considered for
1021 the polyfont lookup
1022 is_enabled %FONT
1024 Returns whether the font is enabled or not
1025 lineHead
1027 Defines the style to paint line heads in patterned lines only, on
1028 line segments that do not lie on line starting or ending points
1029 used to define a line or polygon.
1030 Default value: "undef"
1032 lineEnd VALUE
1034 Selects a line ending cap for plotting primitives. VALUE can be one
1035 of
1036 le::Arrow
1038 le::Cusp
1039 le::InvCusp
1040 le::Flat
1041 le::Knob
1042 le::Rect
1043 le::RoundRect
1044 le::Spearhead
1045 le::Square
1046 le::Round
1047 le::Tail
1048 constants, "undef", a custom line end description, or an array of
1050 four where each entry is one of the values above.
1051 The "undef" value is only accepted in the array syntax, and not for
1053 the index 0 ("lineHead"). The other indexes behave differently if
1054 are set to "undef" - see more in "lineTail", "arrowHead",
1055 "arrowTail", "lineEndIndex".
1056 "le::Round" is the default value.
1058 See also: "Custom line end styles".
1060 lineEndIndex INDEX, VALUE
1062 Same as "lineEnd" except only addresses a single line ending style.
1063 Allows VALUE to be "undef" for indexes greater than 0; depending on
1065 the index, the line style will be different ( see more in
1066 "lineTail", "arrowHead", "arrowTail" ).
1067 Allows special INDEX values or'ed with "le::Only", that behave
1069 differently if the line end style is "undef": while normal INDEX
1070 queries may return "undef", or possibly affect neighbor indexing
1071 (if these are, in turn, "undef"s), the calls with the "le::Only"
1072 bit set never return "undef" on get-calls, and never affect
1073 neighbor styles on set-calls.
1074 The following lookup rules are used if a line end style is undef:
1076 lei::LineTail - can never be undef
1078 lei::LineHead - if undef, same as lei::LineTail
1079 lei::ArrowTail - if undef, same as lei::LineTail
1080 lei::ArrowHead - if undef, same as lei::LineHead, and if it also is undef, then same as lei::LineTail
1081 lineJoin VALUE
1083 Selects a line joining style for polygons. VALUE can be one of
1084 lj::Round
1086 lj::Bevel
1087 lj::Miter
1088 constants. lj::Round is the default value.
1090 linePattern PATTERN
1092 Selects a line pattern for plotting primitives. PATTERN is either
1093 a predefined "lp::" constant, or a string where each even byte is a
1094 length of a dash, and each odd byte is a length of a gap.
1095 The predefined constants are:
1097 lp::Null # "" /* */
1099 lp::Solid # "\1" /* ___________ */
1100 lp::Dash # "\x9\3" /* __ __ __ __ */
1101 lp::LongDash # "\x16\6" /* _____ _____ */
1102 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
1103 lp::Dot # "\1\3" /* . . . . . . */
1104 lp::DotDot # "\1\1" /* ............ */
1105 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
1106 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
1107 Not all systems are capable of accepting user-defined line
1109 patterns, and in such situation the "lp::" constants are mapped to
1110 the system-defined patterns. In Win9x, for example, lp::DashDotDot
1111 is much different from its string definition.
1112 Default value is lp::Solid.
1114 lineTail
1116 Defines the style to paint line tails in patterned lines only, on
1117 line segments that do not lie on line starting or ending points
1118 used to define a line or polygon. If "undef", line tails are
1119 painted with the same style as "lineHead".
1120 Default value: "undef"
1122 lineWidth WIDTH
1124 Selects a line width for plotting primitives. If a VALUE is 0,
1125 then a cosmetic pen is used - the thinnest possible line that a
1126 device can plot. If a VALUE is greater than 0, then a geometric pen
1127 is used - the line width is set in device units. There is a subtle
1128 difference between VALUE 0 and 1 in a way the lines are joined.
1129 Default value is 0.
1131 miterLimit VALUE
1133 When path segments connect at a sharp angle, a miter join results
1134 in a spike that extends well beyond the connection point. The
1135 purpose of the miter limit is to cut off such spikes when they
1136 become objectionably long. At any given corner, the miter length is
1137 the distance from the point at which the inner edges of the stroke
1138 intersect to the point at which the outside edges of the strokes
1139 intersect-in other words, the diagonal length of the miter. This
1140 distance increases as the angle between the segments decreases. If
1141 the ratio of the miter length to the line width exceeds the miter
1142 limit parameter, stroke treats the corner with a bevel join instead
1143 of a miter join. The ratio of miter length to line width is
1144 directly related to the angle j between the segments by the
1145 formula:
1146 r = 1/sin(j/2)
1148 Default value is 10.0.
1150 Assuming line join is "lj::Miter" and line angle is 30 degrees:
1152 miter limit = 1.0: \__/
1154 miter limit = 9.0: \ /
1156 \/
1157 Note: does not work under X11.
1159 palette [ @PALETTE ]
1161 Selects solid colors in a system palette, as many as possible.
1162 PALETTE is an array of integer triplets, where each is R, G and B
1163 component. The call
1164 $d-> palette([128, 240, 240]);
1166 selects a gray-cyan color, for example.
1168 The return value from get-call is the content of the previous set-
1170 call, not the actual colors that were copied to the system palette.
1171 region OBJECT
1173 Selects a clipping region applied to all drawing and painting
1174 routines. On setting, the OBJECT is either undef, then the clip
1175 region is erased ( no clip ), or a Prima::Image object with a bit
1176 depth of 1. The bit mask of OBJECT is applied to the system
1177 clipping region. Or, it is a Prima::Region object. If the OBJECT
1178 is smaller than the drawable, its exterior is assigned to clipped
1179 area as well. Discards the previous "::clipRect" value; successive
1180 get-calls to "::clipRect" return the boundaries of the region.
1181 On getting, OBJECT is either undef or Prima::Region object.
1183 Note: "::region" can not be used while the object is in the paint-
1185 disabled state, its context is neither recorded nor used as a
1186 template ( see "Graphic context and canvas").
1187 resolution X, Y
1189 A read-only property. Returns horizontal and vertical device
1190 resolution in dpi.
1191 rop OPERATION
1193 Selects raster operation that applies to foreground color plotting
1194 routines.
1195 See also: "::rop2", "Raster operations".
1197 rop2 OPERATION
1199 Selects raster operation that applies to background color plotting
1200 routines.
1201 See also: "::rop", "Raster operations".
1203 textOpaque FLAG
1205 If FLAG is 1, then text_out() fills the text background area with
1206 "::backColor" property value before drawing the text. Default value
1207 is 0, when text_out() plots text only.
1208 See get_text_box().
1210 textOutBaseline FLAG
1212 If FLAG is 1, then text_out() plots text on a given Y coordinate
1213 correspondent to font baseline. If FLAG is 0, a Y coordinate is
1214 mapped to font descent line. Default is 0.
1215 translate X_OFFSET, Y_OFFSET
1217 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
1218 affect "::clipRect" and "::region". Not cumulative, so the call
1219 sequence
1220 $d-> translate( 5, 5);
1222 $d-> translate( 15, 15);
1223 is equivalent to
1225 $d-> translate( 15, 15);
1227 Note: "::translate" can not be used while the object is in the
1229 paint-disabled state, its context is neither recorded nor used as a
1230 template ( see "Graphic context and canvas").
1231 Other properties
1233 height HEIGHT
1234 Selects the height of a canvas.
1235 size WIDTH, HEIGHT
1237 Selects the extent of a canvas.
1238 width WIDTH
1240 Selects the width of a canvas.
1241 Graphic primitives methods
1243 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1244 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
1245 from START_ANGLE to END_ANGLE.
1246 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1248 miterLimit, rop, rop2
1249 bar X1, Y1, X2, Y2
1251 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
1252 Context used: color, backColor, fillPattern, fillPatternOffset,
1254 rop, rop2
1255 bar_alpha ALPHA <X1, Y1, X2, Y2>
1257 Fills rectangle in the alpha channel, filled with ALPHA value
1258 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
1259 parameters, in this case fills all canvas area.
1260 Has only effect on layered surfaces.
1262 bars @RECTS
1264 Draws a set of filled rectangles. RECTS is an array of integer
1265 quartets in format (X1,Y1,X2,Y2).
1266 Context used: color, backColor, fillPattern, fillPatternOffset,
1268 rop, rop2
1269 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1271 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes
1272 from START_ANGLE to END_ANGLE and connects its ends with the
1273 straight line.
1274 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1276 miterLimit, rop, rop2
1277 clear <X1, Y1, X2, Y2>
1279 Draws rectangle filled with pure background color within (X1,Y1) -
1280 (X2,Y2) extents. Can be called without parameters, in this case
1281 fills all canvas area.
1282 Context used: backColor, rop2
1284 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
1286 TAB_INDENT = 1 ]
1287 Draws several lines of text one under another with respect to align
1288 and break rules, specified in FLAGS and TAB_INDENT tab character
1289 expansion.
1290 "draw_text" is a convenience wrapper around "text_wrap" for drawing
1292 the wrapped text, and also provides the tilde ( ~ )- character
1293 underlining support.
1294 The FLAGS is a combination of the following constants:
1296 dt::Left - text is aligned to the left boundary
1298 dt::Right - text is aligned to the right boundary
1299 dt::Center - text is aligned horizontally in center
1300 dt::Top - text is aligned to the upper boundary
1301 dt::Bottom - text is aligned to the lower boundary
1302 dt::VCenter - text is aligned vertically in center
1303 dt::DrawMnemonic - tilde-escapement and underlining is used
1304 dt::DrawSingleChar - sets tw::BreakSingle option to
1305 Prima::Drawable::text_wrap call
1306 dt::NewLineBreak - sets tw::NewLineBreak option to
1307 Prima::Drawable::text_wrap call
1308 dt::SpaceBreak - sets tw::SpaceBreak option to
1309 Prima::Drawable::text_wrap call
1310 dt::WordBreak - sets tw::WordBreak option to
1311 Prima::Drawable::text_wrap call
1312 dt::ExpandTabs - performs tab character ( \t ) expansion
1313 dt::DrawPartial - draws the last line, if it is visible partially
1314 dt::UseExternalLeading - text lines positioned vertically with respect to
1315 the font external leading
1316 dt::UseClip - assign ::clipRect property to the boundary rectangle
1317 dt::QueryLinesDrawn - calculates and returns number of lines drawn
1318 ( contrary to dt::QueryHeight )
1319 dt::QueryHeight - if set, calculates and returns vertical extension
1320 of the lines drawn
1321 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
1322 dt::WordWrap - performs word wrapping by the width of the boundaries
1323 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
1324 dt::UseExternalLeading
1325 Context used: color, backColor, font, rop, textOpaque,
1327 textOutBaseline
1328 ellipse X, Y, DIAMETER_X, DIAMETER_Y
1330 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
1331 axes.
1332 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1334 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1336 Fills a chord outline with center in X, Y and DIAMETER_X and
1337 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see chord()).
1338 Context used: color, backColor, fillPattern, fillPatternOffset,
1340 rop, rop2
1341 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
1343 Fills an elliptical outline with center in X, Y and DIAMETER_X and
1344 DIAMETER_Y axes.
1345 Context used: color, backColor, fillPattern, fillPatternOffset,
1347 rop, rop2
1348 fillpoly \@POLYGON
1350 Fills a polygonal area defined by POLYGON set of points. POLYGON
1351 must present an array of integer pair in (X,Y) format. Example:
1352 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
1354 Context used: color, backColor, fillPattern, fillPatternOffset,
1356 rop, rop2, fillMode
1357 Returns success flag; if failed, $@ contains the error.
1359 See also: polyline().
1361 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1363 Fills a sector outline with center in X, Y and DIAMETER_X and
1364 DIAMETER_Y axes from START_ANGLE to END_ANGLE (see sector()).
1365 Context used: color, backColor, fillPattern, fillPatternOffset,
1367 rop, rop2
1368 fill_spline \@VERTICES, %OPTIONS
1370 Fills a polygonal area defined by the curve, projected by applying
1371 B-spline curve based on set of VERTICES. VERTICES must present an
1372 array of integer pair in (X,Y) format. Example:
1373 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1375 Context used: color, backColor, fillPattern, fillPatternOffset,
1377 rop, rop2
1378 Returns success flag; if failed, $@ contains the error.
1380 See also: spline, render_spline
1382 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1384 Fills an area of the canvas using the current fill context. The
1385 area is assumed to be bounded as specified by the SINGLEBORDER
1386 parameter. SINGLEBORDER can be 0 or 1.
1387 SINGLEBORDER = 0: The fill area is bounded by the color specified
1389 by the COLOR parameter.
1390 SINGLEBORDER = 1: The fill area is defined by the color that is
1392 specified by COLOR. Filling continues outward in all directions as
1393 long as the color is encountered. This style is useful for filling
1394 areas with multicolored boundaries.
1395 Context used: color, backColor, fillPattern, fillPatternOffset,
1397 rop, rop2
1398 line X1, Y1, X2, Y2
1400 Plots the straight line from (X1,Y1) to (X2,Y2).
1401 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1403 lines \@LINES
1405 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1406 lines() plots the straight line per quartet.
1407 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1409 Returns success flag; if failed, $@ contains the error.
1411 new_aa_surface
1413 Returns a new antialiasing surface object for AA emulation. See
1414 Prima::Drawable::Antialias for usage and details.
1415 new_gradient
1417 Returns a new gradient object. See Prima::Drawable::Gradient for
1418 usage and details.
1419 new_path
1421 Returns a new path object. See Prima::Drawable::Path for usage and
1422 details.
1423 pixel X, Y, <COLOR>
1425 ::pixel is a property - on set-call it changes the pixel value at
1426 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1427 pixel value at (X,Y).
1428 No context is used. May return "cl::Invalid" to signal an error or
1430 the out-of-boundaries condition.
1431 polyline \@POLYGON
1433 Draws a polygonal area defined by the POLYGON set of points.
1434 POLYGON must contain an array of integer pairs in (X,Y) format.
1435 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1437 lineEnd, miterLimit, rop, rop2
1438 Returns success flag; if failed, $@ contains the error.
1440 See also: fillpoly().
1442 put_image X, Y, OBJECT, [ ROP ]
1444 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1445 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1446 specified, it is used. Otherwise, value of "::rop" property is
1447 used.
1448 Returns success flag; if failed, $@ contains the error.
1450 Context used: rop; color and backColor for a monochrome
1452 DeviceBitmap
1453 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1455 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1456 Draws the OBJECT's source rectangle into the destination rectangle,
1457 stretching or compressing the source bits to fit the dimensions of
1458 the destination rectangle, if necessary. The source rectangle
1459 starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide and
1460 SRC_HEIGHT pixels tall. The destination rectangle starts at (X,Y),
1461 and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT) pixels
1462 tall. If DEST_WIDTH or DEST_HEIGHT are negative, a mirroring by
1463 respective axis is performed.
1464 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1466 No context is used, except color and backColor for a monochrome
1468 DeviceBitmap
1469 Returns success flag; if failed, $@ contains the error.
1471 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1473 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1474 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1475 specified, paints an inferior rectangle with it, otherwise the
1476 inferior rectangle is not touched.
1477 Context used: rop; color and backColor for a monochrome
1479 DeviceBitmap
1480 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1482 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1483 line width.
1484 No context is used.
1486 rectangle X1, Y1, X2, Y2
1488 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1489 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1491 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1493 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1494 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1495 two straight lines.
1496 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1498 miterLimit, rop, rop2
1499 spline \@VERTICES, %OPTIONS
1501 Draws a B-spline curve defined by set of VERTICES control points.
1502 VERTICES must present an array of integer pair in (X,Y) format.
1503 The following options are supported:
1505 closed BOOL = undef
1507 When not set, checks if the first and the last vertices point
1508 to the same point, and if yes, assumes a closed shape. Note - a
1509 closed shape rendering is implemented by adding degree minus
1510 two points to the set; this is important if "weight" or "knots"
1511 are specified.
1512 degree INTEGER = 2
1514 The B-spline degree. Default is 2 (quadratic). Number of points
1515 supplied must be at least degree plus one.
1516 knots \@INTEGERS
1518 Array of integers, number of points plus degree plus one, which
1519 makes the result a Bezier curve. By default, if the shape is
1520 opened (i.e. first and last points are different), is set to
1521 represent a clamped array, so that the first and last points of
1522 the final curve match the first and the last control points. If
1523 the shape is closed, set to represent an unclamped array, so
1524 that no control points lie directly on the curve.
1525 precision INTEGER = 24
1527 Defines number of steps to split the curve into. The value is
1528 multiplied to the number of points and the result is used as
1529 number of steps.
1530 weight \@INTEGERS = [ 1, 1, 1, ... ]
1532 Array of integers, one for each point supplied. Assigning these
1533 can be used to convert B-spline into a NURBS. By default set of
1534 ones.
1535 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1537 miterLimit, rop, rop2
1538 See also: fill_spline, render_spline.
1540 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1542 Draws the OBJECT on the destination rectangle, stretching or
1543 compressing the source bits to fit the dimensions of the
1544 destination rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT
1545 are negative, a mirroring is performed. The destination rectangle
1546 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1547 pixels tall.
1548 If ROP raster operation is specified, it is used. Otherwise, value
1550 of "::rop" property is used.
1551 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1553 Returns success flag; if failed, $@ contains the error.
1555 Context used: rop
1557 text_out TEXT, X, Y
1559 Draws TEXT string at (X,Y). TEXT is either character string, or a
1560 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1561 "Prima::Drawable::Glyphs->glyphs" strings of glyphs.
1562 Returns success flag; if failed, $@ contains the error.
1564 Context used: color, backColor, font, rop, textOpaque,
1566 textOutBaseline
1567 text_shape TEXT, %OPTIONS
1569 Converts TEXT into set of glyphs, returns either a
1570 "Prima::Drawable::Glyphs" object, or a 0 integer when shaping is
1571 not necessary, or "undef" as an error.
1572 When Prima is compiled with "libfribidi", the method runs unicode
1574 bidirectional algorithm on TEXT that properly positions embedded
1575 directional text (f.ex. a latin quote inside an arabic text), see
1576 Unicode Standard Annex #9 for the details. Without the library
1577 only does minimal RTL alignment.
1578 Glyphs returned are positioned according to RTL directions given in
1580 TEXT using characters from unicode block "General Punctuation
1581 U+2000 .. U+206F". Additionally, character ligation may be
1582 performed so that one or more characters are represented by one or
1583 more glyphs. Such syntactic units, clusters, are adopted in Prima
1584 where appropriate, instead of character units, for selection,
1585 navigation etc in f.ex. "Prima::InputLine" and "Prima::Edit".
1586 Helper routines that translate clusters, glyphs, and characters
1587 into each other are found in Prima::Drawable::Glyphs.
1588 Options recognized:
1590 advances BOOLEAN = false
1592 Shaping process may or may not fill integer array of advances
1593 and positions for each glyphs, depending on the implementation.
1594 The advances are needed to represent f.ex. combining graphemes,
1595 when TEXT consisting of two characters, "A" and combining grave
1596 accent U+300 should be drawn as a single À cluster but are
1597 represented by two glyphs "A" and "`". The grave glyph has its
1598 own advance for standalone usage, but in this case it should be
1599 ignored, and that is achieved by filling advance table where
1600 the "A" advance is the normal glyph advance, whereas the
1601 advance of the "`" is zero. Also, the position table
1602 additionally shifts glyph position by X and Y coordinates, when
1603 that is needed (f.ex. it might be positioned differently by the
1604 vertical axis on "a" and "A").
1605 Setting this options to "true" will force fill advance and
1607 positioning tables. These tables can be manipulated later, and
1608 are respected by "text_out" and "get_text_width".
1609 language STRING = undef
1611 When set, shaping process can take in the account the language
1612 of the text. F.ex. text "ae" might be shaped as a single glyph
1613 æ for the Latin language, but never for the English.
1614 level INTEGER = ts::Full
1616 Selects the shaping (i.e. text to glyph conversion) level, how
1617 the system should treat the input text and how deep the shaping
1618 should go.
1619 One of the following "ts::XXX" options:
1621 ts::Bytes
1623 Treats input text as non-unicode locale-specific
1624 codepoints, characters higher than 255 are treated as
1625 chr(255). Reordering never happens, font substitution
1626 never happens, kerning and ligation never happens; returns
1627 glyph indexes in a 1:1 mapping for each codepoint.
1628 ts::None
1630 Performs quick null shaping without mapping to the font
1631 glyphs, but only running bidirectional algorithm on the
1632 text. On the return, "glyphs", as well as eventual
1633 "advances" and "positions", are filled with zeros, but
1634 "indexes" are filled with the proper character offsets,
1635 effectively making it a visual-to-logical map since the
1636 number of glyphs will always be equal to the number of
1637 characters in TEXT, because ligation never happens here
1638 (except when TEXT contains unicode directional characters
1639 such as isolates etc - those are removed from the output).
1640 By default, advances and positions are not filled, but if
1642 the "advances" option is set, fills them with zeros.
1643 ts::Glyphs
1645 Applies the unicode bidi algorithm and maps the result onto
1646 font glyphs. Ligation and kerning doesn't happen here,
1647 it's basically same as "ts::None" but with the glyph
1648 mapping part.
1649 By default, advances and positions are not filled, but if
1651 "advances" option is set, fills the advances array with
1652 character glyph advances and the positions array with
1653 zeros.
1654 May fill the "fonts" array if the "polyfont" option is set.
1656 ts::Full
1658 Applies the unicode bidi algorithm, and runs the full
1659 shaping on the result. Ligation and kerning may occur.
1660 Always fills the advances and positions array; the
1661 "advances" option is ignored.
1662 If the system or the selected font does not support
1664 shaping, tries to ligate known arabic shapes using the
1665 fribidi library, if available. Also in this case does not
1666 return the advances and positions by default, but if
1667 "advances" option is set, fills the advances array with
1668 character glyph advances and the positions array with
1669 zeros.
1670 May fill the "fonts" array if the "polyfont" option is set.
1672 pitch INTEGER
1674 When the "polyfont" is set (default) and thus font substitution
1675 is desired, filters only fonts that match "pitch", either
1676 "fp::Variable" or "fp::Fixed". By default will be set to
1677 "fp::Fixed" if the current for is monospaced, but to
1678 "fp::Default" matching all fonts, otherwise.
1679 polyfont BOOLEAN = true
1681 If set, scans if the currently selected font supports all
1682 unicode points, and if not, selects a substitutions from a pre-
1683 populated list, taking into account the font pitch (see "pitch"
1684 above). In cases where the current font has not enough glyphs
1685 to shape all the requested unicode points, font substitution is
1686 performed, and the result contains an extra array "fonts" (see
1687 "fonts" in Prima::Drawable::Glyphs). When the current font has
1688 all needed glyphs, the fonts array is not created.
1689 The font list access is available through "font_mapper".
1691 Valid only with shaping levels "ts::Glyphs" and "ts::Full".
1693 reorder BOOLEAN = true
1695 When set, unicode bidi algorithm is used to reorder codepoints,
1696 and additionally RTL codepoints may be reversed (depending on
1697 direction context).
1698 When unset, no such reordering occurs, to emulate as much as
1700 possible a behavior that each text grapheme is being mapped to
1701 a glyph cluster exactly as it occurs in the input text, from
1702 left to right. Note that bidi reordering still may occur
1703 internally, since system shapers may reverse placement of RTL
1704 characters, so that the Prima reordering is needed to cancel
1705 this. In theory the caller shouldn't see the difference as
1706 these should cancel each other, but if Prima miscalculates the
1707 expected way the system shaper does the bidi processing, it
1708 might.
1709 A similar effect can be reached by prepending the text with
1711 U+202D (LEFT-TO-RIGHT OVERRIDE).
1712 rtl BOOLEAN
1714 If set to 1, default text direction is assumed as RTL, and as
1715 LTR if set to 0. If unset, the text direction is taken from
1716 "textDirection" in Prima::Application.
1717 skip_if_simple BOOLEAN = false
1719 When set, checks whether the shaping result is identical to the
1720 input, in a sense that a call to text_out(TEXT) and a call to
1721 text_shape_out(TEXT) produce identical results. Majority of
1722 english text will fall into that category, and when that indeed
1723 happens, returns integer value 0 instead of a glyph object.
1724 See also "text_shape_out", "get_text_shape_width",
1726 "text_wrap_shape".
1727 text_shape_out TEXT, X, Y[, RTL]
1729 Runs shaping on TEXT character string with the RTL flag (or
1730 "$::application->textDirection". Draws the resulting glyph string
1731 at (X,Y).
1732 Returns success flag; if failed, $@ contains the error.
1734 Context used: color, backColor, font, rop, textOpaque,
1736 textOutBaseline
1737 Methods
1739 begin_paint
1740 Enters the enabled ( active paint ) state, returns success flag; if
1741 failed, $@ contains the error. Once the object is in enabled
1742 state, painting and drawing methods can perform write operations on
1743 a canvas.
1744 See also: "end_paint", "begin_paint_info", "Graphic context and
1746 canvas"
1747 begin_paint_info
1749 Enters the information state, returns success flag; if failed, $@
1750 contains the error. The object information state is same as
1751 enabled state ( see "begin_paint"), except painting and drawing
1752 methods do not change the object canvas.
1753 See also: "end_paint_info", "begin_paint", "Graphic context and
1755 canvas"
1756 can_draw_alpha
1758 Returns whether using alpha bits operation on the drawable will
1759 have any effect or not. Note that the drawable may not necessarily
1760 have an alpha channel, for example a normal RGB image is capable to
1761 be painted on with alpha while not having any alpha on its own. On
1762 unix, all non-1 bit drawables return true if Prima was compiled
1763 with XRender support and if that extension is present on the X
1764 server. On windows, all non-1 bit drawables return true
1765 unconditionally.
1766 See also: "has_alpha_layer"
1768 end_paint
1770 Exits the enabled state and returns the object to a disabled state.
1771 See also: "begin_paint", "Graphic context and canvas"
1773 end_paint_info
1775 Exits the information state and returns the object to a disabled
1776 state.
1777 See also: "begin_paint_info", "Graphic context and canvas"
1779 font_match \%SOURCE, \%DEST, PICK = 1
1781 Performs merging of two font hashes, SOURCE and DEST. Returns the
1782 merge result. If PICK is true, matches the result with a system
1783 font repository.
1784 Called implicitly by "::font" on set-call, allowing the following
1786 example to work:
1787 $d-> font-> set( size => 10);
1789 $d-> font-> set( style => fs::Bold);
1790 In the example, the hash 'style => fs::Bold' does not overwrite the
1792 previous font context ( 'size => 10' ) but gets added to it ( by
1793 font_match()), providing the resulting font with both font
1794 properties set.
1795 fonts <FAMILY = "", ENCODING = "">
1797 Member of "Prima::Application" and "Prima::Printer", does not
1798 present in "Prima::Drawable".
1799 Returns an array of font metric hashes for a given font FAMILY and
1801 ENCODING. Every hash has full set of elements described in
1802 "Fonts".
1803 If called without parameters, returns an array of same hashes where
1805 each hash represents a member of font family from every system font
1806 set. It this special case, each font hash contains additional
1807 "encodings" entry, which points to an array of encodings available
1808 for the font.
1809 If called with FAMILY parameter set but no ENCODING is set,
1811 enumerates all combinations of fonts with all available encodings.
1812 If called with FAMILY set to an empty string, but ENCODING
1814 specified, returns only fonts that can be displayed with the
1815 encoding.
1816 Example:
1818 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1820 get_bpp
1822 Returns device color depth. 1 is for black-and-white monochrome, 24
1823 for true color, etc.
1824 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1826 Returns ABC font metrics for the given range, starting at
1827 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1828 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1829 responsible of representation of characters in 127-255 range. If
1830 0, the default, encoding-dependent characters are assumed. If 1,
1831 the U007F-U00FF glyphs from Latin-1 set are used.
1832 The result is an integer array reference, where every character
1834 glyph is referred by three integers, each triplet containing A, B
1835 and C values.
1836 For detailed explanation of ABC meaning, see "Font ABC metrics";
1838 Context used: font
1840 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1842 Same as "get_font_abc", but for vertical metrics. Is expensive on
1843 bitmap fonts, because to find out the correct values Prima has to
1844 render glyphs on bitmaps and scan for black and white pixels.
1845 Vector fonts are not subject to this, and the call is as effective
1847 as "get_font_abc".
1848 get_font_languages
1850 Returns array of ISO 639 strings that can be displayed using glyphs
1851 available in the currently selected font.
1852 get_font_ranges
1854 Returns array of integer pairs denoting unicode indices of glyphs
1855 covered by the currently selected font. Each pair is the first and
1856 the last index of a contiguous range.
1857 Context used: font
1859 get_nearest_color COLOR
1861 Returns a nearest possible solid color in representation of the
1862 graphic device. Always returns same color if the device bit depth
1863 is equal or greater than 24.
1864 get_paint_state
1866 Returns paint state value on of ps:: constants - "ps::Disabled" if
1867 the object is in the disabled state, "ps::Enabled" for the enabled
1868 state, "ps::Information" for the information state.
1869 For brevity, mb::Disabled is equal to 0 so this allows for simple
1871 boolean testing whether one can get/set graphical properties on an
1872 object.
1873 See "Graphic context and canvas" for more.
1875 get_physical_palette
1877 Returns an array of integers in (R,G,B) format, where each color
1878 entry is in the 0 - 255 range.
1879 The physical palette array is non-empty only on paletted graphic
1881 devices, the true color devices return an empty array.
1882 The physical palette reflects the solid colors currently available
1884 to all programs in the system. The information is volatile if the
1885 system palette can change colors, since any other application may
1886 request to change the system colors at any moment.
1887 get_text_shape_width TEXT, [ FLAGS ]
1889 Runs shaping on TEXT character string with text direction either
1890 taken from "FLAGS & to::RTL" value, or from the or
1891 "$::application->textDirection". Returns the shaping result width
1892 as if it would be drawn using currently selected font.
1893 If "FLAGS & to::AddOverhangs" is set, the first character's
1895 absolute A value and the last character's absolute C value are
1896 added to the string if they are negative.
1897 get_text_width TEXT, ADD_OVERHANG = 0
1899 Returns TEXT string width if it would be drawn using currently
1900 selected font. TEXT is either a character string, or a
1901 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1902 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1903 If ADD_OVERHANG is 1, the first character's absolute A value and
1905 the last character's absolute C value are added to the string if
1906 they are negative.
1907 See more on ABC values at "Font ABC metrics".
1909 Context used: font
1911 get_text_box TEXT
1913 Returns TEXT string extensions if it would be drawn using currently
1914 selected font. TEXT is either a character string, or a
1915 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1916 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1917 The result is an anonymous array of 5 points ( 5 integer pairs in
1919 (X,Y) format). These 5 points are offsets for the following string
1920 extents, given the string is plotted at (0,0):
1921 1: start of string at ascent line ( top left )
1923 2: start of string at descent line ( bottom left )
1925 3: end of string at ascent line ( top right )
1927 4: end of string at descent line ( bottom right )
1929 5: concatenation point
1931 The concatenation point coordinates (XC,YC) are coordinated passed
1933 to consequent text_out() call so the conjoint string would plot as
1934 if it was a part of TEXT. Depending on the value of the
1935 "textOutBaseline" property, the concatenation point is located
1936 either on the baseline or on the descent line.
1937 Context used: font, textOutBaseline
1939 1 3 3 4
1941 ** ****
1942 * * *
1943 *** ***
1944 * * *
1945 **** **
1946 2 4 1 2
1947 graphic_context %GC, $CALLBACK
1949 A shortcut method that saves the graphic context, applies changes
1950 in %GC, calls $CALLBACK, and finally restores the context. F ex:
1951 $self->graphic_context( fillPattern => fp::Solid, sub { $self-> bar(..) } );
1953 graphic_context_pop
1955 Restores the graphic context properties from the stack.
1956 graphic_context_push
1958 Saves the graphic context properties on the stack.
1959 has_alpha_layer
1961 Returns true if the drawable has an alpha channel. If the drawable
1962 is treated as a source, it means its alpha content will be
1963 respected when drawing on another surface. If the drawable is
1964 treated as a destination, it means that its alpha content will be
1965 updated if drawing on it uses alpha bits.
1966 See also: "can_draw_alpha".
1968 render_glyph INDEX, %OPTIONS
1970 Returns glyph representation as an outline. The outline is an
1971 integer array, formed as a set of plotting commands. Each command
1972 is a "ggo::" constant, followed by number of points, followed by
1973 the 2D point coordinates in 1/64 pixels.
1974 Options recognized:
1976 glyph BOOL
1978 If set, INDEX is treated as the glyph index rather than
1979 character index. Default is false.
1980 hints BOOL
1982 Is set, hinting is enabled. Default is true.
1983 unicode BOOL
1985 If set, INDEX is treated as a utf8 character index, otherwise a
1986 locale-specific index. Default is false.
1987 The "ggo::" commands are:
1989 ggo::Move - move point
1991 ggo::Line - plot line
1992 ggo::Conic - plot 2-degree spline
1993 ggo::Cubic - plot 3-degree spline
1994 render_pattern IMAGE|ICON|ARRAY|INDEX, %OPTIONS
1996 Takes a fill pattern represented by one of "fp::XXX" constant, an
1997 array of 8 bytes, or an image (or icon); same syntax as in
1998 "fillPattern".
1999 Uses %OPTIONS to generate a new rectangular pattern that can be
2001 used in "fillPattern" property. Since Prima does not provide an
2002 individual property that would govern specifically the matrix of a
2003 fill pattern, this method can be used to implement this
2004 functionality.
2005 Also respects "preserveType" property and if it is set, changes the
2007 resulting pattern image type back to the original type. In case
2008 where fillPattern is given by ARRAY or INDEX, always generates a
2009 "im::BW" image, so it can be used both in "rop2" transparent and
2010 opaque modes, like the original pattern.
2011 Options:
2013 color COLOR, alpha 0-255
2015 If "margin" is used, pre-fills target image with this color.
2016 "alpha" is used to pre-fill the target image's mask with this
2017 value, if the image is an icon.
2018 margin XY | [ X, Y ]
2020 Set margins in X and Y pixels before applying the
2021 transformation
2022 matrix MATRIX
2024 2D matrix to transform IMAGE
2025 render_polyline \@POLYLINE, %OPTIONS
2027 Performs calculations on POLYLINE, defined by OPTIONS. The
2028 following options are recognized:
2029 matrix A,B,C,D,U,V
2031 If supplied, performs matrix transformation on each polyline
2032 vertex:
2033 X' = AX + CY + U
2035 Y' = BX + DY + V
2036 and returns the new polyline
2038 box BOOLEAN
2040 If set, instead of polyline vertices, calculates the box
2041 extents of the polyline (either original or after the matrix
2042 transform, depending on whether "matrix" option was supplied or
2043 not), and returns 4 numerics for left,bottom,width,and height
2044 of the box enclosure.
2045 integer BOOLEAN
2047 By default the result is returned as a set of floating point
2048 numerics, however if integer results are needed, the results
2049 are transformed to integers using the int = float + ((float <
2050 0) ? -0.5 : 0.5) formula.
2051 path BOOLEAN
2053 If set, treats polyline as a path that will get applied
2054 "lineEnd", "lineJoin", "linePattern",and "miterLimit"
2055 properties (either from the object or from %OPTIONS) and
2056 returns a set of commands that would represent the final shape.
2057 The commands are: arc (6 arguments, same as the "arc"
2058 primitive), line with 1 argument, a polyline array (respects
2059 the "integer" option), and open with no arguments.
2060 See "widen" in Prima::Drawable::Path for usage.
2062 render_spline \@VERTICES, %OPTIONS
2064 Renders B-spline curve from set of VERTICES to a polyline with
2065 given options.
2066 The method is internally used by "spline" and "fill_spline", and is
2068 provided for cases when these are insufficient. See description of
2069 options in "spline".
2070 text_wrap TEXT, WIDTH, OPTIONS, [TAB_INDENT = 8, FROM = 0, LENGTH = -1,
2072 GLYPHS]
2073 Breaks TEXT string in chunks that must fit into WIDTH pixels wide
2074 box ( for WIDTH >= 0 ). TEXT is either character string, or a
2075 "Prima::Drawable::Glyphs" object returned from "text_shape", or
2076 "Prima::Drawable::Glyphs->glyphs" strings of glyphs. In the glyph
2077 cases, some wrapping options are not applicable. It is possible to
2078 send both text as TEXT and its shaped representation as GLYPHS.
2079 The breaking algorithm and its result are governed by the OPTIONS
2081 integer value that is a combination of the following "tw::"
2082 constants:
2083 tw::CalcMnemonic
2085 Use 'hot key' semantics, when a character preceded by ~ has
2086 special meaning, f ex it gets underlined when used in menus.
2087 If this bit is set, the first tilde character used as an escape
2088 is not calculated, and never appears in the result apart from
2089 the escaped character.
2090 Not applicable in glyph wrapping.
2092 tw::CollapseTilde
2094 In addition to tw::CalcMnemonic, removes '~' character from the
2095 resulting chunks.
2096 Not applicable in glyph wrapping.
2098 tw::CalcTabs
2100 If set, calculates a tab ('\t') character as TAB_INDENT times
2101 space characters.
2102 Not applicable in glyph wrapping.
2104 tw::ExpandTabs
2106 If set, expands tab ('\t') character as TAB_INDENT times space
2107 characters.
2108 Not applicable in glyph wrapping.
2110 tw::BreakSingle
2112 Defines the method behavior when the text cannot be fit in
2113 WIDTH, does not affect anything else otherwise.
2114 If set, the method returns an empty array. If unset, it
2116 returns a text broken by minimum number of characters per
2117 chunk. In the latter case, the width of the resulting text
2118 blocks will exceed WIDTH.
2119 tw::NewLineBreak
2121 Forces creation of a new chunk after a newline character ('\n')
2122 is met. If UTF8 text is passed, unicode line break characters
2123 0x2028 and 0x2029 produce same effect as the newline character.
2124 Not applicable in glyph wrapping.
2126 tw::SpaceBreak
2128 Forces creation of a new chunk after a space character (' ') or
2129 a tab character ('\t') are met.
2130 Not applicable in glyph wrapping.
2132 tw::ReturnChunks
2134 Defines the result of the text_wrap() method.
2135 If set, the array consists of integer pairs, where each is a
2137 text offset within TEXT and its length.
2138 If unset, the resulting array consists of text chunks.
2140 tw::ReturnGlyphs
2142 If GLYPHS are set (only together with TEXT), this option
2143 becomes available to get the resulting chunks as sub-sets of
2144 GLYPHS.
2145 tw::ReturnLines
2147 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
2148 In glyph wrapping means "tw::ReturnGlyphs".
2150 tw::WordBreak
2152 If unset, the TEXT breaks as soon as the chunk width exceeds
2153 WIDTH. If set, tries to keep words in TEXT so they do not
2154 appear in two chunks, e.g. breaks TEXT by words, not by
2155 characters.
2156 If Prima is compiled with the libthai library, and thai text is
2158 detected, Prima uses the library to detects the word
2159 boundaries, because the Thai language does not use spaces
2160 between words. This behavior can be disabled by running Prima
2161 with "--no-libthai".
2162 Not applicable in glyph wrapping.
2164 tw::ReturnFirstLineLength
2166 If set, "text_wrap" proceeds until the first line is wrapped,
2167 either by width or ( if specified ) by break characters.
2168 Returns the length of the resulting line. Used for efficiency
2169 as the inverted "get_text_width" function.
2170 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
2172 the last scalar of the array is a special hash reference. The hash
2173 contains extra information regarding the 'hot key' underline
2174 position - it is assumed that '~' - escapement denotes the
2175 underlined character. The hash contains the following keys:
2176 tildeLine
2178 Chunk index that contains the escaped character. Set to undef
2179 if no ~ - escape was found; the rest of the information in the
2180 hash is not relevant in this case.
2181 tildeStart
2183 Horizontal offset of a beginning of the line that underlines
2184 the escaped character.
2185 tildeEnd
2187 Horizontal offset of an end of the line that underlines the
2188 escaped character.
2189 tildeChar
2191 The escaped character.
2192 Context used: font
2194 text_wrap_shape TEXT, WIDTH = -1, %OPTIONS
2196 Runs "text_shape" over results from "text_wrap" call, with "TEXT",
2197 "WIDTH", $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are
2198 used in "text_shape" call. Where "text_wrap" returns text
2199 substrings or positions, return glyphs objects or their positions
2200 instead.
2201 When called with "tw::CalcMnemonic" options, recalculates the tilde
2203 position so it adapts to the glyph positions returned.
2204 If $OPTIONS{kashida} is set, performs kashida justification on the
2206 last wrapped line, using optional $OPTIONS{min_kashida} value ( see
2207 "arabic_justify" in Prima::Drawable::Glyphs ).
2208 If $OPTIONS{letter} or $OPTIONS{word} is set, performs interspace
2210 justification on all but the last wrapped line.
2211
2213 Dmitry Karasik, <dmitry@karasik.eu.org>.
2214
2216 Prima, Prima::Object, Prima::Image, Prima::Region,
2217 Prima::Drawable::Path, Prima::Drawable::Glyphs
2218perl v5.36.0 2023-03-20 pod::Prima::Drawable(3)