1pod::Prima::Drawable(3)User Contributed Perl Documentatiopnod::Prima::Drawable(3)
2
6 Prima::Drawable - 2-D graphic interface
7
9 if ( $object-> isa('Prima::Drawable')) {
10 $object-> begin_paint;
11 $object-> color( cl::Black);
12 $object-> line( 100, 100, 200, 200);
13 $object-> ellipse( 100, 100, 200, 200);
14 $object-> end_paint;
15 }
16
18 Prima::Drawable is a descendant of Prima::Component. It provides
19 access to the object-bound graphic context and canvas through its
20 methods and properties. The Prima::Drawable descendants Prima::Widget,
21 Prima::Image, Prima::DeviceBitmap and Prima::Printer are backed by
22 system-dependent routines that allow drawing and painting on the system
23 objects.
24
26 Prima::Drawable, as well as its ancestors Prima::Component and
27 Prima::Object, is never used directly, because Prima::Drawable class by
28 itself provides only the interface. It provides a three-state object
29 access - when drawing and painting is enabled, when these are disabled,
30 and the information acquisition state. By default, the object is
31 created in paint-disabled state. To switch to the enabled state,
32 begin_paint() method is used. Once in the enabled state, the object
33 drawing and painting methods apply to the object-bound canvas. To
34 return to the disabled state, end_paint() method is called. The
35 information state can be managed by using begin_paint_info() and
36 end_paint_info() methods pair. An object cannot be triggered from the
37 information state to the enabled state ( and vice versa ) directly.
38 These states differ on how do they apply to a graphic context and a
39 canvas.
40 Graphic context and canvas
42 The graphic context is the set of variables, that control how exactly
43 graphic primitives are rendered. The variable examples are color, font,
44 line width, etc. Another term used here is 'canvas' - the graphic area
45 of a certain extent, bound to the object, where the drawing and
46 painting methods are applied to.
47 In all three states a graphic context is allowed to be modified, but in
49 different ways. In the disabled state the graphic context values form
50 a template values; when a object enters the information or the enabled
51 state, the values are preserved, but when the object is back to the
52 disabled state, the graphic context is restored to the values last
53 assigned before entering new state. The code example below illustrates
54 the idea:
55 $d = Prima::Drawable-> create;
57 $d-> lineWidth( 5);
58 $d-> begin_paint_info;
59 # lineWidth is 5 here
60 $d-> lineWidth( 1);
61 # lineWidth is 1
62 $d-> end_paint_info;
63 # lineWidth is 5 again
64 ( Note: "::region", "::clipRect" and "::translate" properties are
66 exceptions. They can not be used in the disabled state; their values
67 are neither recorded nor used as a template).
68 That is, in disabled state any Drawable maintains only the graphic
70 context. To draw on a canvas, the object must enter the enabled state
71 by calling begin_paint(). This function can be unsuccessful, because
72 the object binds with system resources during this stage, and might
73 fail. Only after the enabled state is entered, the canvas is
74 accessible:
75 $d = Prima::Image-> create( width => 100, height => 100);
77 if ( $d-> begin_paint) {
78 $d-> color( cl::Black);
79 $d-> bar( 0, 0, $d-> size);
80 $d-> color( cl::White);
81 $d-> fill_ellipse( $d-> width / 2, $d-> height / 2, 30, 30);
82 $d-> end_paint;
83 } else {
84 die "can't draw on image:$@";
85 }
86 Different objects are mapped to different types of canvases -
88 Prima::Image canvas pertains its content after end_paint(),
89 Prima::Widget maps it to a screen area, which content is of more
90 transitory nature, etc.
91 The information state is as same as the enabled state, but the changes
93 to a canvas are not visible. Its sole purpose is to read, not to write
94 information. Because begin_paint() requires some amount of system
95 resources, there is a chance that a resource request can fail, for any
96 reason. The begin_paint_info() requires some resources as well, but
97 usually much less, and therefore if only information is desired, it is
98 usually faster and cheaper to obtain it inside the information state. A
99 notable example is get_text_width() method, that returns the length of
100 a text string in pixels. It works in both enabled and information
101 states, but code
102 $d = Prima::Image-> create( width => 10000, height => 10000);
104 $d-> begin_paint;
105 $x = $d-> get_text_width('A');
106 $d-> end_paint;
107 is much more 'expensive' than
109 $d = Prima::Image-> create( width => 10000, height => 10000);
111 $d-> begin_paint_info;
112 $x = $d-> get_text_width('A');
113 $d-> end_paint_info;
114 for the obvious reasons.
116 It must be noted that some information methods like get_text_width()
118 work even under the disabled state; the object is switched to the
119 information state implicitly if it is necessary.
120 Color space
122 Graphic context and canvas operations rely completely on a system
123 implementation. The internal canvas color representation is therefore
124 system-specific, and usually could not be described in standard
125 definitions. Often the only information available about color space is
126 its color depth.
127 Therefore, all color manipulations, including dithering and
129 antialiasing are subject to system implementation, and can not be
130 controlled from perl code. When a property is set in the object
131 disabled state, it is recorded verbatim; color properties are no
132 exception. After the object switched to the enabled state, a color
133 value is transformed to a system color representation, which might be
134 different from Prima's. For example, if a display color depth is 15
135 bits, 5 bits for every component, then white color value 0xffffff is
136 mapped to
137 11111000 11111000 11111000
139 --R----- --G----- --B-----
140 that equals to 0xf8f8f8, not 0xffffff ( See Prima::gp-problems for
142 inevident graphic issues discussion ).
143 The Prima::Drawable color format is RRGGBB, with each component
145 resolution of 8 bit, thus allowing 2^24 color combinations. If the
146 device color space depth is different, the color is truncated or
147 expanded automatically. In case the device color depth is small,
148 dithering algorithms might apply.
149 Note: not only color properties, but all graphic context properties
151 allow all possible values in the disabled state, which transformed into
152 system-allowed values in the enabled and the information states. This
153 feature can be used to test if a graphic device is capable of
154 performing certain operations ( for example, if it supports raster
155 operations - the printers usually do not ). Example:
156 $d-> begin_paint;
158 $d-> rop( rop::Or);
159 if ( $d-> rop != rop::Or) { # this assertion is always false without
160 ... # begin_paint/end_paint brackets
161 }
162 $d-> end_paint;
163 There are ( at least ) two color properties on each drawable -
165 "::color" and "::backColor". The values they operate are integers in
166 the discussed above RRGGBB format, however, the toolkit defines some
167 mnemonic color constants:
168 cl::Black
170 cl::Blue
171 cl::Green
172 cl::Cyan
173 cl::Red
174 cl::Magenta
175 cl::Brown
176 cl::LightGray
177 cl::DarkGray
178 cl::LightBlue
179 cl::LightGreen
180 cl::LightCyan
181 cl::LightRed
182 cl::LightMagenta
183 cl::Yellow
184 cl::White
185 cl::Gray
186 As stated before, it is not unlikely that if a device color depth is
188 small, the primitives plotted in particular colors will be drawn with
189 dithered or incorrect colors. This usually happens on paletted
190 displays, with 256 or less colors.
191 There exists two methods that facilitate the correct color
193 representation. The first way is to get as much information as
194 possible about the device. The methods get_nearest_color() and
195 get_physical_palette() provide possibility to avoid mixed colors
196 drawing by obtaining indirect information about solid colors, supported
197 by a device. Another method is to use "::palette" property. It works
198 by inserting the colors into the system palette, so if an application
199 knows the colors it needs beforehand, it can employ this method -
200 however this might result in system palette flash when a window focus
201 toggles.
202 Both of these methods are applicable both with drawing routines and
204 image output. An image desired to output with least distortion is
205 advised to export its palette to an output device, because images
206 usually are not subject to automatic dithering algorithms.
207 Prima::ImageViewer module employs this scheme.
208 Monochrome bitmaps
210 A special case of "put_image" is taken where the object to be drawn is
211 a monochrome DeviceBitmap object. This object doesn't possess the color
212 palette, and is by definition a bitmap, where there are only two values
213 present, 0s and 1s. When it is drawn, 0s are drawn with the color value
214 of the target canvas "color" property, and 1s with "backColor".
215 This means that the following code
217 $bitmap-> color(0);
219 $bitmap-> line(0,0,100,100);
220 $target-> color(cl::Green);
221 $target-> put_image(0,0,$bitmap);
222 produces a green line on $target.
224 When using monochrome bitmaps for logical operations, note that target
226 colors should not be explicit 0 and 0xffffff, nor "cl::Black" and
227 "cl::White", but "cl::Clear" and "cl::Set" instead. The reason is that
228 on paletted displays, system palette may not necessarily contain the
229 white color under palette index (2^ScreenDepth-1). "cl::Set" thus
230 signals that the value should be "all ones", no matter what color it
231 represents, because it will be used for logical operations.
232 Fonts
234 Prima maintains its own font naming convention, that usually does not
235 conform to system's. Since its goal is interoperability, it might be so
236 that some system fonts would not be accessible from within the toolkit.
237 Prima::Drawable provides property "::font", that accepts/returns a
239 hash, that represents the state of a font in the object-bound graphic
240 context. The font hash keys that are acceptable on set-call are:
241 name
243 The font name string. If there is no such font, a default font name
244 is used. To select default font, a 'Default' string can be passed
245 with the same result ( unless the system has a font named
246 'Default', of course).
247 height
249 An integer value from 1 to MAX_INT. Specifies the desired extent of
250 a font glyph between descent and ascent lines in pixels.
251 size
253 An integer value from 1 to MAX_INT. Specifies the desired extent of
254 a font glyph between descent and internal leading lines in points.
255 The relation between "size" and "height" is
256 height - internal_leading
258 size = --------------------------- * 72.27
259 resolution
260 That differs from some other system representations: Win32, for
262 example, rounds 72.27 constant to 72.
263 width
265 A integer value from 0 to MAX_INT. If greater than 0, specifies the
266 desired extent of a font glyph width in pixels. If 0, sets the
267 default ( designed ) width corresponding to the font size or
268 height.
269 style
271 A combination of "fs::" ( font style ) constants. The constants
272 hight
273 fs::Normal
275 fs::Bold
276 fs::Thin
277 fs::Italic
278 fs::Underlined
279 fs::StruckOut
280 fs::Outline
281 and can be OR-ed together to express the font style. fs::Normal
283 equals to 0 and usually never used. If some styles are not
284 supported by a system-dependent font subsystem, they are ignored.
285 pitch
287 One of three constants:
288 fp::Default
290 fp::Fixed
291 fp::Variable
292 "fp::Default" specifies no interest about font pitch selection.
294 "fp::Fixed" is set when a monospaced (all glyphs are of same width)
295 font is desired. "fp::Variable" pitch specifies a font with
296 different glyph widths. This key is of the highest priority; all
297 other keys may be altered for the consistency of the pitch key.
298 vector
300 On of three constants:
301 fv::Default
303 fv::Bitmap
304 fv::Outline
305 "fv::Default" specifies no interest about font type selection,
307 "fv::Bitmap" sets priority for bitmap fonts, "fv::Outline" for
308 vector fonts.
309 Additionally, font entries returned from "fonts" method may set
311 "vector" to "fv::ScalableBitmap", to distingush a bitmap font face
312 that comes with predefined bitmap sets from a scalable font.
313 direction
315 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
316 is pi, etc. If a font could not be rotated, it is usually
317 substituted to the one that can.
318 encoding
320 A string value, one of the strings returned by
321 "Prima::Application::font_encodings". Selects desired font
322 encoding; if empty, picks the first matched encoding, preferably
323 the locale set up by the user.
324 The encodings provided by different systems are different; in
326 addition, the only encodings are recognizable by the system, that
327 are represented by at least one font in the system.
328 Unix systems and the toolkit PostScript interface usually provide
330 the following encodings:
331 iso8859-1
333 iso8859-2
334 ... other iso8859 ...
335 fontspecific
336 Win32 returns the literal strings like
338 Western
340 Baltic
341 Cyrillic
342 Hebrew
343 Symbol
344 A hash that "::font" returns, is a tied hash, whose keys are also
346 available as separate properties. For example,
347 $x = $d-> font-> {style};
349 is equivalent to
351 $x = $d-> font-> style;
353 While the latter gives nothing but the arguable coding convenience, its
355 usage in set-call is much more usable:
356 $d-> font-> style( fs::Bold);
358 instead of
360 my %temp = %{$d-> font};
362 $temp{ style} = fs::Bold;
363 $d-> font( \%temp);
364 The properties of a font tied hash are also accessible through set()
366 call, like in Prima::Object:
367 $d-> font-> style( fs::Bold);
369 $d-> font-> width( 10);
370 is adequate to
372 $d-> font-> set(
374 style => fs::Bold,
375 width => 10,
376 );
377 When get-called, "::font" property returns a hash where more entries
379 than the described above can be found. These keys are read-only, their
380 values are discarded if passed to "::font" in a set-call.
381 In order to query the full list of fonts available to a graphic device,
383 a "::fonts" method is used. This method is not present in
384 Prima::Drawable namespace; it can be found in two built-in class
385 instances, "Prima::Application" and "Prima::Printer".
386 "Prima::Application::fonts" returns metrics for the fonts available to
388 a screen device, while "Prima::Printer::fonts" ( or its substitute
389 Prima::PS::Printer ) returns fonts for the printing device. The result
390 of this method is an array of font metrics, fully analogous to these
391 returned by "Prima::Drawable::font" method.
392 family
394 A string with font family name. The family is a secondary string
395 key, used for distinguishing between fonts with same name but of
396 different vendors ( for example, Adobe Courier and Microsoft
397 Courier).
398 vector
400 A boolean; true if the font is vector ( e.g. can be scaled with no
401 quality loss ), false otherwise. The false value does not show if
402 the font can be scaled at all - the behavior is system-dependent.
403 Win32 can scale all non-vector fonts; X11 only the fonts specified
404 as the scalable.
405 ascent
407 Number of pixels between a glyph baseline and descent line.
408 descent
410 Number of pixels between a glyph baseline and descent line.
411 internalLeading
413 Number of pixels between ascent and internal leading lines.
414 Negative if the ascent line is below the internal leading line.
415 externalLeading
417 Number of pixels between ascent and external leading lines.
418 Negative if the ascent line is above the external leading line.
419 ------------- external leading line
421 $ ------------- ascent line
423 $ $
424 ------------- internal leading line
425 $
426 $$$
427 $ $
428 $ $ $
429 $$$$$$$ $$$
430 $ $ $ $
431 $ $ $ $
432 $ $ $$$ ---- baseline
433 $
434 $
435 $
436 $$$$ ---- descent line
437 weight
439 A font designed weight. Can be one of
440 fw::UltraLight
442 fw::ExtraLight
443 fw::Light
444 fw::SemiLight
445 fw::Medium
446 fw::SemiBold
447 fw::Bold
448 fw::ExtraBold
449 fw::UltraBold
450 constants.
452 maximalWidth
454 Maximal extent of a glyph in pixels. Equals to width in monospaced
455 fonts.
456 xDeviceRes
458 Designed horizontal font resolution in dpi.
459 yDeviceRes
461 Designed vertical font resolution in dpi.
462 firstChar
464 Index of the first glyph present in a font.
465 lastChar
467 Index of the last glyph present in a font.
468 breakChar
470 Index of the default character used to divide words. In a typical
471 western language font it is 32, ASCII space character.
472 defaultChar
474 Index of a glyph that is drawn instead of nonexistent glyph if its
475 index is passed to the text drawing routines.
476 Font ABC metrics
478 Besides these characteristics, every font glyph has an ABC-metric, the
479 three integer values that describe horizontal extents of a glyph's
480 black part relative to the glyph extent:
481 . . . . . . . .
483 . . $$$. . . . .
484 . . $$. $ . . . .
485 . . $$. . . . $$ . .
486 . $$$$$$$$$$. . .$$$$$ . .
487 . . $$ . . . $ $$ . .
488 . . $$ . . . .$$$$$ . .
489 . . $$ . . . . $$ . .
490 . .$$ . . . . $$$ $$$. .
491 $$ .$$ . . . $ $$ .
492 .$$$ . . . .$$$$$$$$. .
493 . . . . . . . .
494 <A>. .<C> <A>. .<C>
495 .<-.--B--.->. . .<--B--->. .
496 A = -3 A = 3
498 B = 13 B = 10
499 C = -3 C = 3
500 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
502 in picture on the left. A and C values are positive, if a glyph
503 contains empty space in front or behind the neighbor glyphs, like in
504 picture on the right. As can be seen, B is the width of a glyph's
505 black part.
506 ABC metrics returned by the get_font_abc() method.
508 Corresponding vertical metrics, called in Prima "DEF" metrics, are
510 returned by the get_font_def() method.
511 Raster operations
513 A drawable has two raster operation properties: "::rop" and "::rop2".
514 These define how the graphic primitives are plotted. "::rop" deals with
515 the foreground color drawing, and "::rop2" with the background.
516 Universal ROPs
518 The toolkit defines the following operations:
520 rop::Blackness # = 0
522 rop::NotOr # = !(src | dest)
523 rop::NotSrcAnd # &= !src
524 rop::NotPut # = !src
525 rop::NotDestAnd # = !dest & src
526 rop::Invert # = !dest
527 rop::XorPut # ^= src
528 rop::NotAnd # = !(src & dest)
529 rop::AndPut # &= src
530 rop::NotXor # = !(src ^ dest)
531 rop::NotSrcXor # alias for rop::NotXor
532 rop::NotDestXor # alias for rop::NotXor
533 rop::NoOper # = dest
534 rop::NotSrcOr # |= !src
535 rop::CopyPut # = src
536 rop::NotDestOr # = !dest | src
537 rop::OrPut # |= src
538 rop::Whiteness # = 1
539 Usually, however, graphic devices support only a small part of the
541 above set, limiting "::rop" to the most important operations: Copy,
542 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
543 only Copy and NoOp.
544 The raster operations apply to all graphic primitives except SetPixel.
546 Note for layering: using layered images and device bitmaps with
548 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
549 "rop::SrcOver" raster operations on OS-provided surfaces.
550 Also, "rop::AlphaCopy" operation is available for accessing alpha bits
552 only. When used, the source image is treated as alpha mask, and
553 therefore it has to be grayscale. It can be used to apply the alpha
554 bits independently, without need to construct an Icon object.
555 Additional ROPs
557 Prima implements extra features for compositing on images outside the
559 begin_paint/end_paint brackets. It supports the following 12 Porter-
560 Duff operators and some selected Photoshop blend operators:
561 rop::Clear rop::Add
563 rop::Xor rop::Multiply
564 rop::SrcOver rop::Screen
565 rop::DstOver rop::Overlay
566 rop::SrcCopy rop::Darken
567 rop::DstCopy rop::Lighten
568 rop::SrcIn rop::ColorDodge
569 rop::DstIn rop::ColorBurn
570 rop::SrcOut rop::HardLight
571 rop::DstOut rop::SoftLight
572 rop::SrcAtop rop::Difference
573 rop::DstAtop rop::Exclusion
574 Transparency control
576 There is defined a set of constants to apply a constant source and
577 destination alpha to whe there is no alpha channel available:
578 rop::SrcAlpha
580 rop::SrcAlphaShift
581 rop::DstAlpha
582 rop::DstAlphaShift
583 Combine the rop constant using this formula:
585 $rop = rop::XXX |
587 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
588 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
589 Also, function "rop::blend($alpha)" creates a rop constant for
591 simple blending of two images by the following formula:
592 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
594 Its brother function "rop::alpha($rop, $src_alpha, $dst_alpha)" can
596 be used for drawing on image outside begin_paint/end_paint:
597 $image->rop( rop::alpha( rop::SrcOver, 128 ));
599 $image->ellipse( 5, 5, 5, 5 );
600 When used with icons, their source and/or destination alpha
602 channels are additionally multiplied with these values.
603 rop::Premultiply
605 When this bit is set, source pixels will be multiplied with alpha
606 before blending
607 Coordinates
609 The Prima toolkit employs a geometrical XY grid, where X ascends
610 rightwards and Y ascends upwards. There, the (0,0) location is the
611 bottom-left pixel of a canvas.
612 All graphic primitives use inclusive-inclusive boundaries. For
614 example,
615 $d-> bar( 0, 0, 1, 1);
617 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
619 The coordinate origin can be shifted using "::translate" property, that
621 translates the (0,0) point to the given offset. Calls to "::translate",
622 "::clipRect" and "::region" always use the 'physical' (0,0) point,
623 whereas the plotting methods use the transformation result, the
624 'logical' (0,0) point.
625 As noted before, these three properties can not be used in when an
627 object is in its disabled state.
628
630 Graphic context properties
631 backColor COLOR
632 Reflects background color in the graphic context. All drawing
633 routines that use non-solid or transparent fill or line patterns
634 use this property value.
635 color COLOR
637 Reflects foreground color in the graphic context. All drawing
638 routines use this property value.
639 clipRect X1, Y1, X2, Y2
641 Selects the clipping rectangle corresponding to the physical canvas
642 origin. On get-call, returns the extent of the clipping area, if
643 it is not rectangular, or the clipping rectangle otherwise. The
644 code
645 $d-> clipRect( 1, 1, 2, 2);
647 $d-> bar( 0, 0, 1, 1);
648 thus affects only one pixel at (1,1).
650 Set-call discards the previous "::region" value.
652 Note: "::clipRect" can not be used while the object is in the
654 paint-disabled state, its context is neither recorded nor used as a
655 template ( see "Graphic context and canvas").
656 fillMode INTEGER
658 Affects filling style of complex polygonal shapes filled by
659 "fillpoly". If "fm::Winding", the filled shape contains no holes;
660 if "fm::EvenOdd", holes are present where the shape edges cross.
661 "fm::Overlay" flag can be combined with these to counter an
663 intrinsic defect of filled shaped both in Win32 and X11 that don't
664 exactly follow polygon vertices. When supplied, it overlays a
665 polygon over the filled shape, so that the latter falls exactly in
666 the boundaries defined by vertices. This is desirable when one
667 wants to follow polygon vertices, but is not desirable when a shape
668 has holes in it connected in a way that the polygon overlay may
669 leave connection edges over them.
670 Default value: "fm::Winding|fm::Overlay"
672 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
674 Selects 8x8 fill pattern that affects primitives that plot filled
675 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
676 fill_sector(), floodfill().
677 Accepts either a "fp::" constant or a reference to an array of 8
679 integers, each representing 8 bits of each line in a pattern, where
680 the first integer is the topmost pattern line, and the bit 0x80 is
681 the leftmost pixel in the line.
682 There are some predefined patterns, that can be referred via "fp::"
684 constants:
685 fp::Empty
687 fp::Solid
688 fp::Line
689 fp::LtSlash
690 fp::Slash
691 fp::BkSlash
692 fp::LtBkSlash
693 fp::Hatch
694 fp::XHatch
695 fp::Interleave
696 fp::WideDot
697 fp::CloseDot
698 fp::SimpleDots
699 fp::Borland
700 fp::Parquet
701 ( the actual patterns are hardcoded in primguts.c ) The default
703 pattern is fp::Solid.
704 An example below shows encoding of fp::Parquet pattern:
706 # 76543210
708 84218421 Hex
709 0 $ $ $ 51
711 1 $ $ 22
712 2 $ $ $ 15
713 3 $ $ 88
714 4 $ $ $ 45
715 5 $ $ 22
716 6 $ $ $ 54
717 7 $ $ 88
718 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
720 On a get-call always returns an array, never a "fp::" constant.
722 fillPatternOffset X, Y
724 Origin coordinates for the "fillPattern", from 0 to 7.
725 font \%FONT
727 Manages font context. FONT hash acceptable values are "name",
728 "height", "size", "width", "style" and "pitch".
729 Synopsis:
731 $d-> font-> size( 10);
733 $d-> font-> name( 'Courier');
734 $d-> font-> set(
735 style => $x-> font-> style | fs::Bold,
736 width => 22
737 );
738 See "Fonts" for the detailed descriptions.
740 Applies to text_out(), get_text_width(), get_text_box(),
742 get_font_abc(), get_font_def().
743 fontMapperPalette INDEX, [\%FONT | COMMAND]
745 A pseudo-property that manages access to a set of fonts used for
746 substitution in polyfont shaping (see "text_shape"). INDEX is the
747 same font index used in "fonts" array returned from "text_shape",
748 if polyfont was used (where 0 is the current font).
749 There are two font lists used in the substituion mechanism, passive
751 and active. The passive font list is initiated during the toolkit
752 start and is not changed. Each font there is addressed by "INDEX".
753 When the actual search for a glyph is initiated, these fonts are
754 queried in the loop and are checked whether they do contain
755 required glyphs. These queries are cached, so that next time
756 lookups run much quicker. That way, an "active" font list is built,
757 and next substitutions use it before trying to look into the
758 passive list. Since font order is system based, and is rather
759 random, some fonts may not be a good or aesthetic substition.
760 Therefore "fontMapperPallette" can assist in adding or removing
761 particular fonts to the active list, potentially allowing an
762 application to store and load a user-driven selection of
763 substitution fonts.
764 "fontMapperPallette" is a pseudo-property, such that it is not
766 symmetric as real properties are; its call formats are several and
767 not orthogonal to each other neither in syntax nor functionality.
768 Therefore these may change in future.
769 As a getter, the property returns the following depending on INDEX:
771 If it is -1, returns how many fonts are in the passive list. If 0,
772 which means the current font return either the non-index of the
773 current font if the same font is found in the palette, and 0
774 otherwise. If greater than zero, returns the substitution FONT
775 record from the passive list.
776 As a setter, manages the active list, and uses COMMAND integer as a
778 second argument. If COMMAND is 0, removes the INDEXth font from
779 the active list, and if 1, marks it for immediate scanning and
780 adding to the active list. The font is added in the end of the
781 list, after the existing active entries.
782 lineEnd VALUE
784 Selects a line ending cap for plotting primitives. VALUE can be one
785 of
786 le::Flat
788 le::Square
789 le::Round
790 constants. le::Round is the default value.
792 lineJoin VALUE
794 Selects a line joining style for polygons. VALUE can be one of
795 lj::Round
797 lj::Bevel
798 lj::Miter
799 constants. lj::Round is the default value.
801 linePattern PATTERN
803 Selects a line pattern for plotting primitives. PATTERN is either
804 a predefined "lp::" constant, or a string where each even byte is a
805 length of a dash, and each odd byte is a length of a gap.
806 The predefined constants are:
808 lp::Null # "" /* */
810 lp::Solid # "\1" /* ___________ */
811 lp::Dash # "\x9\3" /* __ __ __ __ */
812 lp::LongDash # "\x16\6" /* _____ _____ */
813 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
814 lp::Dot # "\1\3" /* . . . . . . */
815 lp::DotDot # "\1\1" /* ............ */
816 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
817 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
818 Not all systems are capable of accepting user-defined line
820 patterns, and in such situation the "lp::" constants are mapped to
821 the system-defined patterns. In Win9x, for example, lp::DashDotDot
822 is much different from its string definition therefore.
823 Default value is lp::Solid.
825 lineWidth WIDTH
827 Selects a line width for plotting primitives. If a VALUE is 0,
828 then a 'cosmetic' pen is used - the thinnest possible line that a
829 device can plot. If a VALUE is greater than 0, then a 'geometric'
830 pen is used - the line width is set in device units. There is a
831 subtle difference between VALUE 0 and 1 in a way the lines are
832 joined.
833 Default value is 0.
835 miterLimit VALUE
837 When path segments connect at a sharp angle, a miter join results
838 in a spike that extends well beyond the connection point. The
839 purpose of the miter limit is to cut off such spikes when they
840 become objectionably long. At any given corner, the miter length is
841 the distance from the point at which the inner edges of the stroke
842 intersect to the point at which the outside edges of the strokes
843 intersect-in other words, the diagonal length of the miter. This
844 distance increases as the angle between the segments decreases. If
845 the ratio of the miter length to the line width exceeds the miter
846 limit parameter, stroke treats the corner with a bevel join instead
847 of a miter join. The ratio of miter length to line width is
848 directly related to the angle j between the segments by the
849 formula:
850 r = 1/sin(j/2)
852 Default value is 10.0.
854 Asssuming line join is "lj::Miter" and line angle is 30 degrees:
856 miter limit = 1.0: \__/
858 miter limit = 9.0: \ /
860 \/
861 Note: does not work under X11.
863 palette [ @PALETTE ]
865 Selects solid colors in a system palette, as many as possible.
866 PALETTE is an array of integer triplets, where each is R, G and B
867 component. The call
868 $d-> palette([128, 240, 240]);
870 selects a gray-cyan color, for example.
872 The return value from get-call is the content of the previous set-
874 call, not the actual colors that were copied to the system palette.
875 region OBJECT
877 Selects a clipping region applied to all drawing and painting
878 routines. On setting, the OBJECT is either undef, then the clip
879 region is erased ( no clip ), or a Prima::Image object with a bit
880 depth of 1. The bit mask of OBJECT is applied to the system
881 clipping region. Or, it is a Prima::Region object. If the OBJECT
882 is smaller than the drawable, its exterior is assigned to clipped
883 area as well. Discards the previous "::clipRect" value; successive
884 get-calls to "::clipRect" return the boundaries of the region.
885 On getting, OBJECT is either undef or Prima::Region object.
887 Note: "::region" can not be used while the object is in the paint-
889 disabled state, its context is neither recorded nor used as a
890 template ( see "Graphic context and canvas").
891 resolution X, Y
893 A read-only property. Returns horizontal and vertical device
894 resolution in dpi.
895 rop OPERATION
897 Selects raster operation that applies to foreground color plotting
898 routines.
899 See also: "::rop2", "Raster operations".
901 rop2 OPERATION
903 Selects raster operation that applies to background color plotting
904 routines.
905 See also: "::rop", "Raster operations".
907 textOpaque FLAG
909 If FLAG is 1, then text_out() fills the text background area with
910 "::backColor" property value before drawing the text. Default value
911 is 0, when text_out() plots text only.
912 See get_text_box().
914 textOutBaseline FLAG
916 If FLAG is 1, then text_out() plots text on a given Y coordinate
917 correspondent to font baseline. If FLAG is 0, a Y coordinate is
918 mapped to font descent line. Default is 0.
919 translate X_OFFSET, Y_OFFSET
921 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
922 affect "::clipRect" and "::region". Not cumulative, so the call
923 sequence
924 $d-> translate( 5, 5);
926 $d-> translate( 15, 15);
927 is equivalent to
929 $d-> translate( 15, 15);
931 Note: "::translate" can not be used while the object is in the
933 paint-disabled state, its context is neither recorded nor used as a
934 template ( see "Graphic context and canvas").
935 Other properties
937 height HEIGHT
938 Selects the height of a canvas.
939 size WIDTH, HEIGHT
941 Selects the extent of a canvas.
942 width WIDTH
944 Selects the width of a canvas.
945 Graphic primitives methods
947 alpha ALPHA <X1, Y1, X2, Y2>
948 Fills rectangle in the alpha channel, filled with ALPHA value
949 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
950 parameters, in this case fills all canvas area.
951 Has only effect on layered surfaces.
953 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
955 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
956 from START_ANGLE to END_ANGLE.
957 Context used: color, backColor, lineEnd, linePattern, lineWidth,
959 miterLimit, rop, rop2
960 bar X1, Y1, X2, Y2
962 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
963 Context used: color, backColor, fillPattern, fillPatternOffset,
965 rop, rop2
966 bars @RECTS
968 Draws a set of filled rectangles. RECTS is an array of integer
969 quartets in format (X1,Y1,X2,Y2).
970 Context used: color, backColor, fillPattern, fillPatternOffset,
972 rop, rop2
973 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
975 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
976 from START_ANGLE to END_ANGLE and connects its ends with a straight
977 line.
978 Context used: color, backColor, lineEnd, linePattern, lineWidth,
980 miterLimit, rop, rop2
981 clear <X1, Y1, X2, Y2>
983 Draws rectangle filled with pure background color within (X1,Y1) -
984 (X2,Y2) extents. Can be called without parameters, in this case
985 fills all canvas area.
986 Context used: backColor, rop2
988 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
990 TAB_INDENT = 1 ]
991 Draws several lines of text one under another with respect to align
992 and break rules, specified in FLAGS and TAB_INDENT tab character
993 expansion.
994 "draw_text" is a convenience wrapper around "text_wrap" for drawing
996 the wrapped text, and also provides the tilde ( ~ )- character
997 underlining support.
998 The FLAGS is a combination of the following constants:
1000 dt::Left - text is aligned to the left boundary
1002 dt::Right - text is aligned to the right boundary
1003 dt::Center - text is aligned horizontally in center
1004 dt::Top - text is aligned to the upper boundary
1005 dt::Bottom - text is aligned to the lower boundary
1006 dt::VCenter - text is aligned vertically in center
1007 dt::DrawMnemonic - tilde-escapement and underlining is used
1008 dt::DrawSingleChar - sets tw::BreakSingle option to
1009 Prima::Drawable::text_wrap call
1010 dt::NewLineBreak - sets tw::NewLineBreak option to
1011 Prima::Drawable::text_wrap call
1012 dt::SpaceBreak - sets tw::SpaceBreak option to
1013 Prima::Drawable::text_wrap call
1014 dt::WordBreak - sets tw::WordBreak option to
1015 Prima::Drawable::text_wrap call
1016 dt::ExpandTabs - performs tab character ( \t ) expansion
1017 dt::DrawPartial - draws the last line, if it is visible partially
1018 dt::UseExternalLeading - text lines positioned vertically with respect to
1019 the font external leading
1020 dt::UseClip - assign ::clipRect property to the boundary rectangle
1021 dt::QueryLinesDrawn - calculates and returns number of lines drawn
1022 ( contrary to dt::QueryHeight )
1023 dt::QueryHeight - if set, calculates and returns vertical extension
1024 of the lines drawn
1025 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
1026 dt::WordWrap - performs word wrapping by the width of the boundaries
1027 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
1028 dt::UseExternalLeading
1029 Context used: color, backColor, font, rop, textOpaque,
1031 textOutBaseline
1032 ellipse X, Y, DIAMETER_X, DIAMETER_Y
1034 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
1035 axis.
1036 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1038 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1040 Fills a chord outline with center in X, Y and DIAMETER_X and
1041 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see chord()).
1042 Context used: color, backColor, fillPattern, fillPatternOffset,
1044 rop, rop2
1045 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
1047 Fills an elliptical outline with center in X, Y and DIAMETER_X and
1048 DIAMETER_Y axis.
1049 Context used: color, backColor, fillPattern, fillPatternOffset,
1051 rop, rop2
1052 fillpoly \@POLYGON
1054 Fills a polygonal area defined by POLYGON set of points. POLYGON
1055 must present an array of integer pair in (X,Y) format. Example:
1056 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
1058 Context used: color, backColor, fillPattern, fillPatternOffset,
1060 rop, rop2, fillMode
1061 Returns success flag; if failed, $@ contains the error.
1063 See also: polyline().
1065 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1067 Fills a sector outline with center in X, Y and DIAMETER_X and
1068 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see sector()).
1069 Context used: color, backColor, fillPattern, fillPatternOffset,
1071 rop, rop2
1072 fill_spline \@VERTICES, %OPTIONS
1074 Fills a polygonal area defined by a curve, projected by applying
1075 B-spline curve based on set of VERTICES. VERTICES must present an
1076 array of integer pair in (X,Y) format. Example:
1077 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1079 Context used: color, backColor, fillPattern, fillPatternOffset,
1081 rop, rop2
1082 Returns success flag; if failed, $@ contains the error.
1084 See also: spline, render_spline
1086 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1088 Fills an area of the canvas in current fill context. The area is
1089 assumed to be bounded as specified by the SINGLEBORDER parameter.
1090 SINGLEBORDER can be 0 or 1.
1091 SINGLEBORDER = 0: The fill area is bounded by the color specified
1093 by the COLOR parameter.
1094 SINGLEBORDER = 1: The fill area is defined by the color that is
1096 specified by COLOR. Filling continues outward in all directions as
1097 long as the color is encountered. This style is useful for filling
1098 areas with multicolored boundaries.
1099 Context used: color, backColor, fillPattern, fillPatternOffset,
1101 rop, rop2
1102 line X1, Y1, X2, Y2
1104 Plots a straight line from (X1,Y1) to (X2,Y2).
1105 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1107 lines \@LINES
1109 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1110 lines() plots a straight line per quartet.
1111 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1113 Returns success flag; if failed, $@ contains the error.
1115 new_gradient
1117 Returns a new gradient object. See Prima::Drawable::Gradient for
1118 usage and details.
1119 new_path
1121 Returns a new path object. See Prima::Drawable::Path for usage and
1122 details.
1123 pixel X, Y, <COLOR>
1125 ::pixel is a property - on set-call it changes the pixel value at
1126 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1127 pixel value at (X,Y).
1128 No context is used.
1130 polyline \@POLYGON
1132 Draws a polygonal area defined by POLYGON set of points. POLYGON
1133 must present an array of integer pair in (X,Y) format.
1134 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1136 lineEnd, miterLimit, rop, rop2
1137 Returns success flag; if failed, $@ contains the error.
1139 See also: fillpoly().
1141 put_image X, Y, OBJECT, [ ROP ]
1143 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1144 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1145 specified, it is used. Otherwise, value of "::rop" property is
1146 used.
1147 Returns success flag; if failed, $@ contains the error.
1149 Context used: rop; color and backColor for a monochrome
1151 DeviceBitmap
1152 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1154 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1155 Copies a OBJECT from a source rectangle into a destination
1156 rectangle, stretching or compressing the OBJECT to fit the
1157 dimensions of the destination rectangle, if necessary. The source
1158 rectangle starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide
1159 and SRC_HEIGHT pixels tall. The destination rectangle starts at
1160 (X,Y), and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT)
1161 pixels tall. If DEST_WIDTH or DEST_HEIGHT are negative, a
1162 mirroring by respective axis is performed.
1163 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1165 No context is used, except color and backColor for a monochrome
1167 DeviceBitmap
1168 Returns success flag; if failed, $@ contains the error.
1170 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1172 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1173 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1174 specified, paints an inferior rectangle with it, otherwise the
1175 inferior rectangle is not touched.
1176 Context used: rop; color and backColor for a monochrome
1178 DeviceBitmap
1179 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1181 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1182 line width.
1183 No context is used.
1185 rectangle X1, Y1, X2, Y2
1187 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1188 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1190 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1192 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1193 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1194 two straight lines.
1195 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1197 miterLimit, rop, rop2
1198 spline \@VERTICES, %OPTIONS
1200 Draws a B-spline curve defined by set of VERTICES control points.
1201 VERTICES must present an array of integer pair in (X,Y) format.
1202 The following options are supported:
1204 closed BOOL = undef
1206 When not set, checks if the first and the last vertices point
1207 to the same point, and if yes, assumes a closed shape. Note - a
1208 closed shape rendering is implemented by adding degree minus
1209 two points to the set; this is important if "weight" or "knots"
1210 are specificed.
1211 degree INTEGER = 2
1213 The B-spline degree. Default is 2 (quadratic). Number of points
1214 supplied must be at least degree plus one.
1215 knots \@INTEGERS
1217 Array of integers, number of points plus degree plus one, which
1218 makes the result a Bezier curve. By default, if the shape is
1219 opened (i.e. first and last points are different), is set to a
1220 clamped array, so that the first and last points of the final
1221 curve match the first and the last control points. If the shape
1222 is closed, set to an unclamped array, so that no control points
1223 lie directly on the curve.
1224 precision INTEGER = 24
1226 Defines number of steps to split the curve into. The value is
1227 multiplied to the number of points and the result is used as
1228 number of steps.
1229 weight \@INTEGERS = [ 1, 1, 1, ... ]
1231 Array of integers, one for each point supplied. Assigning these
1232 can be used to convert B-spline into a NURBS. By default set of
1233 ones.
1234 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1236 miterLimit, rop, rop2
1237 See also: fill_spline, render_spline.
1239 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1241 Copies a OBJECT into a destination rectangle, stretching or
1242 compressing the OBJECT to fit the dimensions of the destination
1243 rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT are
1244 negative, a mirroring is performed. The destination rectangle
1245 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1246 pixels tall.
1247 If ROP raster operation is specified, it is used. Otherwise, value
1249 of "::rop" property is used.
1250 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1252 Returns success flag; if failed, $@ contains the error.
1254 Context used: rop
1256 text_out TEXT, X, Y
1258 Draws TEXT string at (X,Y). TEXT is either character string, or a
1259 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1260 "Prima::Drawable::Glyphs->glyphs" strings of glyphs.
1261 Returns success flag; if failed, $@ contains the error.
1263 Context used: color, backColor, font, rop, textOpaque,
1265 textOutBaseline
1266 text_shape TEXT, %OPTIONS
1268 Converts TEXT into set of glyphs, returns either a
1269 "Prima::Drawable::Glyphs" object, or a 0 integer when shaping is
1270 not necessary, or "undef" as an error.
1271 When compiled with "libfribidi", runs unicode bidirectional
1273 algorithm on TEXT that properly positions embedded directional text
1274 (f.ex. a latin quote inside an arabic text), see
1275 <http://unicode.org/reports/tr9/tr9-22.html>. Without the library
1276 only does minimal RTL alignment.
1277 Glyphs returned are positioned according to RTL directions given in
1279 TEXT using characters from uncode block "General Punctuation U+2000
1280 .. U+206F". Additionally, character ligation may be performed to
1281 that one or more characters are respresented by one or more glyphs.
1282 Such syntatic units, clusters, are adopted in Prima where
1283 appropriate, instead of character units, for selection, navigation
1284 etc in f.ex. "Prima::InputLine" and "Prima::Edit". Helper routines
1285 that translate clusters, glyphs, and characters into each other are
1286 found in Prima::Drawable::Glyphs.
1287 Options recognized:
1289 advances BOOLEAN = false
1291 Shaping process may or may not fill integer array of advances
1292 and positions for each glyphs, depending on the implementation.
1293 The advances are needed to represent f.ex. combining
1294 graphemes, when TEXT consisting of two characters, "A" and
1295 combining grave accent U+300 should be drawn as a single À
1296 cluster but are represented by a two glyphs "A" and <"`">. The
1297 grave glyph has its own advance for standalone usage, but in
1298 this case it should be ignored, and that is achieved by filling
1299 advance table where the "A" advance is the normal glyph
1300 advance, whereas the advance of the "`" is zero. Also, the
1301 position table additionaly shifts glyph position by X and Y
1302 coordinates, when that is needed (f.ex. it might be positioned
1303 differently by vertical on "a" and "A").
1304 Setting this options to "true" will force fill advance and
1306 positioning tables. These tables can be manipulated laters,
1307 and are respected by "text_out" and "get_text_width".
1308 language STRING = undef
1310 When set, shaping process can take in the account the language
1311 of the text. F.ex. text "ae" will be shaped as a single glyph
1312 æ for the Latin language, but not for the English.
1313 level INTEGER = ts:XXX
1315 Select the shaping (i.e. text to glyph conversion) level, how
1316 the system should treat the input text and how deep the shaping
1317 should go. One of the following "ts::XXX" options:
1318 ts::Bytes
1320 Treats input text as non-unicode locale-specific
1321 codepoints, characters higher than 255 are treated as
1322 chr(255). Reordering never happens, kerning and ligation
1323 never happens, returns glyph indexes in a 1:1 mapping to
1324 each codepoint.
1325 ts::None
1327 Performs quick null shaping without mapping to the font
1328 glyphs, but only running bidirectional algorithm on the
1329 text. On the return, "glyphs", as well as eventual
1330 "advances" and "positions", are filled with zeros, but
1331 "indexes" are filled with the proper character offsets,
1332 effectively making it a visual to logical map since number
1333 of glyphs will always be equal to number of characters in
1334 TEXT, because ligation never happens here (except when text
1335 contains unicode directional characters such as isolates
1336 etc).
1337 By default, advances and positions are not filled, but if
1339 "advances" option is set, fills them with zeros.
1340 ts::Glyphs
1342 Applies the unicode bidi algoritm and maps the result onto
1343 font glyphs. Ligation and kerning doesn't happen here,
1344 it's basically same as "ts::None" but with the glyph
1345 mapping part.
1346 By default, advances and positions are not filled, but if
1348 "advances" option is set, fills the advances array with
1349 character glyph advances and the positions array with
1350 zeros.
1351 ts::Full
1353 Applies the unicode bidi algorithm, and runs the full
1354 shaping on the result. Ligation and kerning may occur.
1355 Always fills the advances and positions array; the
1356 "advances" option is ignored.
1357 If the system or the selected font does not support
1359 shaping, tries to ligate known arabic shapes using the
1360 fribidi library, when compiled with. Also in this case does
1361 not return the advances and positions by default, but if
1362 "advances" option is set, fills the advances array with
1363 character glyph advances and the positions array with
1364 zeros.
1365 pitch INTEGER
1367 When polyfont is active and font substitution is desired,
1368 filters only fonts that match "pitch", either "fp::Variable" or
1369 "fp::Fixed". By default will be set to "fp::Fixed" if the
1370 current for is monospaced, but to "fp::Default" matching all
1371 fonts, otherwise.
1372 polyfont BOOLEAN = true
1374 If set, scans if the currently selected font supports all
1375 unicode points, and if not, selects a substituions from a pre-
1376 populated list, taking into account the font pitch (see "pitch"
1377 above). In cases where the current font has not enough glyphs
1378 to shape all the requested unicode points, font substitution is
1379 made, and the result contains an extra array "fonts" (see
1380 "fonts" in Prima::Drawable). When the current font has all
1381 needed glyphs, the fonts array is not created.
1382 The font list access is available through "fontMapperPallette".
1384 Valid only with shaping levels "ts::Glyphs" and "ts::Full".
1386 reorder BOOLEAN = true
1388 When set, unicode bidi algorithm is used to reorder codepoints,
1389 and additionally RTL codepoints are reversed (depending on
1390 direction context).
1391 When unset, no such reordering occurs, to emulate as much as
1393 possible a behavior that each text grapheme is being mapped to
1394 a glyph cluster exactly as it occurs in the input text, from
1395 left to right. Note that bidi reordering still may occur
1396 internally, since system shapers may reverse placement of RTL
1397 characters, so that reordering is needed to cancel this. In
1398 theory the caller shouldn't see the difference as these should
1399 cancel each other, but if Prima miscalculates the expected way
1400 the system shaper does the bidi processing it might.
1401 A similar effect can be reached by prepending the text with
1403 U+202D (LEFT-TO-RIGHT OVERRIDE).
1404 rtl BOOLEAN
1406 If set to 1, default text direction is assumed as RTL, and as
1407 LTR if set to 0. If unset, the text direction is taken from
1408 "Prima::Application::textDirection".
1409 skip_if_simple BOOLEAN = false
1411 When set, checks whether shaping result is identical to the
1412 input, in a sense that a call to "text_out(TEXT)" and a call to
1413 "text_shape_out(TEXT)" produce identical results. Majority of
1414 english text will fall into that category, and when that indeed
1415 happens, returns integer value 0 instead of a glyph object.
1416 See also "text_shape_out", "get_text_shape_width",
1418 "text_wrap_shape".
1419 text_shape_out TEXT, X, Y[, RTL]
1421 Runs shaping on TEXT character string with the RTL flag or
1422 "$::application->textDirection". Draws the resulting glyph string
1423 at (X,Y).
1424 Returns success flag; if failed, $@ contains the error.
1426 Context used: color, backColor, font, rop, textOpaque,
1428 textOutBaseline
1429 Methods
1431 begin_paint
1432 Enters the enabled ( active paint ) state, returns success flag; if
1433 failed, $@ contains the error. Once the object is in enabled
1434 state, painting and drawing methods can perform write operations on
1435 a canvas.
1436 See also: "end_paint", "begin_paint_info", "Graphic context and
1438 canvas"
1439 begin_paint_info
1441 Enters the information state, returns success flag; if failed, $@
1442 contains the error. The object information state is same as
1443 enabled state ( see "begin_paint"), except painting and drawing
1444 methods do not change the object canvas.
1445 See also: "end_paint_info", "begin_paint", "Graphic context and
1447 canvas"
1448 end_paint
1450 Exits the enabled state and returns the object to a disabled state.
1451 See also: "begin_paint", "Graphic context and canvas"
1453 end_paint_info
1455 Exits the information state and returns the object to a disabled
1456 state.
1457 See also: "begin_paint_info", "Graphic context and canvas"
1459 font_match \%SOURCE, \%DEST, PICK = 1
1461 Performs merging of two font hashes, SOURCE and DEST. Returns the
1462 merge result. If PICK is true, matches the result with a system
1463 font repository.
1464 Called implicitly by "::font" on set-call, allowing the following
1466 example to work:
1467 $d-> font-> set( size => 10);
1469 $d-> font-> set( style => fs::Bold);
1470 In the example, the hash 'style => fs::Bold' does not overwrite the
1472 previous font context ( 'size => 10' ) but gets added to it ( by
1473 font_match()), providing the resulting font with both font
1474 properties set.
1475 fonts <FAMILY = "", ENCODING = "">
1477 Member of "Prima::Application" and "Prima::Printer", does not
1478 present in "Prima::Drawable".
1479 Returns an array of font metric hashes for a given font FAMILY and
1481 ENCODING. Every hash has full set of elements described in
1482 "Fonts".
1483 If called without parameters, returns an array of same hashes where
1485 each hash represents a member of font family from every system font
1486 set. It this special case, each font hash contains additional
1487 "encodings" entry, which points to an array of encodings available
1488 for the font.
1489 If called with FAMILY parameter set but no ENCODING is set,
1491 enumerates all combinations of fonts with all available encodings.
1492 If called with FAMILY set to an empty string, but ENCODING
1494 specified, returns only fonts that can be displayed with the
1495 encoding.
1496 Example:
1498 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1500 get_bpp
1502 Returns device color depth. 1 is for black-and-white monochrome, 24
1503 for true color, etc.
1504 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1506 Returns ABC font metrics for the given range, starting at
1507 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1508 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1509 responsible of representation of characters in 127-255 range. If
1510 0, the default, encoding-dependent characters are assumed. If 1,
1511 the U007F-U00FF glyphs from Latin-1 set are used.
1512 The result is an integer array reference, where every character
1514 glyph is referred by three integers, each triplet containing A, B
1515 and C values.
1516 For detailed explanation of ABC meaning, see "Font ABC metrics";
1518 Context used: font
1520 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1522 Same as "get_font_abc", but for vertical mertics. Is expensive on
1523 bitmap fonts, because to find out the correct values Prima has to
1524 render glyphs on bitmaps and scan for black and white pixels.
1525 Vector fonts are not subject to this, and the call is as effective
1527 as "get_font_abc".
1528 get_font_languages
1530 Returns array of ISO 639 strings that can be displayed using glyphs
1531 available in the currently selected font.
1532 get_font_ranges
1534 Returns array of integer pairs denoting unicode indices of glyphs
1535 covered by the currently selected font. Each pair is the first and
1536 the last index of a contiguous range.
1537 Context used: font
1539 get_nearest_color COLOR
1541 Returns a nearest possible solid color in representation of object-
1542 bound graphic device. Always returns same color if the device bit
1543 depth is equal or greater than 24.
1544 get_paint_state
1546 Returns paint state value on of ps:: constants - "ps::Disabled" if
1547 the object is in the disabled state, "ps::Enabled" for the enabled
1548 state, "ps::Information" for the information state.
1549 For brevity, mb::Disabled is equal to 0 so this allows for simple
1551 boolean testing whether one can get/set graphical properties on an
1552 object.
1553 See "Graphic context and canvas" for more.
1555 get_physical_palette
1557 Returns an anonymous array of integers, in (R,G,B) format, every
1558 color entry described by three values, in range 0 - 255.
1559 The physical palette array is non-empty only on paletted graphic
1561 devices, the true color devices return an empty array.
1562 The physical palette reflects the solid colors currently available
1564 to all programs in the system. The information is volatile if the
1565 system palette can change colors, since any other application may
1566 change the system colors at any moment.
1567 get_text_shape_width TEXT, [ FLAGS ]
1569 Runs shaping on TEXT character string with text direction either
1570 taken from "FLAGS & to::RTL" value, or from the or
1571 "$::application->textDirection". Returns the shaping result width
1572 as if it would be drawn using currently selected font.
1573 If "FLAGS & to::AddOverhangs" is set, the first character's
1575 absolute A value and the last character's absolute C value are
1576 added to the string if they are negative.
1577 get_text_width TEXT, ADD_OVERHANG = 0
1579 Returns TEXT string width if it would be drawn using currently
1580 selected font. TEXT is either a character string, or a
1581 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1582 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1583 If ADD_OVERHANG is 1, the first character's absolute A value and
1585 the last character's absolute C value are added to the string if
1586 they are negative.
1587 See more on ABC values at "Font ABC metrics".
1589 Context used: font
1591 get_text_box TEXT
1593 Returns TEXT string extensions if it would be drawn using currently
1594 selected font. TEXT is either a character string, or a
1595 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1596 "Prima::Drawable::Glyphs-> glyphs" glyph string.
1597 The result is an anonymous array of 5 points ( 5 integer pairs in
1599 (X,Y) format). These 5 points are offsets for the following string
1600 extents, given the string is plotted at (0,0):
1601 1: start of string at ascent line ( top left )
1603 2: start of string at descent line ( bottom left )
1605 3: end of string at ascent line ( top right )
1607 4: end of string at descent line ( bottom right )
1609 5: concatenation point
1611 The concatenation point coordinates (XC,YC) are coordinated passed
1613 to consequent text_out() call so the conjoint string would plot as
1614 if it was a part of TEXT. Depending on the value of the
1615 "textOutBaseline" property, the concatenation point is located
1616 either on the baseline or on the descent line.
1617 Context used: font, textOutBaseline
1619 1 3 3 4
1621 ** ****
1622 * * *
1623 *** ***
1624 * * *
1625 **** **
1626 2 4 1 2
1627 render_glyph INDEX, %OPTIONS
1629 Returns glyph representation as an outline. The outline is an
1630 integer array, formed as a set of plotting commands. Each commnds
1631 is a "ggo::" constant, followed by number of points, followed by
1632 the 2D point coordinates in 1/64 pixels.
1633 Options recognized:
1635 glyph BOOL
1637 If set, INDEX is treated as the glyph index rather than
1638 character index. Default is false.
1639 hints BOOL
1641 Is set, hinting is enabled. Default is true.
1642 unicode BOOL
1644 If set, INDEX is threated as a utf8 character index, otherwise
1645 a locale-specific index. Default is false.
1646 The "ggo::" commands are:
1648 ggo::Move - move point
1650 ggo::Line - plot line
1651 ggo::Conic - plot 2-degree spline
1652 ggo::Cubic - plot 3-degree spline
1653 render_spline \@VERTICES, %OPTIONS
1655 Renders B-spline curve from set of VERTICES to a polyline with
1656 given options.
1657 The method is internally used by "spline" and "fill_spline", and is
1659 provided for cases when these are insufficient. See description of
1660 options in spline.
1661 text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
1663 Breaks TEXT string in chunks that would fit into WIDTH pixels wide
1664 box. TEXT is either character string, or a
1665 "Prima::Drawable::Glyphs" object returned from "text_shape", or
1666 "Prima::Drawable::Glyphs->glyphs" strings of glyphs. In the glyph
1667 cases, some wrapping options are not applicable.
1668 The break algorithm and its result are governed by OPTIONS integer
1670 value which is a combination of "tw::" constants:
1671 tw::CalcMnemonic
1673 Use 'hot key' semantics, when a character preceded by ~ has
1674 special meaning - it gets underlined. If this bit is set, the
1675 first tilde character used as an escapement is not calculated,
1676 and never appeared in the result apart from the escaped
1677 character.
1678 Not applicable in glyph wrapping.
1680 tw::CollapseTilde
1682 In addition to tw::CalcMnemonic, removes '~' character from the
1683 resulting chunks.
1684 Not applicable in glyph wrapping.
1686 tw::CalcTabs
1688 If set, calculates a tab ('\t') character as TAB_INDENT times
1689 space characters.
1690 Not applicable in glyph wrapping.
1692 tw::ExpandTabs
1694 If set, expands tab ('\t') character as TAB_INDENT times space
1695 characters.
1696 Not applicable in glyph wrapping.
1698 tw::BreakSingle
1700 Defines procedure behavior when the text cannot be fit in
1701 WIDTH, does not affect anything otherwise.
1702 If set, returns an empty array. If unset, returns a text
1704 broken by minimum number of characters per chunk. In the
1705 latter case, the width of the resulting text blocks will exceed
1706 WIDTH.
1707 tw::NewLineBreak
1709 Forces new chunk after a newline character ('\n') is met. If
1710 UTF8 text is passed, unicode line break characters 0x2028 and
1711 0x2029 produce same effect as the newline character.
1712 Not applicable in glyph wrapping.
1714 tw::SpaceBreak
1716 Forces new chunk after a space character (' ') or a tab
1717 character ('\t') are met.
1718 Not applicable in glyph wrapping.
1720 tw::ReturnChunks
1722 Defines the result of text_wrap() function.
1723 If set, the array consists of integer pairs, each consists of a
1725 text offset within TEXT and a its length.
1726 If unset, the resulting array consists from text chunks.
1728 tw::ReturnLines
1730 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1731 Not applicable in glyph wrapping.
1733 tw::WordBreak
1735 If unset, the TEXT breaks as soon as the chunk width exceeds
1736 WIDTH. If set, tries to keep words in TEXT so they do not
1737 appear in two chunks, e.g. breaks TEXT by words, not by
1738 characters.
1739 Not applicable in glyph wrapping.
1741 tw::ReturnFirstLineLength
1743 If set, "text_wrap" proceeds until the first line is wrapped,
1744 either by width or ( if specified ) by break characters.
1745 Returns length of the resulting line. Used for efficiency when
1746 the reverse function to "get_text_width" is needed.
1747 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1749 the last scalar in the array result is a special hash reference.
1750 The hash contains extra information regarding the 'hot key'
1751 underline position - it is assumed that '~' - escapement denotes an
1752 underlined character. The hash contains the following keys:
1753 tildeLine
1755 Chunk index that contains the escaped character. Set to undef
1756 if no ~ - escapement was found. The other hash information is
1757 not relevant in this case.
1758 tildeStart
1760 Horizontal offset of a beginning of the line that underlines
1761 the escaped character.
1762 tildeEnd
1764 Horizontal offset of an end of the line that underlines the
1765 escaped character.
1766 tildeChar
1768 The escaped character.
1769 Context used: font
1771 text_wrap_shape TEXT, WIDTH, %OPTIONS
1773 Runs "text_shape" over results from "text_wrap" call, with "TEXT",
1774 "WIDTH", $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are
1775 used in "text_shape" call. Where "text_wrap" returns text
1776 substrings or positions, return glyphs objects or their positions
1777 instead.
1778 When called with "tw::CalcMnemonic" options, recalculates the tilde
1780 position so it adapts to glyph positions returned.
1781
1783 Dmitry Karasik, <dmitry@karasik.eu.org>.
1784
1786 Prima, Prima::Object, Prima::Image, Prima::Region,
1787 Prima::Drawable::Path, Prima::Drawable::Glyphs
1788perl v5.32.0 2020-07-28 pod::Prima::Drawable(3)