1pod::Prima::Drawable(3)User Contributed Perl Documentatiopnod::Prima::Drawable(3)
2
3
4

NAME

6       Prima::Drawable - 2-D graphic interface
7

SYNOPSIS

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

DESCRIPTION

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

USAGE

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
41   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
48       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
56          $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
65       ( 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
69       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
76          $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
87       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
92       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
103          $d = Prima::Image-> create( width => 10000, height => 10000);
104          $d-> begin_paint;
105          $x = $d-> get_text_width('A');
106          $d-> end_paint;
107
108       is much more 'expensive' than
109
110          $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
115       for the obvious reasons.
116
117       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
121   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
128       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
138        11111000 11111000 11111000
139        --R----- --G----- --B-----
140
141       that equals to 0xf8f8f8, not 0xffffff ( See Prima::gp-problems for
142       inevident graphic issues discussion ).
143
144       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
150       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
157         $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
164       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
169         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
187       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
192       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
203       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
209   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
216       This means that the following code
217
218           $bitmap-> color(0);
219           $bitmap-> line(0,0,100,100);
220           $target-> color(cl::Green);
221           $target-> put_image(0,0,$bitmap);
222
223       produces a green line on $target.
224
225       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
233   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
238       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
242       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
248       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
252       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
257                       height - internal_leading
258             size =  --------------------------- * 72.27
259                            resolution
260
261           That differs from some other system representations: Win32, for
262           example, rounds 72.27 constant to 72.
263
264       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
270       style
271           A combination of "fs::" ( font style ) constants. The constants
272           hight
273
274              fs::Normal
275              fs::Bold
276              fs::Thin
277              fs::Italic
278              fs::Underlined
279              fs::StruckOut
280              fs::Outline
281
282           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
286       pitch
287           A one of three constants:
288
289              fp::Default
290              fp::Fixed
291              fp::Variable
292
293           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
299       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
304       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
310           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
314           Unix systems and the toolkit PostScript interface usually provide
315           the following encodings:
316
317              iso8859-1
318              iso8859-2
319              ... other iso8859 ...
320              fontspecific
321
322           Win32 returns the literal strings like
323
324              Western
325              Baltic
326              Cyrillic
327              Hebrew
328              Symbol
329
330       A hash that "::font" returns, is a tied hash, whose keys are also
331       available as separate properties.  For example,
332
333          $x = $d-> font-> {style};
334
335       is equivalent to
336
337          $x = $d-> font-> style;
338
339       While the latter gives nothing but the arguable coding convenience, its
340       usage in set-call is much more usable:
341
342          $d-> font-> style( fs::Bold);
343
344       instead of
345
346          my %temp = %{$d-> font};
347          $temp{ style} = fs::Bold;
348          $d-> font( \%temp);
349
350       The properties of a font tied hash are also accessible through set()
351       call, like in Prima::Object:
352
353          $d-> font-> style( fs::Bold);
354          $d-> font-> width( 10);
355
356       is adequate to
357
358          $d-> font-> set(
359             style => fs::Bold,
360             width => 10,
361          );
362
363       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
367       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
372       "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
378       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
384       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
391       ascent
392           Number of pixels between a glyph baseline and descent line.
393
394       descent
395           Number of pixels between a glyph baseline and descent line.
396
397       internalLeading
398           Number of pixels between ascent and internal leading lines.
399           Negative if the ascent line is below the internal leading line.
400
401       externalLeading
402           Number of pixels between ascent and external leading lines.
403           Negative if the ascent line is above the external leading line.
404
405                     ------------- external leading line
406
407                $    ------------- ascent line
408               $ $
409                     ------------- internal leading line
410                $
411               $$$
412              $   $
413             $     $       $
414             $$$$$$$    $$$
415             $     $   $   $
416             $     $   $   $
417             $     $    $$$   ---- baseline
418                           $
419                            $
420                            $
421                        $$$$  ---- descent line
422
423       weight
424           A font designed weight. Can be one of
425
426              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
436           constants.
437
438       maximalWidth
439           Maximal extent of a glyph in pixels. Equals to width in monospaced
440           fonts.
441
442       xDeviceRes
443           Designed horizontal font resolution in dpi.
444
445       yDeviceRes
446           Designed vertical font resolution in dpi.
447
448       firstChar
449           Index of the first glyph present in a font.
450
451       lastChar
452           Index of the last glyph present in a font.
453
454       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
458       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
462   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
467           .  .     .  .      .  .        .  .
468           .  .     $$$.      .  .        .  .
469           .  .   $$.  $      .  .        .  .
470           .  .   $$.  .      .  .     $$ .  .
471           . $$$$$$$$$$.      .  .$$$$$   .  .
472           .  .  $$ .  .      .  $    $$  .  .
473           .  . $$  .  .      .  .$$$$$   .  .
474           .  . $$  .  .      .  .    $$  .  .
475           .  .$$   .  .      .  . $$$ $$$.  .
476           $$ .$$   .  .      .  $       $$  .
477           .$$$     .  .      .  .$$$$$$$$.  .
478           .  .     .  .      .  .        .  .
479           <A>.     .<C>      <A>.        .<C>
480           .<-.--B--.->.      .  .<--B--->.  .
481
482             A = -3                A = 3
483             B = 13                B = 10
484             C = -3                C = 3
485
486       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
492       ABC metrics returned by the get_font_abc() method.
493
494       Corresponding vertical metrics, called in Prima "DEF" metrics, are
495       returned by the get_font_def() method.
496
497   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
502       The toolkit defines the following operations:
503
504          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
523       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
528       The raster operations apply to all graphic primitives except SetPixel.
529
530       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
534       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
538          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
551       and set of constants to apply a constant source and destination alpha
552       to override the existing alpha channel, if any:
553
554          rop::SrcAlpha
555          rop::SrcAlphaShift
556          rop::DstAlpha
557          rop::DstAlphaShift
558
559       To override the alpha channel(s) combine the rop constant using this
560       formula:
561
562          $rop = rop::XXX |
563             rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
564             rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )
565
566       Also, function "rop::blend($alpha)" creates a rop constant for simple
567       blending of two images by the following formula:
568
569          $dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255
570
571       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
577   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
582       All graphic primitives use inclusive-inclusive boundaries.  For
583       example,
584
585          $d-> bar( 0, 0, 1, 1);
586
587       plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).
588
589       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
595       As noted before, these three properties can not be used in when an
596       object is in its disabled state.
597

