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 A 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 different
296 glyph widths. This key is of the highest priority; all other keys
297 may be altered for the consistency of the pitch key.
298 direction
300 A counter-clockwise rotation angle - 0 is default, 90 is pi/2, 180
301 is pi, etc. If a font could not be rotated, it is usually
302 substituted to the one that can.
303 encoding
305 A string value, one of the strings returned by
306 "Prima::Application::font_encodings". Selects desired font
307 encoding; if empty, picks the first matched encoding, preferably
308 the locale set up by the user.
309 The encodings provided by different systems are different; in
311 addition, the only encodings are recognizable by the system, that
312 are represented by at least one font in the system.
313 Unix systems and the toolkit PostScript interface usually provide
315 the following encodings:
316 iso8859-1
318 iso8859-2
319 ... other iso8859 ...
320 fontspecific
321 Win32 returns the literal strings like
323 Western
325 Baltic
326 Cyrillic
327 Hebrew
328 Symbol
329 A hash that "::font" returns, is a tied hash, whose keys are also
331 available as separate properties. For example,
332 $x = $d-> font-> {style};
334 is equivalent to
336 $x = $d-> font-> style;
338 While the latter gives nothing but the arguable coding convenience, its
340 usage in set-call is much more usable:
341 $d-> font-> style( fs::Bold);
343 instead of
345 my %temp = %{$d-> font};
347 $temp{ style} = fs::Bold;
348 $d-> font( \%temp);
349 The properties of a font tied hash are also accessible through set()
351 call, like in Prima::Object:
352 $d-> font-> style( fs::Bold);
354 $d-> font-> width( 10);
355 is adequate to
357 $d-> font-> set(
359 style => fs::Bold,
360 width => 10,
361 );
362 When get-called, "::font" property returns a hash where more entries
364 than the described above can be found. These keys are read-only, their
365 values are discarded if passed to "::font" in a set-call.
366 In order to query the full list of fonts available to a graphic device,
368 a "::fonts" method is used. This method is not present in
369 Prima::Drawable namespace; it can be found in two built-in class
370 instances, "Prima::Application" and "Prima::Printer".
371 "Prima::Application::fonts" returns metrics for the fonts available to
373 a screen device, while "Prima::Printer::fonts" ( or its substitute
374 Prima::PS::Printer ) returns fonts for the printing device. The result
375 of this method is an array of font metrics, fully analogous to these
376 returned by "Prima::Drawable::font" method.
377 family
379 A string with font family name. The family is a secondary string
380 key, used for distinguishing between fonts with same name but of
381 different vendors ( for example, Adobe Courier and Microsoft
382 Courier).
383 vector
385 A boolean; true if the font is vector ( e.g. can be scaled with no
386 quality loss ), false otherwise. The false value does not show if
387 the font can be scaled at all - the behavior is system-dependent.
388 Win32 can scale all non-vector fonts; X11 only the fonts specified
389 as the scalable.
390 ascent
392 Number of pixels between a glyph baseline and descent line.
393 descent
395 Number of pixels between a glyph baseline and descent line.
396 internalLeading
398 Number of pixels between ascent and internal leading lines.
399 Negative if the ascent line is below the internal leading line.
400 externalLeading
402 Number of pixels between ascent and external leading lines.
403 Negative if the ascent line is above the external leading line.
404 ------------- external leading line
406 $ ------------- ascent line
408 $ $
409 ------------- internal leading line
410 $
411 $$$
412 $ $
413 $ $ $
414 $$$$$$$ $$$
415 $ $ $ $
416 $ $ $ $
417 $ $ $$$ ---- baseline
418 $
419 $
420 $
421 $$$$ ---- descent line
422 weight
424 A font designed weight. Can be one of
425 fw::UltraLight
427 fw::ExtraLight
428 fw::Light
429 fw::SemiLight
430 fw::Medium
431 fw::SemiBold
432 fw::Bold
433 fw::ExtraBold
434 fw::UltraBold
435 constants.
437 maximalWidth
439 Maximal extent of a glyph in pixels. Equals to width in monospaced
440 fonts.
441 xDeviceRes
443 Designed horizontal font resolution in dpi.
444 yDeviceRes
446 Designed vertical font resolution in dpi.
447 firstChar
449 Index of the first glyph present in a font.
450 lastChar
452 Index of the last glyph present in a font.
453 breakChar
455 Index of the default character used to divide words. In a typical
456 western language font it is 32, ASCII space character.
457 defaultChar
459 Index of a glyph that is drawn instead of nonexistent glyph if its
460 index is passed to the text drawing routines.
461 Font ABC metrics
463 Besides these characteristics, every font glyph has an ABC-metric, the
464 three integer values that describe horizontal extents of a glyph's
465 black part relative to the glyph extent:
466 . . . . . . . .
468 . . $$$. . . . .
469 . . $$. $ . . . .
470 . . $$. . . . $$ . .
471 . $$$$$$$$$$. . .$$$$$ . .
472 . . $$ . . . $ $$ . .
473 . . $$ . . . .$$$$$ . .
474 . . $$ . . . . $$ . .
475 . .$$ . . . . $$$ $$$. .
476 $$ .$$ . . . $ $$ .
477 .$$$ . . . .$$$$$$$$. .
478 . . . . . . . .
479 <A>. .<C> <A>. .<C>
480 .<-.--B--.->. . .<--B--->. .
481 A = -3 A = 3
483 B = 13 B = 10
484 C = -3 C = 3
485 A and C are negative, if a glyphs 'hangs' over it neighbors, as shown
487 in picture on the left. A and C values are positive, if a glyph
488 contains empty space in front or behind the neighbor glyphs, like in
489 picture on the right. As can be seen, B is the width of a glyph's
490 black part.
491 ABC metrics returned by the get_font_abc() method.
493 Corresponding vertical metrics, called in Prima "DEF" metrics, are
495 returned by the get_font_def() method.
496 Raster operations
498 A drawable has two raster operation properties: "::rop" and "::rop2".
499 These define how the graphic primitives are plotted. "::rop" deals with
500 the foreground color drawing, and "::rop2" with the background.
501 The toolkit defines the following operations:
503 rop::Blackness # = 0
505 rop::NotOr # = !(src | dest)
506 rop::NotSrcAnd # &= !src
507 rop::NotPut # = !src
508 rop::NotDestAnd # = !dest & src
509 rop::Invert # = !dest
510 rop::XorPut # ^= src
511 rop::NotAnd # = !(src & dest)
512 rop::AndPut # &= src
513 rop::NotXor # = !(src ^ dest)
514 rop::NotSrcXor # alias for rop::NotXor
515 rop::NotDestXor # alias for rop::NotXor
516 rop::NoOper # = dest
517 rop::NotSrcOr # |= !src
518 rop::CopyPut # = src
519 rop::NotDestOr # = !dest | src
520 rop::OrPut # |= src
521 rop::Whiteness # = 1
522 Usually, however, graphic devices support only a small part of the
524 above set, limiting "::rop" to the most important operations: Copy,
525 And, Or, Xor, NoOp. "::rop2" is usually even more restricted, supports
526 only Copy and NoOp.
527 The raster operations apply to all graphic primitives except SetPixel.
529 Note for layering: using layered images and device bitmaps with
531 "put_image" and "stretch_image" can only use "rop::SrcCopy" and
532 "rop::SrcOver" raster operations on OS-provided surfaces.
533 Additionally, Prima implements extra features for compositing on images
535 outside the begin_paint/end_paint brackets. It supports the following
536 12 Porter-Duff operators and some selected Photoshop blend operators:
537 rop::Clear rop::Add
539 rop::Xor rop::Multiply
540 rop::SrcOver rop::Screen
541 rop::DstOver rop::Overlay
542 rop::SrcCopy rop::Darken
543 rop::DstCopy rop::Lighten
544 rop::SrcIn rop::ColorDodge
545 rop::DstIn rop::ColorBurn
546 rop::SrcOut rop::HardLight
547 rop::DstOut rop::SoftLight
548 rop::SrcAtop rop::Difference
549 rop::DstAtop rop::Exclusion
550 and set of constants to apply a constant source and destination alpha
552 to override the existing alpha channel, if any:
553 rop::SrcAlpha
555 rop::SrcAlphaShift
556 rop::DstAlpha
557 rop::DstAlphaShift
558 To override the alpha channel(s) combine the rop constant using this
560 formula:
561 $rop = rop::XXX |
563 rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
564 rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
565 Also, function "rop::blend($alpha)" creates a rop constant for simple
567 blending of two images by the following formula:
568 $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
570 Its brother function "rop::alpha($rop, $src_alpha[, $dst_alpha])" can
572 be used for drawing on image outside begin_paint/end_paint:
573 $image->rop( rop::alpha( rop::SrcOver, 128 ));
575 $image->ellipse( 5, 5, 5, 5 );
576 In addition to that, "rop::AlphaCopy" operation is available for
578 accessing alpha bits only. When used, the source image is treated as
579 alpha mask, and therefore it has to be grayscale. It can be used to
580 apply the alpha bits independently, without need to construct an Icon
581 object.
582 Coordinates
584 The Prima toolkit employs a geometrical XY grid, where X ascends
585 rightwards and Y ascends upwards. There, the (0,0) location is the
586 bottom-left pixel of a canvas.
587 All graphic primitives use inclusive-inclusive boundaries. For
589 example,
590 $d-> bar( 0, 0, 1, 1);
592 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
594 The coordinate origin can be shifted using "::translate" property, that
596 translates the (0,0) point to the given offset. Calls to "::translate",
597 "::clipRect" and "::region" always use the 'physical' (0,0) point,
598 whereas the plotting methods use the transformation result, the
599 'logical' (0,0) point.
600 As noted before, these three properties can not be used in when an
602 object is in its disabled state.
603
605 Graphic context properties
606 backColor COLOR
607 Reflects background color in the graphic context. All drawing
608 routines that use non-solid or transparent fill or line patterns
609 use this property value.
610 color COLOR
612 Reflects foreground color in the graphic context. All drawing
613 routines use this property value.
614 clipRect X1, Y1, X2, Y2
616 Selects the clipping rectangle corresponding to the physical canvas
617 origin. On get-call, returns the extent of the clipping area, if
618 it is not rectangular, or the clipping rectangle otherwise. The
619 code
620 $d-> clipRect( 1, 1, 2, 2);
622 $d-> bar( 0, 0, 1, 1);
623 thus affects only one pixel at (1,1).
625 Set-call discards the previous "::region" value.
627 Note: "::clipRect" can not be used while the object is in the
629 paint-disabled state, its context is neither recorded nor used as a
630 template ( see "Graphic context and canvas").
631 fillMode INTEGER
633 Affects filling style of complex polygonal shapes filled by
634 "fillpoly". If "fm::Winding", the filled shape contains no holes;
635 if "fm::EvenOdd", holes are present where the shape edges cross.
636 "fm::Overlay" flag can be combined with these to counter an
638 intrinsic defect of filled shaped both in Win32 and X11 that don't
639 exactly follow polygon vertices. When supplied, it overlays a
640 polygon over the filled shape, so that the latter falls exactly in
641 the boundaries defined by vertices. This is desirable when one
642 wants to follow polygon vertices, but is not desirable when a shape
643 has holes in it connected in a way that the polygon overlay may
644 leave connection edges over them.
645 Default value: "fm::Winding|fm::Overlay"
647 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
649 Selects 8x8 fill pattern that affects primitives that plot filled
650 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
651 fill_sector(), floodfill().
652 Accepts either a "fp::" constant or a reference to an array of 8
654 integers, each representing 8 bits of each line in a pattern, where
655 the first integer is the topmost pattern line, and the bit 0x80 is
656 the leftmost pixel in the line.
657 There are some predefined patterns, that can be referred via "fp::"
659 constants:
660 fp::Empty
662 fp::Solid
663 fp::Line
664 fp::LtSlash
665 fp::Slash
666 fp::BkSlash
667 fp::LtBkSlash
668 fp::Hatch
669 fp::XHatch
670 fp::Interleave
671 fp::WideDot
672 fp::CloseDot
673 fp::SimpleDots
674 fp::Borland
675 fp::Parquet
676 ( the actual patterns are hardcoded in primguts.c ) The default
678 pattern is fp::Solid.
679 An example below shows encoding of fp::Parquet pattern:
681 # 76543210
683 84218421 Hex
684 0 $ $ $ 51
686 1 $ $ 22
687 2 $ $ $ 15
688 3 $ $ 88
689 4 $ $ $ 45
690 5 $ $ 22
691 6 $ $ $ 54
692 7 $ $ 88
693 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
695 On a get-call always returns an array, never a "fp::" constant.
697 fillPatternOffset X, Y
699 Origin coordinates for the "fillPattern", from 0 to 7.
700 font \%FONT
702 Manages font context. FONT hash acceptable values are "name",
703 "height", "size", "width", "style" and "pitch".
704 Synopsis:
706 $d-> font-> size( 10);
708 $d-> font-> name( 'Courier');
709 $d-> font-> set(
710 style => $x-> font-> style | fs::Bold,
711 width => 22
712 );
713 See "Fonts" for the detailed descriptions.
715 Applies to text_out(), get_text_width(), get_text_box(),
717 get_font_abc(), get_font_def().
718 lineEnd VALUE
720 Selects a line ending cap for plotting primitives. VALUE can be one
721 of
722 le::Flat
724 le::Square
725 le::Round
726 constants. le::Round is the default value.
728 lineJoin VALUE
730 Selects a line joining style for polygons. VALUE can be one of
731 lj::Round
733 lj::Bevel
734 lj::Miter
735 constants. lj::Round is the default value.
737 linePattern PATTERN
739 Selects a line pattern for plotting primitives. PATTERN is either
740 a predefined "lp::" constant, or a string where each even byte is a
741 length of a dash, and each odd byte is a length of a gap.
742 The predefined constants are:
744 lp::Null # "" /* */
746 lp::Solid # "\1" /* ___________ */
747 lp::Dash # "\x9\3" /* __ __ __ __ */
748 lp::LongDash # "\x16\6" /* _____ _____ */
749 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
750 lp::Dot # "\1\3" /* . . . . . . */
751 lp::DotDot # "\1\1" /* ............ */
752 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
753 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
754 Not all systems are capable of accepting user-defined line
756 patterns, and in such situation the "lp::" constants are mapped to
757 the system-defined patterns. In Win9x, for example, lp::DashDotDot
758 is much different from its string definition therefore.
759 Default value is lp::Solid.
761 lineWidth WIDTH
763 Selects a line width for plotting primitives. If a VALUE is 0,
764 then a 'cosmetic' pen is used - the thinnest possible line that a
765 device can plot. If a VALUE is greater than 0, then a 'geometric'
766 pen is used - the line width is set in device units. There is a
767 subtle difference between VALUE 0 and 1 in a way the lines are
768 joined.
769 Default value is 0.
771 miterLimit VALUE
773 When path segments connect at a sharp angle, a miter join results
774 in a spike that extends well beyond the connection point. The
775 purpose of the miter limit is to cut off such spikes when they
776 become objectionably long. At any given corner, the miter length is
777 the distance from the point at which the inner edges of the stroke
778 intersect to the point at which the outside edges of the strokes
779 intersect-in other words, the diagonal length of the miter. This
780 distance increases as the angle between the segments decreases. If
781 the ratio of the miter length to the line width exceeds the miter
782 limit parameter, stroke treats the corner with a bevel join instead
783 of a miter join. The ratio of miter length to line width is
784 directly related to the angle j between the segments by the
785 formula:
786 r = 1/sin(j/2)
788 Default value is 10.0.
790 Asssuming line join is "lj::Miter" and line angle is 30 degrees:
792 miter limit = 1.0: \__/
794 miter limit = 9.0: \ /
796 \/
797 Note: does not work under X11.
799 palette [ @PALETTE ]
801 Selects solid colors in a system palette, as many as possible.
802 PALETTE is an array of integer triplets, where each is R, G and B
803 component. The call
804 $d-> palette([128, 240, 240]);
806 selects a gray-cyan color, for example.
808 The return value from get-call is the content of the previous set-
810 call, not the actual colors that were copied to the system palette.
811 region OBJECT
813 Selects a clipping region applied to all drawing and painting
814 routines. On setting, the OBJECT is either undef, then the clip
815 region is erased ( no clip ), or a Prima::Image object with a bit
816 depth of 1. The bit mask of OBJECT is applied to the system
817 clipping region. Or, it is a Prima::Region object. If the OBJECT
818 is smaller than the drawable, its exterior is assigned to clipped
819 area as well. Discards the previous "::clipRect" value; successive
820 get-calls to "::clipRect" return the boundaries of the region.
821 On getting, OBJECT is either undef or Prima::Region object.
823 Note: "::region" can not be used while the object is in the paint-
825 disabled state, its context is neither recorded nor used as a
826 template ( see "Graphic context and canvas").
827 resolution X, Y
829 A read-only property. Returns horizontal and vertical device
830 resolution in dpi.
831 rop OPERATION
833 Selects raster operation that applies to foreground color plotting
834 routines.
835 See also: "::rop2", "Raster operations".
837 rop2 OPERATION
839 Selects raster operation that applies to background color plotting
840 routines.
841 See also: "::rop", "Raster operations".
843 textOpaque FLAG
845 If FLAG is 1, then text_out() fills the text background area with
846 "::backColor" property value before drawing the text. Default value
847 is 0, when text_out() plots text only.
848 See get_text_box().
850 textOutBaseline FLAG
852 If FLAG is 1, then text_out() plots text on a given Y coordinate
853 correspondent to font baseline. If FLAG is 0, a Y coordinate is
854 mapped to font descent line. Default is 0.
855 translate X_OFFSET, Y_OFFSET
857 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
858 affect "::clipRect" and "::region". Not cumulative, so the call
859 sequence
860 $d-> translate( 5, 5);
862 $d-> translate( 15, 15);
863 is equivalent to
865 $d-> translate( 15, 15);
867 Note: "::translate" can not be used while the object is in the
869 paint-disabled state, its context is neither recorded nor used as a
870 template ( see "Graphic context and canvas").
871 Other properties
873 height HEIGHT
874 Selects the height of a canvas.
875 size WIDTH, HEIGHT
877 Selects the extent of a canvas.
878 width WIDTH
880 Selects the width of a canvas.
881 Graphic primitives methods
883 alpha ALPHA <X1, Y1, X2, Y2>
884 Fills rectangle in the alpha channel, filled with ALPHA value
885 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
886 parameters, in this case fills all canvas area.
887 Has only effect on layered surfaces.
889 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
891 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
892 from START_ANGLE to END_ANGLE.
893 Context used: color, backColor, lineEnd, linePattern, lineWidth,
895 miterLimit, rop, rop2
896 bar X1, Y1, X2, Y2
898 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
899 Context used: color, backColor, fillPattern, fillPatternOffset,
901 rop, rop2
902 bars @RECTS
904 Draws a set of filled rectangles. RECTS is an array of integer
905 quartets in format (X1,Y1,X2,Y2).
906 Context used: color, backColor, fillPattern, fillPatternOffset,
908 rop, rop2
909 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
911 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
912 from START_ANGLE to END_ANGLE and connects its ends with a straight
913 line.
914 Context used: color, backColor, lineEnd, linePattern, lineWidth,
916 miterLimit, rop, rop2
917 clear <X1, Y1, X2, Y2>
919 Draws rectangle filled with pure background color within (X1,Y1) -
920 (X2,Y2) extents. Can be called without parameters, in this case
921 fills all canvas area.
922 Context used: backColor, rop2
924 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
926 TAB_INDENT = 1 ]
927 Draws several lines of text one under another with respect to align
928 and break rules, specified in FLAGS and TAB_INDENT tab character
929 expansion.
930 "draw_text" is a convenience wrapper around "text_wrap" for drawing
932 the wrapped text, and also provides the tilde ( ~ )- character
933 underlining support.
934 The FLAGS is a combination of the following constants:
936 dt::Left - text is aligned to the left boundary
938 dt::Right - text is aligned to the right boundary
939 dt::Center - text is aligned horizontally in center
940 dt::Top - text is aligned to the upper boundary
941 dt::Bottom - text is aligned to the lower boundary
942 dt::VCenter - text is aligned vertically in center
943 dt::DrawMnemonic - tilde-escapement and underlining is used
944 dt::DrawSingleChar - sets tw::BreakSingle option to
945 Prima::Drawable::text_wrap call
946 dt::NewLineBreak - sets tw::NewLineBreak option to
947 Prima::Drawable::text_wrap call
948 dt::SpaceBreak - sets tw::SpaceBreak option to
949 Prima::Drawable::text_wrap call
950 dt::WordBreak - sets tw::WordBreak option to
951 Prima::Drawable::text_wrap call
952 dt::ExpandTabs - performs tab character ( \t ) expansion
953 dt::DrawPartial - draws the last line, if it is visible partially
954 dt::UseExternalLeading - text lines positioned vertically with respect to
955 the font external leading
956 dt::UseClip - assign ::clipRect property to the boundary rectangle
957 dt::QueryLinesDrawn - calculates and returns number of lines drawn
958 ( contrary to dt::QueryHeight )
959 dt::QueryHeight - if set, calculates and returns vertical extension
960 of the lines drawn
961 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
962 dt::WordWrap - performs word wrapping by the width of the boundaries
963 dt::BidiText - use bidirectional formatting, if available
964 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
965 dt::UseExternalLeading
966 Context used: color, backColor, font, rop, textOpaque,
968 textOutBaseline
969 ellipse X, Y, DIAMETER_X, DIAMETER_Y
971 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
972 axis.
973 Context used: color, backColor, linePattern, lineWidth, rop, rop2
975 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
977 Fills a chord outline with center in X, Y and DIAMETER_X and
978 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see chord()).
979 Context used: color, backColor, fillPattern, fillPatternOffset,
981 rop, rop2
982 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
984 Fills an elliptical outline with center in X, Y and DIAMETER_X and
985 DIAMETER_Y axis.
986 Context used: color, backColor, fillPattern, fillPatternOffset,
988 rop, rop2
989 fillpoly \@POLYGON
991 Fills a polygonal area defined by POLYGON set of points. POLYGON
992 must present an array of integer pair in (X,Y) format. Example:
993 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
995 Context used: color, backColor, fillPattern, fillPatternOffset,
997 rop, rop2, fillMode
998 Returns success flag; if failed, $@ contains the error.
1000 See also: polyline().
1002 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1004 Fills a sector outline with center in X, Y and DIAMETER_X and
1005 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see sector()).
1006 Context used: color, backColor, fillPattern, fillPatternOffset,
1008 rop, rop2
1009 fill_spline \@VERTICES, %OPTIONS
1011 Fills a polygonal area defined by a curve, projected by applying
1012 B-spline curve based on set of VERTICES. VERTICES must present an
1013 array of integer pair in (X,Y) format. Example:
1014 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1016 Context used: color, backColor, fillPattern, fillPatternOffset,
1018 rop, rop2
1019 Returns success flag; if failed, $@ contains the error.
1021 See also: spline, render_spline
1023 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1025 Fills an area of the canvas in current fill context. The area is
1026 assumed to be bounded as specified by the SINGLEBORDER parameter.
1027 SINGLEBORDER can be 0 or 1.
1028 SINGLEBORDER = 0: The fill area is bounded by the color specified
1030 by the COLOR parameter.
1031 SINGLEBORDER = 1: The fill area is defined by the color that is
1033 specified by COLOR. Filling continues outward in all directions as
1034 long as the color is encountered. This style is useful for filling
1035 areas with multicolored boundaries.
1036 Context used: color, backColor, fillPattern, fillPatternOffset,
1038 rop, rop2
1039 line X1, Y1, X2, Y2
1041 Plots a straight line from (X1,Y1) to (X2,Y2).
1042 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1044 lines \@LINES
1046 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1047 lines() plots a straight line per quartet.
1048 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1050 Returns success flag; if failed, $@ contains the error.
1052 new_gradient
1054 Returns a new gradient object. See Prima::Drawable::Gradient for
1055 usage and details.
1056 new_path
1058 Returns a new path object. See Prima::Drawable::Path for usage and
1059 details.
1060 pixel X, Y, <COLOR>
1062 ::pixel is a property - on set-call it changes the pixel value at
1063 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1064 pixel value at (X,Y).
1065 No context is used.
1067 polyline \@POLYGON
1069 Draws a polygonal area defined by POLYGON set of points. POLYGON
1070 must present an array of integer pair in (X,Y) format.
1071 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1073 lineEnd, miterLimit, rop, rop2
1074 Returns success flag; if failed, $@ contains the error.
1076 See also: fillpoly().
1078 put_image X, Y, OBJECT, [ ROP ]
1080 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1081 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1082 specified, it is used. Otherwise, value of "::rop" property is
1083 used.
1084 Returns success flag; if failed, $@ contains the error.
1086 Context used: rop; color and backColor for a monochrome
1088 DeviceBitmap
1089 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1091 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1092 Copies a OBJECT from a source rectangle into a destination
1093 rectangle, stretching or compressing the OBJECT to fit the
1094 dimensions of the destination rectangle, if necessary. The source
1095 rectangle starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide
1096 and SRC_HEIGHT pixels tall. The destination rectangle starts at
1097 (X,Y), and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT)
1098 pixels tall. If DEST_WIDTH or DEST_HEIGHT are negative, a
1099 mirroring by respective axis is performed.
1100 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1102 No context is used, except color and backColor for a monochrome
1104 DeviceBitmap
1105 Returns success flag; if failed, $@ contains the error.
1107 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1109 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1110 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1111 specified, paints an inferior rectangle with it, otherwise the
1112 inferior rectangle is not touched.
1113 Context used: rop; color and backColor for a monochrome
1115 DeviceBitmap
1116 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1118 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1119 line width.
1120 No context is used.
1122 rectangle X1, Y1, X2, Y2
1124 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1125 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1127 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1129 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1130 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1131 two straight lines.
1132 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1134 miterLimit, rop, rop2
1135 spline \@VERTICES, %OPTIONS
1137 Draws a B-spline curve defined by set of VERTICES control points.
1138 VERTICES must present an array of integer pair in (X,Y) format.
1139 The following options are supported:
1141 closed BOOL = undef
1143 When not set, checks if the first and the last vertices point
1144 to the same point, and if yes, assumes a closed shape. Note - a
1145 closed shape rendering is implemented by adding degree minus
1146 two points to the set; this is important if "weight" or "knots"
1147 are specificed.
1148 degree INTEGER = 2
1150 The B-spline degree. Default is 2 (quadratic). Number of points
1151 supplied must be at least degree plus one.
1152 knots \@INTEGERS
1154 Array of integers, number of points plus degree plus one, which
1155 makes the result a Bezier curve. By default, if the shape is
1156 opened (i.e. first and last points are different), is set to a
1157 clamped array, so that the first and last points of the final
1158 curve match the first and the last control points. If the shape
1159 is closed, set to an unclamped array, so that no control points
1160 lie directly on the curve.
1161 precision INTEGER = 24
1163 Defines number of steps to split the curve into. The value is
1164 multiplied to the number of points and the result is used as
1165 number of steps.
1166 weight \@INTEGERS = [ 1, 1, 1, ... ]
1168 Array of integers, one for each point supplied. Assigning these
1169 can be used to convert B-spline into a NURBS. By default set of
1170 ones.
1171 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1173 miterLimit, rop, rop2
1174 See also: fill_spline, render_spline.
1176 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1178 Copies a OBJECT into a destination rectangle, stretching or
1179 compressing the OBJECT to fit the dimensions of the destination
1180 rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT are
1181 negative, a mirroring is performed. The destination rectangle
1182 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1183 pixels tall.
1184 If ROP raster operation is specified, it is used. Otherwise, value
1186 of "::rop" property is used.
1187 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1189 Returns success flag; if failed, $@ contains the error.
1191 Context used: rop
1193 text_out TEXT, X, Y
1195 Draws TEXT string at (X,Y).
1196 Returns success flag; if failed, $@ contains the error.
1198 Context used: color, backColor, font, rop, textOpaque,
1200 textOutBaseline
1201 Methods
1203 begin_paint
1204 Enters the enabled ( active paint ) state, returns success flag; if
1205 failed, $@ contains the error. Once the object is in enabled
1206 state, painting and drawing methods can perform write operations on
1207 a canvas.
1208 See also: "end_paint", "begin_paint_info", "Graphic context and
1210 canvas"
1211 begin_paint_info
1213 Enters the information state, returns success flag; if failed, $@
1214 contains the error. The object information state is same as
1215 enabled state ( see "begin_paint"), except painting and drawing
1216 methods do not change the object canvas.
1217 See also: "end_paint_info", "begin_paint", "Graphic context and
1219 canvas"
1220 end_paint
1222 Exits the enabled state and returns the object to a disabled state.
1223 See also: "begin_paint", "Graphic context and canvas"
1225 end_paint_info
1227 Exits the information state and returns the object to a disabled
1228 state.
1229 See also: "begin_paint_info", "Graphic context and canvas"
1231 font_match \%SOURCE, \%DEST, PICK = 1
1233 Performs merging of two font hashes, SOURCE and DEST. Returns the
1234 merge result. If PICK is true, matches the result with a system
1235 font repository.
1236 Called implicitly by "::font" on set-call, allowing the following
1238 example to work:
1239 $d-> font-> set( size => 10);
1241 $d-> font-> set( style => fs::Bold);
1242 In the example, the hash 'style => fs::Bold' does not overwrite the
1244 previous font context ( 'size => 10' ) but gets added to it ( by
1245 font_match()), providing the resulting font with both font
1246 properties set.
1247 fonts <FAMILY = "", ENCODING = "">
1249 Member of "Prima::Application" and "Prima::Printer", does not
1250 present in "Prima::Drawable".
1251 Returns an array of font metric hashes for a given font FAMILY and
1253 ENCODING. Every hash has full set of elements described in
1254 "Fonts".
1255 If called without parameters, returns an array of same hashes where
1257 each hash represents a member of font family from every system font
1258 set. It this special case, each font hash contains additional
1259 "encodings" entry, which points to an array of encodings available
1260 for the font.
1261 If called with FAMILY parameter set but no ENCODING is set,
1263 enumerates all combinations of fonts with all available encodings.
1264 If called with FAMILY set to an empty string, but ENCODING
1266 specified, returns only fonts that can be displayed with the
1267 encoding.
1268 Example:
1270 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1272 get_bpp
1274 Returns device color depth. 1 is for black-and-white monochrome, 24
1275 for true color, etc.
1276 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1278 Returns ABC font metrics for the given range, starting at
1279 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1280 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1281 responsible of representation of characters in 127-255 range. If
1282 0, the default, encoding-dependent characters are assumed. If 1,
1283 the U007F-U00FF glyphs from Latin-1 set are used.
1284 The result is an integer array reference, where every character
1286 glyph is referred by three integers, each triplet containing A, B
1287 and C values.
1288 For detailed explanation of ABC meaning, see "Font ABC metrics";
1290 Context used: font
1292 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1294 Same as "get_font_abc", but for vertical mertics. Is expensive on
1295 bitmap fonts, because to find out the correct values Prima has to
1296 render glyphs on bitmaps and scan for black and white pixels.
1297 Vector fonts are not subject to this, and the call is as effective
1299 as "get_font_abc".
1300 get_font_ranges
1302 Returns array of integer pairs denoting unicode indices of glyphs
1303 covered by the currently selected font. Each pair is the first and
1304 the last index of a contiguous range.
1305 Context used: font
1307 get_nearest_color COLOR
1309 Returns a nearest possible solid color in representation of object-
1310 bound graphic device. Always returns same color if the device bit
1311 depth is equal or greater than 24.
1312 get_paint_state
1314 Returns paint state value on of ps:: constants - "ps::Disabled" if
1315 the object is in the disabled state, "ps::Enabled" for the enabled
1316 state, "ps::Information" for the information state.
1317 For brevity, mb::Disabled is equal to 0 so this allows for simple
1319 boolean testing whether one can get/set graphical properties on an
1320 object.
1321 See "Graphic context and canvas" for more.
1323 get_physical_palette
1325 Returns an anonymous array of integers, in (R,G,B) format, every
1326 color entry described by three values, in range 0 - 255.
1327 The physical palette array is non-empty only on paletted graphic
1329 devices, the true color devices return an empty array.
1330 The physical palette reflects the solid colors currently available
1332 to all programs in the system. The information is volatile if the
1333 system palette can change colors, since any other application may
1334 change the system colors at any moment.
1335 get_text_width TEXT, ADD_OVERHANG = 0
1337 Returns TEXT string width if it would be drawn using currently
1338 selected font.
1339 If ADD_OVERHANG is 1, the first character's absolute A value and
1341 the last character's absolute C value are added to the string if
1342 they are negative.
1343 See more on ABC values at "Font ABC metrics".
1345 Context used: font
1347 get_text_box TEXT
1349 Returns TEXT string extensions if it would be drawn using currently
1350 selected font.
1351 The result is an anonymous array of 5 points ( 5 integer pairs in
1353 (X,Y) format). These 5 points are offsets for the following string
1354 extents, given the string is plotted at (0,0):
1355 1: start of string at ascent line ( top left )
1357 2: start of string at descent line ( bottom left )
1359 3: end of string at ascent line ( top right )
1361 4: end of string at descent line ( bottom right )
1363 5: concatenation point
1365 The concatenation point coordinates (XC,YC) are coordinated passed
1367 to consequent text_out() call so the conjoint string would plot as
1368 if it was a part of TEXT. Depending on the value of the
1369 "textOutBaseline" property, the concatenation point is located
1370 either on the baseline or on the descent line.
1371 Context used: font, textOutBaseline
1373 1 3 3 4
1375 ** ****
1376 * * *
1377 *** ***
1378 * * *
1379 **** **
1380 2 4 1 2
1381 render_glyph INDEX, %OPTIONS
1383 Returns glyph representation as an outline. The outline is an
1384 integer array, formed as a set of plotting commands. Each commnds
1385 is a "ggo::" constant, followed by number of points, followed by
1386 the 2D point coordinates in 1/64 pixels.
1387 Options recognized:
1389 glyph BOOL
1391 If set, INDEX is treated as the glyph index rather than
1392 character index. Default is false.
1393 hints BOOL
1395 Is set, hinting is enabled. Default is true.
1396 unicode BOOL
1398 If set, INDEX is threated as a utf8 character index, otherwise
1399 a locale-specific index. Default is false.
1400 The "ggo::" commands are:
1402 ggo::Move - move point
1404 ggo::Line - plot line
1405 ggo::Conic - plot 2-degree spline
1406 ggo::Cubic - plot 3-degree spline
1407 render_spline \@VERTICES, %OPTIONS
1409 Renders B-spline curve from set of VERTICES to a polyline with
1410 given options.
1411 The method is internally used by "spline" and "fill_spline", and is
1413 provided for cases when these are insufficient. See description of
1414 options in spline.
1415 text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
1417 Breaks TEXT string in chunks that would fit into WIDTH pixels wide
1418 box.
1419 The break algorithm and its result are governed by OPTIONS integer
1421 value which is a combination of "tw::" constants:
1422 tw::CalcMnemonic
1424 Use 'hot key' semantics, when a character preceded by ~ has
1425 special meaning - it gets underlined. If this bit is set, the
1426 first tilde character used as an escapement is not calculated,
1427 and never appeared in the result apart from the escaped
1428 character.
1429 tw::CollapseTilde
1431 In addition to tw::CalcMnemonic, removes '~' character from the
1432 resulting chunks.
1433 tw::CalcTabs
1435 If set, calculates a tab ('\t') character as TAB_INDENT times
1436 space characters.
1437 tw::ExpandTabs
1439 If set, expands tab ('\t') character as TAB_INDENT times space
1440 characters.
1441 tw::BreakSingle
1443 Defines procedure behavior when the text cannot be fit in
1444 WIDTH, does not affect anything otherwise.
1445 If set, returns an empty array. If unset, returns a text
1447 broken by minimum number of characters per chunk. In the
1448 latter case, the width of the resulting text blocks will exceed
1449 WIDTH.
1450 tw::NewLineBreak
1452 Forces new chunk after a newline character ('\n') is met. If
1453 UTF8 text is passed, unicode line break characters 0x2028 and
1454 0x2029 produce same effect as the newline character.
1455 tw::SpaceBreak
1457 Forces new chunk after a space character (' ') or a tab
1458 character ('\t') are met.
1459 tw::ReturnChunks
1461 Defines the result of text_wrap() function.
1462 If set, the array consists of integer pairs, each consists of a
1464 text offset within TEXT and a its length.
1465 If unset, the resulting array consists from text chunks.
1467 tw::ReturnLines
1469 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1470 tw::WordBreak
1472 If unset, the TEXT breaks as soon as the chunk width exceeds
1473 WIDTH. If set, tries to keep words in TEXT so they do not
1474 appear in two chunks, e.g. breaks TEXT by words, not by
1475 characters.
1476 tw::ReturnFirstLineLength
1478 If set, "text_wrap" proceeds until the first line is wrapped,
1479 either by width or ( if specified ) by break characters.
1480 Returns length of the resulting line. Used for efficiency when
1481 the reverse function to "get_text_width" is needed.
1482 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1484 the last scalar in the array result is a special hash reference.
1485 The hash contains extra information regarding the 'hot key'
1486 underline position - it is assumed that '~' - escapement denotes an
1487 underlined character. The hash contains the following keys:
1488 tildeLine
1490 Chunk index that contains the escaped character. Set to undef
1491 if no ~ - escapement was found. The other hash information is
1492 not relevant in this case.
1493 tildeStart
1495 Horizontal offset of a beginning of the line that underlines
1496 the escaped character.
1497 tildeEnd
1499 Horizontal offset of an end of the line that underlines the
1500 escaped character.
1501 tildeChar
1503 The escaped character.
1504 Context used: font
1506
1508 Dmitry Karasik, <dmitry@karasik.eu.org>.
1509
1511 Prima, Prima::Object, Prima::Image, Prima::Region,
1512 Prima::Drawable::Path
1513perl v5.30.1 2020-01-30 pod::Prima::Drawable(3)