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:
537 rop::Clear
539 rop::Xor
540 rop::SrcOver
541 rop::DstOver
542 rop::SrcCopy
543 rop::DstCopy
544 rop::SrcIn
545 rop::DstIn
546 rop::SrcOut
547 rop::DstOut
548 rop::SrcAtop
549 rop::DstAtop
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 In addition to that, "rop::AlphaCopy" operation is available for
572 accessing alpha bits only. When used, the source image is treated as
573 alpha mask, and therefore it has to be grayscale. It can be used to
574 apply the alpha bits independently, without need to construct an Icon
575 object.
576 Coordinates
578 The Prima toolkit employs a geometrical XY grid, where X ascends
579 rightwards and Y ascends upwards. There, the (0,0) location is the
580 bottom-left pixel of a canvas.
581 All graphic primitives use inclusive-inclusive boundaries. For
583 example,
584 $d-> bar( 0, 0, 1, 1);
586 plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
588 The coordinate origin can be shifted using "::translate" property, that
590 translates the (0,0) point to the given offset. Calls to "::translate",
591 "::clipRect" and "::region" always use the 'physical' (0,0) point,
592 whereas the plotting methods use the transformation result, the
593 'logical' (0,0) point.
594 As noted before, these three properties can not be used in when an
596 object is in its disabled state.
597
599 Graphic context properties
600 backColor COLOR
601 Reflects background color in the graphic context. All drawing
602 routines that use non-solid or transparent fill or line patterns
603 use this property value.
604 color COLOR
606 Reflects foreground color in the graphic context. All drawing
607 routines use this property value.
608 clipRect X1, Y1, X2, Y2
610 Selects the clipping rectangle corresponding to the physical canvas
611 origin. On get-call, returns the extent of the clipping area, if
612 it is not rectangular, or the clipping rectangle otherwise. The
613 code
614 $d-> clipRect( 1, 1, 2, 2);
616 $d-> bar( 0, 0, 1, 1);
617 thus affects only one pixel at (1,1).
619 Set-call discards the previous "::region" value.
621 Note: "::clipRect" can not be used while the object is in the
623 paint-disabled state, its context is neither recorded nor used as a
624 template ( see "Graphic context and canvas").
625 fillMode INTEGER
627 Affects filling style of complex polygonal shapes filled by
628 "fillpoly". If "fm::Winding", the filled shape contains no holes;
629 if "fm::EvenOdd", holes are present where the shape edges cross.
630 "fm::Overlay" flag can be combined with these to counter an
632 intrinsic defect of filled shaped both in Win32 and X11 that don't
633 exactly follow polygon vertices. When supplied, it overlays a
634 polygon over the filled shape, so that the latter falls exactly in
635 the boundaries defined by vertices. This is desirable when one
636 wants to follow polygon vertices, but is not desirable when a shape
637 has holes in it connected in a way that the polygon overlay may
638 leave connection edges over them.
639 Default value: "fm::Winding|fm::Overlay"
641 fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
643 Selects 8x8 fill pattern that affects primitives that plot filled
644 shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
645 fill_sector(), floodfill().
646 Accepts either a "fp::" constant or a reference to an array of 8
648 integers, each representing 8 bits of each line in a pattern, where
649 the first integer is the topmost pattern line, and the bit 0x80 is
650 the leftmost pixel in the line.
651 There are some predefined patterns, that can be referred via "fp::"
653 constants:
654 fp::Empty
656 fp::Solid
657 fp::Line
658 fp::LtSlash
659 fp::Slash
660 fp::BkSlash
661 fp::LtBkSlash
662 fp::Hatch
663 fp::XHatch
664 fp::Interleave
665 fp::WideDot
666 fp::CloseDot
667 fp::SimpleDots
668 fp::Borland
669 fp::Parquet
670 ( the actual patterns are hardcoded in primguts.c ) The default
672 pattern is fp::Solid.
673 An example below shows encoding of fp::Parquet pattern:
675 # 76543210
677 84218421 Hex
678 0 $ $ $ 51
680 1 $ $ 22
681 2 $ $ $ 15
682 3 $ $ 88
683 4 $ $ $ 45
684 5 $ $ 22
685 6 $ $ $ 54
686 7 $ $ 88
687 $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
689 On a get-call always returns an array, never a "fp::" constant.
691 fillPatternOffset X, Y
693 Origin coordinates for the "fillPattern", from 0 to 7.
694 font \%FONT
696 Manages font context. FONT hash acceptable values are "name",
697 "height", "size", "width", "style" and "pitch".
698 Synopsis:
700 $d-> font-> size( 10);
702 $d-> font-> name( 'Courier');
703 $d-> font-> set(
704 style => $x-> font-> style | fs::Bold,
705 width => 22
706 );
707 See "Fonts" for the detailed descriptions.
709 Applies to text_out(), get_text_width(), get_text_box(),
711 get_font_abc(), get_font_def().
712 lineEnd VALUE
714 Selects a line ending cap for plotting primitives. VALUE can be one
715 of
716 le::Flat
718 le::Square
719 le::Round
720 constants. le::Round is the default value.
722 lineJoin VALUE
724 Selects a line joining style for polygons. VALUE can be one of
725 lj::Round
727 lj::Bevel
728 lj::Miter
729 constants. lj::Round is the default value.
731 linePattern PATTERN
733 Selects a line pattern for plotting primitives. PATTERN is either
734 a predefined "lp::" constant, or a string where each even byte is a
735 length of a dash, and each odd byte is a length of a gap.
736 The predefined constants are:
738 lp::Null # "" /* */
740 lp::Solid # "\1" /* ___________ */
741 lp::Dash # "\x9\3" /* __ __ __ __ */
742 lp::LongDash # "\x16\6" /* _____ _____ */
743 lp::ShortDash # "\3\3" /* _ _ _ _ _ _ */
744 lp::Dot # "\1\3" /* . . . . . . */
745 lp::DotDot # "\1\1" /* ............ */
746 lp::DashDot # "\x9\6\1\3" /* _._._._._._ */
747 lp::DashDotDot # "\x9\3\1\3\1\3" /* _.._.._.._.. */
748 Not all systems are capable of accepting user-defined line
750 patterns, and in such situation the "lp::" constants are mapped to
751 the system-defined patterns. In Win9x, for example, lp::DashDotDot
752 is much different from its string definition therefore.
753 Default value is lp::Solid.
755 lineWidth WIDTH
757 Selects a line width for plotting primitives. If a VALUE is 0,
758 then a 'cosmetic' pen is used - the thinnest possible line that a
759 device can plot. If a VALUE is greater than 0, then a 'geometric'
760 pen is used - the line width is set in device units. There is a
761 subtle difference between VALUE 0 and 1 in a way the lines are
762 joined.
763 Default value is 0.
765 miterLimit VALUE
767 When path segments connect at a sharp angle, a miter join results
768 in a spike that extends well beyond the connection point. The
769 purpose of the miter limit is to cut off such spikes when they
770 become objectionably long. At any given corner, the miter length is
771 the distance from the point at which the inner edges of the stroke
772 intersect to the point at which the outside edges of the strokes
773 intersect-in other words, the diagonal length of the miter. This
774 distance increases as the angle between the segments decreases. If
775 the ratio of the miter length to the line width exceeds the miter
776 limit parameter, stroke treats the corner with a bevel join instead
777 of a miter join. The ratio of miter length to line width is
778 directly related to the angle j between the segments by the
779 formula:
780 r = 1/sin(j/2)
782 Default value is 10.0.
784 Asssuming line join is "lj::Miter" and line angle is 30 degrees:
786 miter limit = 1.0: \__/
788 miter limit = 9.0: \ /
790 \/
791 Note: does not work under X11.
793 palette [ @PALETTE ]
795 Selects solid colors in a system palette, as many as possible.
796 PALETTE is an array of integer triplets, where each is R, G and B
797 component. The call
798 $d-> palette([128, 240, 240]);
800 selects a gray-cyan color, for example.
802 The return value from get-call is the content of the previous set-
804 call, not the actual colors that were copied to the system palette.
805 region OBJECT
807 Selects a clipping region applied to all drawing and painting
808 routines. On setting, the OBJECT is either undef, then the clip
809 region is erased ( no clip ), or a Prima::Image object with a bit
810 depth of 1. The bit mask of OBJECT is applied to the system
811 clipping region. Or, it is a Prima::Region object. If the OBJECT
812 is smaller than the drawable, its exterior is assigned to clipped
813 area as well. Discards the previous "::clipRect" value; successive
814 get-calls to "::clipRect" return the boundaries of the region.
815 On getting, OBJECT is either undef or Prima::Region object.
817 Note: "::region" can not be used while the object is in the paint-
819 disabled state, its context is neither recorded nor used as a
820 template ( see "Graphic context and canvas").
821 resolution X, Y
823 A read-only property. Returns horizontal and vertical device
824 resolution in dpi.
825 rop OPERATION
827 Selects raster operation that applies to foreground color plotting
828 routines.
829 See also: "::rop2", "Raster operations".
831 rop2 OPERATION
833 Selects raster operation that applies to background color plotting
834 routines.
835 See also: "::rop", "Raster operations".
837 textOpaque FLAG
839 If FLAG is 1, then text_out() fills the text background area with
840 "::backColor" property value before drawing the text. Default value
841 is 0, when text_out() plots text only.
842 See get_text_box().
844 textOutBaseline FLAG
846 If FLAG is 1, then text_out() plots text on a given Y coordinate
847 correspondent to font baseline. If FLAG is 0, a Y coordinate is
848 mapped to font descent line. Default is 0.
849 translate X_OFFSET, Y_OFFSET
851 Translates the origin point by X_OFFSET and Y_OFFSET. Does not
852 affect "::clipRect" and "::region". Not cumulative, so the call
853 sequence
854 $d-> translate( 5, 5);
856 $d-> translate( 15, 15);
857 is equivalent to
859 $d-> translate( 15, 15);
861 Note: "::translate" can not be used while the object is in the
863 paint-disabled state, its context is neither recorded nor used as a
864 template ( see "Graphic context and canvas").
865 Other properties
867 height HEIGHT
868 Selects the height of a canvas.
869 size WIDTH, HEIGHT
871 Selects the extent of a canvas.
872 width WIDTH
874 Selects the width of a canvas.
875 Graphic primitives methods
877 alpha ALPHA <X1, Y1, X2, Y2>
878 Fills rectangle in the alpha channel, filled with ALPHA value
879 (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without
880 parameters, in this case fills all canvas area.
881 Has only effect on layered surfaces.
883 arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
885 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
886 from START_ANGLE to END_ANGLE.
887 Context used: color, backColor, lineEnd, linePattern, lineWidth,
889 miterLimit, rop, rop2
890 bar X1, Y1, X2, Y2
892 Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
893 Context used: color, backColor, fillPattern, fillPatternOffset,
895 rop, rop2
896 bars @RECTS
898 Draws a set of filled rectangles. RECTS is an array of integer
899 quartets in format (X1,Y1,X2,Y2).
900 Context used: color, backColor, fillPattern, fillPatternOffset,
902 rop, rop2
903 chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
905 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
906 from START_ANGLE to END_ANGLE and connects its ends with a straight
907 line.
908 Context used: color, backColor, lineEnd, linePattern, lineWidth,
910 miterLimit, rop, rop2
911 clear <X1, Y1, X2, Y2>
913 Draws rectangle filled with pure background color within (X1,Y1) -
914 (X2,Y2) extents. Can be called without parameters, in this case
915 fills all canvas area.
916 Context used: backColor, rop2
918 draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
920 TAB_INDENT = 1 ]
921 Draws several lines of text one under another with respect to align
922 and break rules, specified in FLAGS and TAB_INDENT tab character
923 expansion.
924 "draw_text" is a convenience wrapper around "text_wrap" for drawing
926 the wrapped text, and also provides the tilde ( ~ )- character
927 underlining support.
928 The FLAGS is a combination of the following constants:
930 dt::Left - text is aligned to the left boundary
932 dt::Right - text is aligned to the right boundary
933 dt::Center - text is aligned horizontally in center
934 dt::Top - text is aligned to the upper boundary
935 dt::Bottom - text is aligned to the lower boundary
936 dt::VCenter - text is aligned vertically in center
937 dt::DrawMnemonic - tilde-escapement and underlining is used
938 dt::DrawSingleChar - sets tw::BreakSingle option to
939 Prima::Drawable::text_wrap call
940 dt::NewLineBreak - sets tw::NewLineBreak option to
941 Prima::Drawable::text_wrap call
942 dt::SpaceBreak - sets tw::SpaceBreak option to
943 Prima::Drawable::text_wrap call
944 dt::WordBreak - sets tw::WordBreak option to
945 Prima::Drawable::text_wrap call
946 dt::ExpandTabs - performs tab character ( \t ) expansion
947 dt::DrawPartial - draws the last line, if it is visible partially
948 dt::UseExternalLeading - text lines positioned vertically with respect to
949 the font external leading
950 dt::UseClip - assign ::clipRect property to the boundary rectangle
951 dt::QueryLinesDrawn - calculates and returns number of lines drawn
952 ( contrary to dt::QueryHeight )
953 dt::QueryHeight - if set, calculates and returns vertical extension
954 of the lines drawn
955 dt::NoWordWrap - performs no word wrapping by the width of the boundaries
956 dt::WordWrap - performs word wrapping by the width of the boundaries
957 dt::BidiText - use bidirectional formatting, if available
958 dt::Default - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
959 dt::UseExternalLeading
960 Context used: color, backColor, font, rop, textOpaque,
962 textOutBaseline
963 ellipse X, Y, DIAMETER_X, DIAMETER_Y
965 Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
966 axis.
967 Context used: color, backColor, linePattern, lineWidth, rop, rop2
969 fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
971 Fills a chord outline with center in X, Y and DIAMETER_X and
972 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see chord()).
973 Context used: color, backColor, fillPattern, fillPatternOffset,
975 rop, rop2
976 fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
978 Fills an elliptical outline with center in X, Y and DIAMETER_X and
979 DIAMETER_Y axis.
980 Context used: color, backColor, fillPattern, fillPatternOffset,
982 rop, rop2
983 fillpoly \@POLYGON
985 Fills a polygonal area defined by POLYGON set of points. POLYGON
986 must present an array of integer pair in (X,Y) format. Example:
987 $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
989 Context used: color, backColor, fillPattern, fillPatternOffset,
991 rop, rop2, fillMode
992 Returns success flag; if failed, $@ contains the error.
994 See also: polyline().
996 fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
998 Fills a sector outline with center in X, Y and DIAMETER_X and
999 DIAMETER_Y axis from START_ANGLE to END_ANGLE (see sector()).
1000 Context used: color, backColor, fillPattern, fillPatternOffset,
1002 rop, rop2
1003 fill_spline \@VERTICES, %OPTIONS
1005 Fills a polygonal area defined by a curve, projected by applying
1006 B-spline curve based on set of VERTICES. VERTICES must present an
1007 array of integer pair in (X,Y) format. Example:
1008 $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
1010 Context used: color, backColor, fillPattern, fillPatternOffset,
1012 rop, rop2
1013 Returns success flag; if failed, $@ contains the error.
1015 See also: spline, render_spline
1017 flood_fill X, Y, COLOR, SINGLEBORDER = 1
1019 Fills an area of the canvas in current fill context. The area is
1020 assumed to be bounded as specified by the SINGLEBORDER parameter.
1021 SINGLEBORDER can be 0 or 1.
1022 SINGLEBORDER = 0: The fill area is bounded by the color specified
1024 by the COLOR parameter.
1025 SINGLEBORDER = 1: The fill area is defined by the color that is
1027 specified by COLOR. Filling continues outward in all directions as
1028 long as the color is encountered. This style is useful for filling
1029 areas with multicolored boundaries.
1030 Context used: color, backColor, fillPattern, fillPatternOffset,
1032 rop, rop2
1033 line X1, Y1, X2, Y2
1035 Plots a straight line from (X1,Y1) to (X2,Y2).
1036 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1038 lines \@LINES
1040 LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1041 lines() plots a straight line per quartet.
1042 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1044 Returns success flag; if failed, $@ contains the error.
1046 new_gradient
1048 Returns a new gradient object. See Prima::Drawable::Gradient for
1049 usage and details.
1050 new_path
1052 Returns a new path object. See Prima::Drawable::Path for usage and
1053 details.
1054 pixel X, Y, <COLOR>
1056 ::pixel is a property - on set-call it changes the pixel value at
1057 (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1058 pixel value at (X,Y).
1059 No context is used.
1061 polyline \@POLYGON
1063 Draws a polygonal area defined by POLYGON set of points. POLYGON
1064 must present an array of integer pair in (X,Y) format.
1065 Context used: color, backColor, linePattern, lineWidth, lineJoin,
1067 lineEnd, miterLimit, rop, rop2
1068 Returns success flag; if failed, $@ contains the error.
1070 See also: fillpoly().
1072 put_image X, Y, OBJECT, [ ROP ]
1074 Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1075 Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1076 specified, it is used. Otherwise, value of "::rop" property is
1077 used.
1078 Returns success flag; if failed, $@ contains the error.
1080 Context used: rop; color and backColor for a monochrome
1082 DeviceBitmap
1083 put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1085 DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1086 Copies a OBJECT from a source rectangle into a destination
1087 rectangle, stretching or compressing the OBJECT to fit the
1088 dimensions of the destination rectangle, if necessary. The source
1089 rectangle starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide
1090 and SRC_HEIGHT pixels tall. The destination rectangle starts at
1091 (X,Y), and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT)
1092 pixels tall. If DEST_WIDTH or DEST_HEIGHT are negative, a
1093 mirroring by respective axis is performed.
1094 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1096 No context is used, except color and backColor for a monochrome
1098 DeviceBitmap
1099 Returns success flag; if failed, $@ contains the error.
1101 rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1103 Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1104 line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1105 specified, paints an inferior rectangle with it, otherwise the
1106 inferior rectangle is not touched.
1107 Context used: rop; color and backColor for a monochrome
1109 DeviceBitmap
1110 rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1112 Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1113 line width.
1114 No context is used.
1116 rectangle X1, Y1, X2, Y2
1118 Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1119 Context used: color, backColor, linePattern, lineWidth, rop, rop2
1121 sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1123 Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1124 from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1125 two straight lines.
1126 Context used: color, backColor, lineEnd, linePattern, lineWidth,
1128 miterLimit, rop, rop2
1129 spline \@VERTICES, %OPTIONS
1131 Draws a B-spline curve defined by set of VERTICES control points.
1132 VERTICES must present an array of integer pair in (X,Y) format.
1133 The following options are supported:
1135 closed BOOL = undef
1137 When not set, checks if the first and the last vertices point
1138 to the same point, and if yes, assumes a closed shape. Note - a
1139 closed shape rendering is implemented by adding degree minus
1140 two points to the set; this is important if "weight" or "knots"
1141 are specificed.
1142 degree INTEGER = 2
1144 The B-spline degree. Default is 2 (quadratic). Number of points
1145 supplied must be at least degree plus one.
1146 knots \@INTEGERS
1148 Array of integers, number of points plus degree plus one, which
1149 makes the result a Bezier curve. By default, if the shape is
1150 opened (i.e. first and last points are different), is set to a
1151 clamped array, so that the first and last points of the final
1152 curve match the first and the last control points. If the shape
1153 is closed, set to an unclamped array, so that no control points
1154 lie directly on the curve.
1155 precision INTEGER = 24
1157 Defines number of steps to split the curve into. The value is
1158 multiplied to the number of points and the result is used as
1159 number of steps.
1160 weight \@INTEGERS = [ 1, 1, 1, ... ]
1162 Array of integers, one for each point supplied. Assigning these
1163 can be used to convert B-spline into a NURBS. By default set of
1164 ones.
1165 Context used: color, backColor, linePattern, lineWidth, lineEnd,
1167 miterLimit, rop, rop2
1168 See also: fill_spline, render_spline.
1170 stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1172 Copies a OBJECT into a destination rectangle, stretching or
1173 compressing the OBJECT to fit the dimensions of the destination
1174 rectangle, if necessary. If DEST_WIDTH or DEST_HEIGHT are
1175 negative, a mirroring is performed. The destination rectangle
1176 starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1177 pixels tall.
1178 If ROP raster operation is specified, it is used. Otherwise, value
1180 of "::rop" property is used.
1181 OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1183 Returns success flag; if failed, $@ contains the error.
1185 Context used: rop
1187 text_out TEXT, X, Y
1189 Draws TEXT string at (X,Y).
1190 Returns success flag; if failed, $@ contains the error.
1192 Context used: color, backColor, font, rop, textOpaque,
1194 textOutBaseline
1195 Methods
1197 begin_paint
1198 Enters the enabled ( active paint ) state, returns success flag; if
1199 failed, $@ contains the error. Once the object is in enabled
1200 state, painting and drawing methods can perform write operations on
1201 a canvas.
1202 See also: "end_paint", "begin_paint_info", "Graphic context and
1204 canvas"
1205 begin_paint_info
1207 Enters the information state, returns success flag; if failed, $@
1208 contains the error. The object information state is same as
1209 enabled state ( see "begin_paint"), except painting and drawing
1210 methods do not change the object canvas.
1211 See also: "end_paint_info", "begin_paint", "Graphic context and
1213 canvas"
1214 end_paint
1216 Exits the enabled state and returns the object to a disabled state.
1217 See also: "begin_paint", "Graphic context and canvas"
1219 end_paint_info
1221 Exits the information state and returns the object to a disabled
1222 state.
1223 See also: "begin_paint_info", "Graphic context and canvas"
1225 font_match \%SOURCE, \%DEST, PICK = 1
1227 Performs merging of two font hashes, SOURCE and DEST. Returns the
1228 merge result. If PICK is true, matches the result with a system
1229 font repository.
1230 Called implicitly by "::font" on set-call, allowing the following
1232 example to work:
1233 $d-> font-> set( size => 10);
1235 $d-> font-> set( style => fs::Bold);
1236 In the example, the hash 'style => fs::Bold' does not overwrite the
1238 previous font context ( 'size => 10' ) but gets added to it ( by
1239 font_match()), providing the resulting font with both font
1240 properties set.
1241 fonts <FAMILY = "", ENCODING = "">
1243 Member of "Prima::Application" and "Prima::Printer", does not
1244 present in "Prima::Drawable".
1245 Returns an array of font metric hashes for a given font FAMILY and
1247 ENCODING. Every hash has full set of elements described in
1248 "Fonts".
1249 If called without parameters, returns an array of same hashes where
1251 each hash represents a member of font family from every system font
1252 set. It this special case, each font hash contains additional
1253 "encodings" entry, which points to an array of encodings available
1254 for the font.
1255 If called with FAMILY parameter set but no ENCODING is set,
1257 enumerates all combinations of fonts with all available encodings.
1258 If called with FAMILY set to an empty string, but ENCODING
1260 specified, returns only fonts that can be displayed with the
1261 encoding.
1262 Example:
1264 print sort map {"$_->{name}\n"} @{$::application-> fonts};
1266 get_bpp
1268 Returns device color depth. 1 is for black-and-white monochrome, 24
1269 for true color, etc.
1270 get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1272 Returns ABC font metrics for the given range, starting at
1273 FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1274 default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1275 responsible of representation of characters in 127-255 range. If
1276 0, the default, encoding-dependent characters are assumed. If 1,
1277 the U007F-U00FF glyphs from Latin-1 set are used.
1278 The result is an integer array reference, where every character
1280 glyph is referred by three integers, each triplet containing A, B
1281 and C values.
1282 For detailed explanation of ABC meaning, see "Font ABC metrics";
1284 Context used: font
1286 get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1288 Same as "get_font_abc", but for vertical mertics. Is expensive on
1289 bitmap fonts, because to find out the correct values Prima has to
1290 render glyphs on bitmaps and scan for black and white pixels.
1291 Vector fonts are not subject to this, and the call is as effective
1293 as "get_font_abc".
1294 get_font_ranges
1296 Returns array of integer pairs denoting unicode indices of glyphs
1297 covered by the currently selected font. Each pair is the first and
1298 the last index of a contiguous range.
1299 Context used: font
1301 get_nearest_color COLOR
1303 Returns a nearest possible solid color in representation of object-
1304 bound graphic device. Always returns same color if the device bit
1305 depth is equal or greater than 24.
1306 get_paint_state
1308 Returns paint state value on of ps:: constants - "ps::Disabled" if
1309 the object is in the disabled state, "ps::Enabled" for the enabled
1310 state, "ps::Information" for the information state.
1311 For brevity, mb::Disabled is equal to 0 so this allows for simple
1313 boolean testing whether one can get/set graphical properties on an
1314 object.
1315 See "Graphic context and canvas" for more.
1317 get_physical_palette
1319 Returns an anonymous array of integers, in (R,G,B) format, every
1320 color entry described by three values, in range 0 - 255.
1321 The physical palette array is non-empty only on paletted graphic
1323 devices, the true color devices return an empty array.
1324 The physical palette reflects the solid colors currently available
1326 to all programs in the system. The information is volatile if the
1327 system palette can change colors, since any other application may
1328 change the system colors at any moment.
1329 get_text_width TEXT, ADD_OVERHANG = 0
1331 Returns TEXT string width if it would be drawn using currently
1332 selected font.
1333 If ADD_OVERHANG is 1, the first character's absolute A value and
1335 the last character's absolute C value are added to the string if
1336 they are negative.
1337 See more on ABC values at "Font ABC metrics".
1339 Context used: font
1341 get_text_box TEXT
1343 Returns TEXT string extensions if it would be drawn using currently
1344 selected font.
1345 The result is an anonymous array of 5 points ( 5 integer pairs in
1347 (X,Y) format). These 5 points are offsets for the following string
1348 extents, given the string is plotted at (0,0):
1349 1: start of string at ascent line ( top left )
1351 2: start of string at descent line ( bottom left )
1353 3: end of string at ascent line ( top right )
1355 4: end of string at descent line ( bottom right )
1357 5: concatenation point
1359 The concatenation point coordinates (XC,YC) are coordinated passed
1361 to consequent text_out() call so the conjoint string would plot as
1362 if it was a part of TEXT. Depending on the value of the
1363 "textOutBaseline" property, the concatenation point is located
1364 either on the baseline or on the descent line.
1365 Context used: font, textOutBaseline
1367 1 3 3 4
1369 ** ****
1370 * * *
1371 *** ***
1372 * * *
1373 **** **
1374 2 4 1 2
1375 render_glyph INDEX, %OPTIONS
1377 Returns glyph representation as an outline. The outline is an
1378 integer array, formed as a set of plotting commands. Each commnds
1379 is a "ggo::" constant, followed by number of points, followed by
1380 the 2D point coordinates in 1/64 pixels.
1381 Options recognized:
1383 glyph BOOL
1385 If set, INDEX is treated as the glyph index rather than
1386 character index. Default is false.
1387 hints BOOL
1389 Is set, hinting is enabled. Default is true.
1390 unicode BOOL
1392 If set, INDEX is threated as a utf8 character index, otherwise
1393 a locale-specific index. Default is false.
1394 The "ggo::" commands are:
1396 ggo::Move - move point
1398 ggo::Line - plot line
1399 ggo::Conic - plot 2-degree spline
1400 ggo::Cubic - plot 3-degree spline
1401 render_spline \@VERTICES, %OPTIONS
1403 Renders B-spline curve from set of VERTICES to a polyline with
1404 given options.
1405 The method is internally used by "spline" and "fill_spline", and is
1407 provided for cases when these are insufficient. See description of
1408 options in spline.
1409 text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
1411 Breaks TEXT string in chunks that would fit into WIDTH pixels wide
1412 box.
1413 The break algorithm and its result are governed by OPTIONS integer
1415 value which is a combination of "tw::" constants:
1416 tw::CalcMnemonic
1418 Use 'hot key' semantics, when a character preceded by ~ has
1419 special meaning - it gets underlined. If this bit is set, the
1420 first tilde character used as an escapement is not calculated,
1421 and never appeared in the result apart from the escaped
1422 character.
1423 tw::CollapseTilde
1425 In addition to tw::CalcMnemonic, removes '~' character from the
1426 resulting chunks.
1427 tw::CalcTabs
1429 If set, calculates a tab ('\t') character as TAB_INDENT times
1430 space characters.
1431 tw::ExpandTabs
1433 If set, expands tab ('\t') character as TAB_INDENT times space
1434 characters.
1435 tw::BreakSingle
1437 Defines procedure behavior when the text cannot be fit in
1438 WIDTH, does not affect anything otherwise.
1439 If set, returns an empty array. If unset, returns a text
1441 broken by minimum number of characters per chunk. In the
1442 latter case, the width of the resulting text blocks will exceed
1443 WIDTH.
1444 tw::NewLineBreak
1446 Forces new chunk after a newline character ('\n') is met. If
1447 UTF8 text is passed, unicode line break characters 0x2028 and
1448 0x2029 produce same effect as the newline character.
1449 tw::SpaceBreak
1451 Forces new chunk after a space character (' ') or a tab
1452 character ('\t') are met.
1453 tw::ReturnChunks
1455 Defines the result of text_wrap() function.
1456 If set, the array consists of integer pairs, each consists of a
1458 text offset within TEXT and a its length.
1459 If unset, the resulting array consists from text chunks.
1461 tw::ReturnLines
1463 Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1464 tw::WordBreak
1466 If unset, the TEXT breaks as soon as the chunk width exceeds
1467 WIDTH. If set, tries to keep words in TEXT so they do not
1468 appear in two chunks, e.g. breaks TEXT by words, not by
1469 characters.
1470 tw::ReturnFirstLineLength
1472 If set, "text_wrap" proceeds until the first line is wrapped,
1473 either by width or ( if specified ) by break characters.
1474 Returns length of the resulting line. Used for efficiency when
1475 the reverse function to "get_text_width" is needed.
1476 If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1478 the last scalar in the array result is a special hash reference.
1479 The hash contains extra information regarding the 'hot key'
1480 underline position - it is assumed that '~' - escapement denotes an
1481 underlined character. The hash contains the following keys:
1482 tildeLine
1484 Chunk index that contains the escaped character. Set to undef
1485 if no ~ - escapement was found. The other hash information is
1486 not relevant in this case.
1487 tildeStart
1489 Horizontal offset of a beginning of the line that underlines
1490 the escaped character.
1491 tildeEnd
1493 Horizontal offset of an end of the line that underlines the
1494 escaped character.
1495 tildeChar
1497 The escaped character.
1498 Context used: font
1500
1502 Dmitry Karasik, <dmitry@karasik.eu.org>.
1503
1505 Prima, Prima::Object, Prima::Image, Prima::Region,
1506 Prima::Drawable::Path
1507perl v5.30.0 2019-08-21 pod::Prima::Drawable(3)