API

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
605       color COLOR
606           Reflects foreground color in the graphic context. All drawing
607           routines use this property value.
608
609       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
615              $d-> clipRect( 1, 1, 2, 2);
616              $d-> bar( 0, 0, 1, 1);
617
618           thus affects only one pixel at (1,1).
619
620           Set-call discards the previous "::region" value.
621
622           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
626       fillWinding BOOLEAN
627           Affects filling style of complex polygonal shapes filled by
628           "fillpoly".  If 1, the filled shape contains no holes; otherwise,
629           holes are present where the shape edges cross.
630
631           Default value: false
632
633       fillPattern ( [ @PATTERN ] ) or ( fp::XXX )
634           Selects 8x8 fill pattern that affects primitives that plot filled
635           shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(),
636           fill_sector(), floodfill().
637
638           Accepts either a "fp::" constant or a reference to an array of 8
639           integers, each representing 8 bits of each line in a pattern, where
640           the first integer is the topmost pattern line, and the bit 0x80 is
641           the leftmost pixel in the line.
642
643           There are some predefined patterns, that can be referred via "fp::"
644           constants:
645
646             fp::Empty
647             fp::Solid
648             fp::Line
649             fp::LtSlash
650             fp::Slash
651             fp::BkSlash
652             fp::LtBkSlash
653             fp::Hatch
654             fp::XHatch
655             fp::Interleave
656             fp::WideDot
657             fp::CloseDot
658             fp::SimpleDots
659             fp::Borland
660             fp::Parquet
661
662           ( the actual patterns are hardcoded in primguts.c ) The default
663           pattern is fp::Solid.
664
665           An example below shows encoding of fp::Parquet pattern:
666
667              # 76543210
668                84218421  Hex
669
670              0  $ $   $  51
671              1   $   $   22
672              2    $ $ $  15
673              3 $   $     88
674              4  $   $ $  45
675              5   $   $   22
676              6  $ $ $    54
677              7 $   $     88
678
679              $d-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]);
680
681           On a get-call always returns an array, never a "fp::" constant.
682
683       fillPatternOffset X, Y
684           Origin coordinates for the "fillPattern", from 0 to 7.
685
686       font \%FONT
687           Manages font context. FONT hash acceptable values are "name",
688           "height", "size", "width", "style" and "pitch".
689
690           Synopsis:
691
692              $d-> font-> size( 10);
693              $d-> font-> name( 'Courier');
694              $d-> font-> set(
695                style => $x-> font-> style | fs::Bold,
696                width => 22
697              );
698
699           See "Fonts" for the detailed descriptions.
700
701           Applies to text_out(), get_text_width(), get_text_box(),
702           get_font_abc(), get_font_def().
703
704       lineEnd VALUE
705           Selects a line ending cap for plotting primitives. VALUE can be one
706           of
707
708             le::Flat
709             le::Square
710             le::Round
711
712           constants. le::Round is the default value.
713
714       lineJoin VALUE
715           Selects a line joining style for polygons. VALUE can be one of
716
717             lj::Round
718             lj::Bevel
719             lj::Miter
720
721           constants. lj::Round is the default value.
722
723       linePattern PATTERN
724           Selects a line pattern for plotting primitives.  PATTERN is either
725           a predefined "lp::" constant, or a string where each even byte is a
726           length of a dash, and each odd byte is a length of a gap.
727
728           The predefined constants are:
729
730               lp::Null           #    ""              /*              */
731               lp::Solid          #    "\1"            /* ___________  */
732               lp::Dash           #    "\x9\3"         /* __ __ __ __  */
733               lp::LongDash       #    "\x16\6"        /* _____ _____  */
734               lp::ShortDash      #    "\3\3"          /* _ _ _ _ _ _  */
735               lp::Dot            #    "\1\3"          /* . . . . . .  */
736               lp::DotDot         #    "\1\1"          /* ............ */
737               lp::DashDot        #    "\x9\6\1\3"     /* _._._._._._  */
738               lp::DashDotDot     #    "\x9\3\1\3\1\3" /* _.._.._.._.. */
739
740           Not all systems are capable of accepting user-defined line
741           patterns, and in such situation the "lp::" constants are mapped to
742           the system-defined patterns. In Win9x, for example, lp::DashDotDot
743           is much different from its string definition therefore.
744
745           Default value is lp::Solid.
746
747       lineWidth WIDTH
748           Selects a line width for plotting primitives.  If a VALUE is 0,
749           then a 'cosmetic' pen is used - the thinnest possible line that a
750           device can plot. If a VALUE is greater than 0, then a 'geometric'
751           pen is used - the line width is set in device units.  There is a
752           subtle difference between VALUE 0 and 1 in a way the lines are
753           joined.
754
755           Default value is 0.
756
757       palette [ @PALETTE ]
758           Selects solid colors in a system palette, as many as possible.
759           PALETTE is an array of integer triplets, where each is R, G and B
760           component. The call
761
762              $d-> palette([128, 240, 240]);
763
764           selects a gray-cyan color, for example.
765
766           The return value from get-call is the content of the previous set-
767           call, not the actual colors that were copied to the system palette.
768
769       region OBJECT
770           Selects a clipping region applied to all drawing and painting
771           routines. On setting, the OBJECT is either undef, then the clip
772           region is erased ( no clip ), or a Prima::Image object with a bit
773           depth of 1. The bit mask of OBJECT is applied to the system
774           clipping region. Or, it is a Prima::Region object.  If the OBJECT
775           is smaller than the drawable, its exterior is assigned to clipped
776           area as well.  Discards the previous "::clipRect" value; successive
777           get-calls to "::clipRect" return the boundaries of the region.
778
779           On getting, OBJECT is either undef or Prima::Region object.
780
781           Note: "::region" can not be used while the object is in the paint-
782           disabled state, its context is neither recorded nor used as a
783           template ( see "Graphic context and canvas").
784
785       resolution X, Y
786           A read-only property. Returns horizontal and vertical device
787           resolution in dpi.
788
789       rop OPERATION
790           Selects raster operation that applies to foreground color plotting
791           routines.
792
793           See also: "::rop2", "Raster operations".
794
795       rop2 OPERATION
796           Selects raster operation that applies to background color plotting
797           routines.
798
799           See also: "::rop", "Raster operations".
800
801       textOpaque FLAG
802           If FLAG is 1, then text_out() fills the text background area with
803           "::backColor" property value before drawing the text. Default value
804           is 0, when text_out() plots text only.
805
806           See get_text_box().
807
808       textOutBaseline FLAG
809           If FLAG is 1, then text_out() plots text on a given Y coordinate
810           correspondent to font baseline. If FLAG is 0, a Y coordinate is
811           mapped to font descent line. Default is 0.
812
813       translate X_OFFSET, Y_OFFSET
814           Translates the origin point by X_OFFSET and Y_OFFSET.  Does not
815           affect "::clipRect" and "::region". Not cumulative, so the call
816           sequence
817
818              $d-> translate( 5, 5);
819              $d-> translate( 15, 15);
820
821           is equivalent to
822
823              $d-> translate( 15, 15);
824
825           Note: "::translate" can not be used while the object is in the
826           paint-disabled state, its context is neither recorded nor used as a
827           template ( see "Graphic context and canvas").
828
829   Other properties
830       height HEIGHT
831           Selects the height of a canvas.
832
833       size WIDTH, HEIGHT
834           Selects the extent of a canvas.
835
836       width WIDTH
837           Selects the width of a canvas.
838
839   Graphic primitives methods
840       alpha ALPHA <X1, Y1, X2, Y2>
841           Fills rectangle in the alpha channel, filled with ALPHA value
842           (0-255) within (X1,Y1) - (X2,Y2) extents.  Can be called without
843           parameters, in this case fills all canvas area.
844
845           Has only effect on layered surfaces.
846
847       arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
848           Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
849           from START_ANGLE to END_ANGLE.
850
851           Context used: color, backColor, lineEnd, linePattern, lineWidth,
852           rop, rop2
853
854       bar X1, Y1, X2, Y2
855           Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.
856
857           Context used: color, backColor, fillPattern, fillPatternOffset,
858           rop, rop2
859
860       bars @RECTS
861           Draws a set of filled rectangles.  RECTS is an array of integer
862           quartets in format (X1,Y1,X2,Y2).
863
864           Context used: color, backColor, fillPattern, fillPatternOffset,
865           rop, rop2
866
867       chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
868           Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
869           from START_ANGLE to END_ANGLE and connects its ends with a straight
870           line.
871
872           Context used: color, backColor, lineEnd, linePattern, lineWidth,
873           rop, rop2
874
875       clear <X1, Y1, X2, Y2>
876           Draws rectangle filled with pure background color within (X1,Y1) -
877           (X2,Y2) extents.  Can be called without parameters, in this case
878           fills all canvas area.
879
880           Context used: backColor, rop2
881
882       draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default,
883       TAB_INDENT = 1 ]
884           Draws several lines of text one under another with respect to align
885           and break rules, specified in FLAGS and TAB_INDENT tab character
886           expansion.
887
888           "draw_text" is a convenience wrapper around "text_wrap" for drawing
889           the wrapped text, and also provides the tilde ( ~ )- character
890           underlining support.
891
892           The FLAGS is a combination of the following constants:
893
894             dt::Left                  - text is aligned to the left boundary
895             dt::Right                 - text is aligned to the right boundary
896             dt::Center                - text is aligned horizontally in center
897             dt::Top                   - text is aligned to the upper boundary
898             dt::Bottom                - text is aligned to the lower boundary
899             dt::VCenter               - text is aligned vertically in center
900             dt::DrawMnemonic          - tilde-escapement and underlining is used
901             dt::DrawSingleChar        - sets tw::BreakSingle option to
902                                         Prima::Drawable::text_wrap call
903             dt::NewLineBreak          - sets tw::NewLineBreak option to
904                                         Prima::Drawable::text_wrap call
905             dt::SpaceBreak            - sets tw::SpaceBreak option to
906                                         Prima::Drawable::text_wrap call
907             dt::WordBreak             - sets tw::WordBreak option to
908                                         Prima::Drawable::text_wrap call
909             dt::ExpandTabs            - performs tab character ( \t ) expansion
910             dt::DrawPartial           - draws the last line, if it is visible partially
911             dt::UseExternalLeading    - text lines positioned vertically with respect to
912                                         the font external leading
913             dt::UseClip               - assign ::clipRect property to the boundary rectangle
914             dt::QueryLinesDrawn       - calculates and returns number of lines drawn
915                                         ( contrary to dt::QueryHeight )
916             dt::QueryHeight           - if set, calculates and returns vertical extension
917                                         of the lines drawn
918             dt::NoWordWrap            - performs no word wrapping by the width of the boundaries
919             dt::WordWrap              - performs word wrapping by the width of the boundaries
920             dt::BidiText              - use bidirectional formatting, if available
921             dt::Default               - dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs|
922                                         dt::UseExternalLeading
923
924           Context used: color, backColor, font, rop, textOpaque,
925           textOutBaseline
926
927       ellipse X, Y, DIAMETER_X, DIAMETER_Y
928           Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y
929           axis.
930
931           Context used: color, backColor, linePattern, lineWidth, rop, rop2
932
933       fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
934           Fills a chord outline with center in X, Y and DIAMETER_X and
935           DIAMETER_Y axis from START_ANGLE to END_ANGLE (see chord()).
936
937           Context used: color, backColor, fillPattern, fillPatternOffset,
938           rop, rop2
939
940       fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y
941           Fills an elliptical outline with center in X, Y and DIAMETER_X and
942           DIAMETER_Y axis.
943
944           Context used: color, backColor, fillPattern, fillPatternOffset,
945           rop, rop2
946
947       fillpoly \@POLYGON
948           Fills a polygonal area defined by POLYGON set of points.  POLYGON
949           must present an array of integer pair in (X,Y) format.  Example:
950
951              $d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle
952
953           Context used: color, backColor, fillPattern, fillPatternOffset,
954           rop, rop2, fillWinding
955
956           Returns success flag; if failed, $@ contains the error.
957
958           See also: polyline().
959
960       fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
961           Fills a sector outline with center in X, Y and DIAMETER_X and
962           DIAMETER_Y axis from START_ANGLE to END_ANGLE (see sector()).
963
964           Context used: color, backColor, fillPattern, fillPatternOffset,
965           rop, rop2
966
967       fill_spline \@VERTICES, %OPTIONS
968           Fills a polygonal area defined by a curve, projected by applying
969           B-spline curve based on set of VERTICES. VERTICES must present an
970           array of integer pair in (X,Y) format.  Example:
971
972              $d-> fill_spline([ 0, 0, 15, 20, 30, 0]);
973
974           Context used: color, backColor, fillPattern, fillPatternOffset,
975           rop, rop2
976
977           Returns success flag; if failed, $@ contains the error.
978
979           See also: spline, render_spline
980
981       flood_fill X, Y, COLOR, SINGLEBORDER = 1
982           Fills an area of the canvas in current fill context.  The area is
983           assumed to be bounded as specified by the SINGLEBORDER parameter.
984           SINGLEBORDER can be 0 or 1.
985
986           SINGLEBORDER = 0: The fill area is bounded by the color specified
987           by the COLOR parameter.
988
989           SINGLEBORDER = 1: The fill area is defined by the color that is
990           specified by COLOR.  Filling continues outward in all directions as
991           long as the color is encountered. This style is useful for filling
992           areas with multicolored boundaries.
993
994           Context used: color, backColor, fillPattern, fillPatternOffset,
995           rop, rop2
996
997       line X1, Y1, X2, Y2
998           Plots a straight line from (X1,Y1) to (X2,Y2).
999
1000           Context used: color, backColor, linePattern, lineWidth, rop, rop2
1001
1002       lines \@LINES
1003           LINES is an array of integer quartets in format (X1,Y1,X2,Y2).
1004           lines() plots a straight line per quartet.
1005
1006           Context used: color, backColor, linePattern, lineWidth, rop, rop2
1007
1008           Returns success flag; if failed, $@ contains the error.
1009
1010       new_gradient
1011           Returns a new gradient object. See Prima::Drawable::Gradient for
1012           usage and details.
1013
1014       new_path
1015           Returns a new path object. See Prima::Drawable::Path for usage and
1016           details.
1017
1018       pixel X, Y, <COLOR>
1019           ::pixel is a property - on set-call it changes the pixel value at
1020           (X,Y) to COLOR, on get-call ( without COLOR ) it does return a
1021           pixel value at (X,Y).
1022
1023           No context is used.
1024
1025       polyline \@POLYGON
1026           Draws a polygonal area defined by POLYGON set of points.  POLYGON
1027           must present an array of integer pair in (X,Y) format.
1028
1029           Context used: color, backColor, linePattern, lineWidth, lineJoin,
1030           lineEnd, rop, rop2
1031
1032           Returns success flag; if failed, $@ contains the error.
1033
1034           See also: fillpoly().
1035
1036       put_image X, Y, OBJECT, [ ROP ]
1037           Draws an OBJECT at coordinates (X,Y). OBJECT must be Prima::Image,
1038           Prima::Icon or Prima::DeviceBitmap. If ROP raster operation is
1039           specified, it is used. Otherwise, value of "::rop" property is
1040           used.
1041
1042           Returns success flag; if failed, $@ contains the error.
1043
1044           Context used: rop; color and backColor for a monochrome
1045           DeviceBitmap
1046
1047       put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH,
1048       DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP
1049           Copies a OBJECT from a source rectangle into a destination
1050           rectangle, stretching or compressing the OBJECT to fit the
1051           dimensions of the destination rectangle, if necessary.  The source
1052           rectangle starts at (X_FROM,Y_FROM), and is SRC_WIDTH pixels wide
1053           and SRC_HEIGHT pixels tall.  The destination rectangle starts at
1054           (X,Y), and is abs(DEST_WIDTH) pixels wide and abs(DEST_HEIGHT)
1055           pixels tall.  If DEST_WIDTH or DEST_HEIGHT are negative, a
1056           mirroring by respective axis is performed.
1057
1058           OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1059
1060           No context is used, except color and backColor for a monochrome
1061           DeviceBitmap
1062
1063           Returns success flag; if failed, $@ contains the error.
1064
1065       rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]
1066           Draws 3d-shaded rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1067           line width and LIGHT_COLOR and DARK_COLOR colors. If BACK_COLOR is
1068           specified, paints an inferior rectangle with it, otherwise the
1069           inferior rectangle is not touched.
1070
1071           Context used: rop; color and backColor for a monochrome
1072           DeviceBitmap
1073
1074       rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]
1075           Draws a marquee rectangle in boundaries X1,Y1 - X2,Y2 with WIDTH
1076           line width.
1077
1078           No context is used.
1079
1080       rectangle X1, Y1, X2, Y2
1081           Plots a rectangle with (X1,Y1) - (X2,Y2) extents.
1082
1083           Context used: color, backColor, linePattern, lineWidth, rop, rop2
1084
1085       sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE
1086           Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axis
1087           from START_ANGLE to END_ANGLE and connects its ends and (X,Y) with
1088           two straight lines.
1089
1090           Context used: color, backColor, lineEnd, linePattern, lineWidth,
1091           rop, rop2
1092
1093       spline \@VERTICES, %OPTIONS
1094           Draws a B-spline curve defined by set of VERTICES control points.
1095           VERTICES must present an array of integer pair in (X,Y) format.  If
1096           the first and the last vertices point to the same point, draws
1097           closed spline shape ( Note - by adding degree minus two points to
1098           the set; this is important if "weight" or "knots" are specificed).
1099
1100           The following options are supported:
1101
1102           degree INTEGER = 2
1103               The B-spline degree. Default is 2 (quadratic). Number of points
1104               supplied must be at least degree plus one.
1105
1106           knots \@INTEGERS
1107               Array of integers, number of points plus degree plus one, which
1108               makes the result a Bezier curve. By default, if the shape is
1109               opened (i.e. first and last points are different), is set to a
1110               clamped array, so that the first and last points of the final
1111               curve match the first and the last control points. If the shape
1112               is closed, set to an unclamped array, so that no control points
1113               lie directly on the curve.
1114
1115           precision INTEGER = 24
1116               Defines number of steps to split the curve into. The value is
1117               multiplied to the number of points and the result is used as
1118               number of steps.
1119
1120           weight \@INTEGERS = [ 1, 1, 1, ... ]
1121               Array of integers, one for each point supplied. Assigning these
1122               can be used to convert B-spline into a NURBS. By default set of
1123               ones.
1124
1125           Context used: color, backColor, linePattern, lineWidth, lineEnd,
1126           rop, rop2
1127
1128           See also: fill_spline, render_spline.
1129
1130       stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]
1131           Copies a OBJECT into a destination rectangle, stretching or
1132           compressing the OBJECT to fit the dimensions of the destination
1133           rectangle, if necessary.  If DEST_WIDTH or DEST_HEIGHT are
1134           negative, a mirroring is performed.  The destination rectangle
1135           starts at (X,Y) and is DEST_WIDTH pixels wide and DEST_HEIGHT
1136           pixels tall.
1137
1138           If ROP raster operation is specified, it is used. Otherwise, value
1139           of "::rop" property is used.
1140
1141           OBJECT must be Prima::Image, Prima::Icon or Prima::DeviceBitmap.
1142
1143           Returns success flag; if failed, $@ contains the error.
1144
1145           Context used: rop
1146
1147       text_out TEXT, X, Y
1148           Draws TEXT string at (X,Y).
1149
1150           Returns success flag; if failed, $@ contains the error.
1151
1152           Context used: color, backColor, font, rop, textOpaque,
1153           textOutBaseline
1154
1155   Methods
1156       begin_paint
1157           Enters the enabled ( active paint ) state, returns success flag; if
1158           failed, $@ contains the error.  Once the object is in enabled
1159           state, painting and drawing methods can perform write operations on
1160           a canvas.
1161
1162           See also: "end_paint", "begin_paint_info", "Graphic context and
1163           canvas"
1164
1165       begin_paint_info
1166           Enters the information state, returns success flag; if failed, $@
1167           contains the error.  The object information state is same as
1168           enabled state ( see "begin_paint"), except painting and drawing
1169           methods do not change the object canvas.
1170
1171           See also: "end_paint_info", "begin_paint", "Graphic context and
1172           canvas"
1173
1174       end_paint
1175           Exits the enabled state and returns the object to a disabled state.
1176
1177           See also: "begin_paint", "Graphic context and canvas"
1178
1179       end_paint_info
1180           Exits the information state and returns the object to a disabled
1181           state.
1182
1183           See also: "begin_paint_info", "Graphic context and canvas"
1184
1185       font_match \%SOURCE, \%DEST, PICK = 1
1186           Performs merging of two font hashes, SOURCE and DEST.  Returns the
1187           merge result. If PICK is true, matches the result with a system
1188           font repository.
1189
1190           Called implicitly by "::font" on set-call, allowing the following
1191           example to work:
1192
1193              $d-> font-> set( size => 10);
1194              $d-> font-> set( style => fs::Bold);
1195
1196           In the example, the hash 'style => fs::Bold' does not overwrite the
1197           previous font context ( 'size => 10' ) but gets added to it ( by
1198           font_match()), providing the resulting font with both font
1199           properties set.
1200
1201       fonts <FAMILY = "", ENCODING = "">
1202           Member of "Prima::Application" and "Prima::Printer", does not
1203           present in "Prima::Drawable".
1204
1205           Returns an array of font metric hashes for a given font FAMILY and
1206           ENCODING.  Every hash has full set of elements described in
1207           "Fonts".
1208
1209           If called without parameters, returns an array of same hashes where
1210           each hash represents a member of font family from every system font
1211           set. It this special case, each font hash contains additional
1212           "encodings" entry, which points to an array of encodings available
1213           for the font.
1214
1215           If called with FAMILY parameter set but no ENCODING is set,
1216           enumerates all combinations of fonts with all available encodings.
1217
1218           If called with FAMILY set to an empty string, but ENCODING
1219           specified, returns only fonts that can be displayed with the
1220           encoding.
1221
1222           Example:
1223
1224             print sort map {"$_->{name}\n"} @{$::application-> fonts};
1225
1226       get_bpp
1227           Returns device color depth. 1 is for black-and-white monochrome, 24
1228           for true color, etc.
1229
1230       get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1231           Returns ABC font metrics for the given range, starting at
1232           FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the
1233           default range ( 0 and 255 ) is assumed. UNICODE boolean flag is
1234           responsible of representation of characters in 127-255 range.  If
1235           0, the default, encoding-dependent characters are assumed.  If 1,
1236           the U007F-U00FF glyphs from Latin-1 set are used.
1237
1238           The result is an integer array reference, where every character
1239           glyph is referred by three integers, each triplet containing A, B
1240           and C values.
1241
1242           For detailed explanation of ABC meaning, see "Font ABC metrics";
1243
1244           Context used: font
1245
1246       get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0
1247           Same as "get_font_abc", but for vertical mertics. Is expensive on
1248           bitmap fonts, because to find out the correct values Prima has to
1249           render glyphs on bitmaps and scan for black and white pixels.
1250
1251           Vector fonts are not subject to this, and the call is as effective
1252           as "get_font_abc".
1253
1254       get_font_ranges
1255           Returns array of integer pairs denoting unicode indices of glyphs
1256           covered by the currently selected font. Each pair is the first and
1257           the last index of a contiguous range.
1258
1259           Context used: font
1260
1261       get_nearest_color COLOR
1262           Returns a nearest possible solid color in representation of object-
1263           bound graphic device. Always returns same color if the device bit
1264           depth is equal or greater than 24.
1265
1266       get_paint_state
1267           Returns paint state value on of ps:: constants - "ps::Disabled" if
1268           the object is in the disabled state, "ps::Enabled" for the enabled
1269           state, "ps::Information" for the information state.
1270
1271           For brevity, mb::Disabled is equal to 0 so this allows for simple
1272           boolean testing whether one can get/set graphical properties on an
1273           object.
1274
1275           See "Graphic context and canvas" for more.
1276
1277       get_physical_palette
1278           Returns an anonymous array of integers, in (R,G,B) format, every
1279           color entry described by three values, in range 0 - 255.
1280
1281           The physical palette array is non-empty only on paletted graphic
1282           devices, the true color devices return an empty array.
1283
1284           The physical palette reflects the solid colors currently available
1285           to all programs in the system. The information is volatile if the
1286           system palette can change colors, since any other application may
1287           change the system colors at any moment.
1288
1289       get_text_width TEXT, ADD_OVERHANG = 0
1290           Returns TEXT string width if it would be drawn using currently
1291           selected font.
1292
1293           If ADD_OVERHANG is 1, the first character's absolute A value and
1294           the last character's absolute C value are added to the string if
1295           they are negative.
1296
1297           See more on ABC values at "Font ABC metrics".
1298
1299           Context used: font
1300
1301       get_text_box TEXT
1302           Returns TEXT string extensions if it would be drawn using currently
1303           selected font.
1304
1305           The result is an anonymous array of 5 points ( 5 integer pairs in
1306           (X,Y) format). These 5 points are offsets for the following string
1307           extents, given the string is plotted at (0,0):
1308
1309           1: start of string at ascent line ( top left )
1310
1311           2: start of string at descent line ( bottom left )
1312
1313           3: end of string at ascent line ( top right )
1314
1315           4: end of string at descent line ( bottom right )
1316
1317           5: concatenation point
1318
1319           The concatenation point coordinates (XC,YC) are coordinated passed
1320           to consequent text_out() call so the conjoint string would plot as
1321           if it was a part of TEXT. Depending on the value of the
1322           "textOutBaseline" property, the concatenation point is located
1323           either on the baseline or on the descent line.
1324
1325           Context used: font, textOutBaseline
1326
1327                 1      3         3         4
1328                    **               ****
1329                      *               *  *
1330                    ***               ***
1331                   *  *               *
1332                    ****               **
1333                 2       4         1        2
1334
1335       render_spline \@VERTICES, %OPTIONS
1336           Renders B-spline curve from set of VERTICES to a polyline with
1337           given options.
1338
1339           The method is internally used by "spline" and "fill_spline", and is
1340           provided for cases when these are insufficient. See description of
1341           options in spline.
1342
1343       text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8
1344           Breaks TEXT string in chunks that would fit into WIDTH pixels wide
1345           box.
1346
1347           The break algorithm and its result are governed by OPTIONS integer
1348           value which is a combination of "tw::" constants:
1349
1350           tw::CalcMnemonic
1351               Use 'hot key' semantics, when a character preceded by ~ has
1352               special meaning - it gets underlined. If this bit is set, the
1353               first tilde character used as an escapement is not calculated,
1354               and never appeared in the result apart from the escaped
1355               character.
1356
1357           tw::CollapseTilde
1358               In addition to tw::CalcMnemonic, removes '~' character from the
1359               resulting chunks.
1360
1361           tw::CalcTabs
1362               If set, calculates a tab ('\t') character as TAB_INDENT times
1363               space characters.
1364
1365           tw::ExpandTabs
1366               If set, expands tab ('\t') character as TAB_INDENT times space
1367               characters.
1368
1369           tw::BreakSingle
1370               Defines procedure behavior when the text cannot be fit in
1371               WIDTH, does not affect anything otherwise.
1372
1373               If set, returns an empty array.  If unset, returns a text
1374               broken by minimum number of characters per chunk.  In the
1375               latter case, the width of the resulting text blocks will exceed
1376               WIDTH.
1377
1378           tw::NewLineBreak
1379               Forces new chunk after a newline character ('\n') is met.  If
1380               UTF8 text is passed, unicode line break characters 0x2028 and
1381               0x2029 produce same effect as the newline character.
1382
1383           tw::SpaceBreak
1384               Forces new chunk after a space character (' ') or a tab
1385               character ('\t') are met.
1386
1387           tw::ReturnChunks
1388               Defines the result of text_wrap() function.
1389
1390               If set, the array consists of integer pairs, each consists of a
1391               text offset within TEXT and a its length.
1392
1393               If unset, the resulting array consists from text chunks.
1394
1395           tw::ReturnLines
1396               Equals to 0, is a mnemonic to an unset tw::ReturnChunks.
1397
1398           tw::WordBreak
1399               If unset, the TEXT breaks as soon as the chunk width exceeds
1400               WIDTH.  If set, tries to keep words in TEXT so they do not
1401               appear in two chunks, e.g. breaks TEXT by words, not by
1402               characters.
1403
1404           tw::ReturnFirstLineLength
1405               If set, "text_wrap" proceeds until the first line is wrapped,
1406               either by width or ( if specified ) by break characters.
1407               Returns length of the resulting line. Used for efficiency when
1408               the reverse function to "get_text_width" is needed.
1409
1410           If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then
1411           the last scalar in the array result is a special hash reference.
1412           The hash contains extra information regarding the 'hot key'
1413           underline position - it is assumed that '~' - escapement denotes an
1414           underlined character. The hash contains the following keys:
1415
1416           tildeLine
1417               Chunk index that contains the escaped character.  Set to undef
1418               if no ~ - escapement was found.  The other hash information is
1419               not relevant in this case.
1420
1421           tildeStart
1422               Horizontal offset of a beginning of the line that underlines
1423               the escaped character.
1424
1425           tildeEnd
1426               Horizontal offset of an end of the line that underlines the
1427               escaped character.
1428
1429           tildeChar
1430               The escaped character.
1431
1432           Context used: font
1433

AUTHOR

1435       Dmitry Karasik, <dmitry@karasik.eu.org>.
1436

SEE ALSO

1438       Prima, Prima::Object, Prima::Image, Prima::Region,
1439       Prima::Drawable::Path
1440
1441
1442
1443perl v5.28.0                      2017-05-15           pod::Prima::Drawable(3)
Impressum