.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "pod::Prima::Drawable 3" .TH pod::Prima::Drawable 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Prima::Drawable \- 2\-D graphic interface .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 7 \& if ( $object\-> isa(\*(AqPrima::Drawable\*(Aq)) { \& $object\-> begin_paint; \& $object\-> color( cl::Black); \& $object\-> line( 100, 100, 200, 200); \& $object\-> ellipse( 100, 100, 200, 200); \& $object\-> end_paint; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Prima::Drawable is a descendant of Prima::Component. It provides access to the object-bound graphic context and canvas through its methods and properties. The Prima::Drawable descendants Prima::Widget, Prima::Image, Prima::DeviceBitmap and Prima::Printer are backed by system-dependent routines that allow drawing and painting on the system objects. .SH "USAGE" .IX Header "USAGE" Prima::Drawable, as well as its ancestors Prima::Component and Prima::Object, is never used directly, because Prima::Drawable class by itself provides only the interface. It provides a three-state object access \- when drawing and painting is enabled, when these are disabled, and the information acquisition state. By default, the object is created in paint-disabled state. To switch to the enabled state, \fIbegin_paint()\fR method is used. Once in the enabled state, the object drawing and painting methods apply to the object-bound canvas. To return to the disabled state, \fIend_paint()\fR method is called. The information state can be managed by using \&\fIbegin_paint_info()\fR and \fIend_paint_info()\fR methods pair. An object cannot be triggered from the information state to the enabled state ( and vice versa ) directly. These states differ on how do they apply to a graphic context and a canvas. .SS "Graphic context and canvas" .IX Subsection "Graphic context and canvas" The graphic context is the set of variables, that control how exactly graphic primitives are rendered. The variable examples are color, font, line width, etc. Another term used here is 'canvas' \- the graphic area of a certain extent, bound to the object, where the drawing and painting methods are applied to. .PP In all three states a graphic context is allowed to be modified, but in different ways. In the disabled state the graphic context values form a template values; when a object enters the information or the enabled state, the values are preserved, but when the object is back to the disabled state, the graphic context is restored to the values last assigned before entering new state. The code example below illustrates the idea: .PP .Vb 8 \& $d = Prima::Drawable\-> create; \& $d\-> lineWidth( 5); \& $d\-> begin_paint_info; \& # lineWidth is 5 here \& $d\-> lineWidth( 1); \& # lineWidth is 1 \& $d\-> end_paint_info; \& # lineWidth is 5 again .Ve .PP ( Note: \f(CW\*(C`::region\*(C'\fR, \f(CW\*(C`::clipRect\*(C'\fR and \f(CW\*(C`::translate\*(C'\fR properties are exceptions. They can not be used in the disabled state; their values are neither recorded nor used as a template). .PP That is, in disabled state any Drawable maintains only the graphic context. To draw on a canvas, the object must enter the enabled state by calling \fIbegin_paint()\fR. This function can be unsuccessful, because the object binds with system resources during this stage, and might fail. Only after the enabled state is entered, the canvas is accessible: .PP .Vb 10 \& $d = Prima::Image\-> create( width => 100, height => 100); \& if ( $d\-> begin_paint) { \& $d\-> color( cl::Black); \& $d\-> bar( 0, 0, $d\-> size); \& $d\-> color( cl::White); \& $d\-> fill_ellipse( $d\-> width / 2, $d\-> height / 2, 30, 30); \& $d\-> end_paint; \& } else { \& die "can\*(Aqt draw on image:$@"; \& } .Ve .PP Different objects are mapped to different types of canvases \- Prima::Image canvas pertains its content after \fIend_paint()\fR, Prima::Widget maps it to a screen area, which content is of more transitory nature, etc. .PP The information state is as same as the enabled state, but the changes to a canvas are not visible. Its sole purpose is to read, not to write information. Because \fIbegin_paint()\fR requires some amount of system resources, there is a chance that a resource request can fail, for any reason. The \fIbegin_paint_info()\fR requires some resources as well, but usually much less, and therefore if only information is desired, it is usually faster and cheaper to obtain it inside the information state. A notable example is \&\fIget_text_width()\fR method, that returns the length of a text string in pixels. It works in both enabled and information states, but code .PP .Vb 4 \& $d = Prima::Image\-> create( width => 10000, height => 10000); \& $d\-> begin_paint; \& $x = $d\-> get_text_width(\*(AqA\*(Aq); \& $d\-> end_paint; .Ve .PP is much more 'expensive' than .PP .Vb 4 \& $d = Prima::Image\-> create( width => 10000, height => 10000); \& $d\-> begin_paint_info; \& $x = $d\-> get_text_width(\*(AqA\*(Aq); \& $d\-> end_paint_info; .Ve .PP for the obvious reasons. .PP It must be noted that some information methods like \fIget_text_width()\fR work even under the disabled state; the object is switched to the information state implicitly if it is necessary. .SS "Color space" .IX Subsection "Color space" Graphic context and canvas operations rely completely on a system implementation. The internal canvas color representation is therefore system-specific, and usually could not be described in standard definitions. Often the only information available about color space is its color depth. .PP Therefore, all color manipulations, including dithering and antialiasing are subject to system implementation, and can not be controlled from perl code. When a property is set in the object disabled state, it is recorded verbatim; color properties are no exception. After the object switched to the enabled state, a color value is transformed to a system color representation, which might be different from Prima's. For example, if a display color depth is 15 bits, 5 bits for every component, then white color value 0xffffff is mapped to .PP .Vb 2 \& 11111000 11111000 11111000 \& \-\-R\-\-\-\-\- \-\-G\-\-\-\-\- \-\-B\-\-\-\-\- .Ve .PP that equals to 0xf8f8f8, not 0xffffff ( See Prima::gp\-problems for inevident graphic issues discussion ). .PP The Prima::Drawable color format is \s-1RRGGBB\s0, with each component resolution of 8 bit, thus allowing 2^24 color combinations. If the device color space depth is different, the color is truncated or expanded automatically. In case the device color depth is small, dithering algorithms might apply. .PP Note: not only color properties, but all graphic context properties allow all possible values in the disabled state, which transformed into system-allowed values in the enabled and the information states. This feature can be used to test if a graphic device is capable of performing certain operations ( for example, if it supports raster operations \- the printers usually do not ). Example: .PP .Vb 6 \& $d\-> begin_paint; \& $d\-> rop( rop::Or); \& if ( $d\-> rop != rop::Or) { # this assertion is always false without \& ... # begin_paint/end_paint brackets \& } \& $d\-> end_paint; .Ve .PP There are ( at least ) two color properties on each drawable \- \&\f(CW\*(C`::color\*(C'\fR and \f(CW\*(C`::backColor\*(C'\fR. The values they operate are integers in the discussed above \s-1RRGGBB\s0 format, however, the toolkit defines some mnemonic color constants: .PP .Vb 10 \& cl::Black \& cl::Blue \& cl::Green \& cl::Cyan \& cl::Red \& cl::Magenta \& cl::Brown \& cl::LightGray \& cl::DarkGray \& cl::LightBlue \& cl::LightGreen \& cl::LightCyan \& cl::LightRed \& cl::LightMagenta \& cl::Yellow \& cl::White \& cl::Gray .Ve .PP As stated before, it is not unlikely that if a device color depth is small, the primitives plotted in particular colors will be drawn with dithered or incorrect colors. This usually happens on paletted displays, with 256 or less colors. .PP There exists two methods that facilitate the correct color representation. The first way is to get as much information as possible about the device. The methods \fIget_nearest_color()\fR and \fIget_physical_palette()\fR provide possibility to avoid mixed colors drawing by obtaining indirect information about solid colors, supported by a device. Another method is to use \f(CW\*(C`::palette\*(C'\fR property. It works by inserting the colors into the system palette, so if an application knows the colors it needs beforehand, it can employ this method \- however this might result in system palette flash when a window focus toggles. .PP Both of these methods are applicable both with drawing routines and image output. An image desired to output with least distortion is advised to export its palette to an output device, because images usually are not subject to automatic dithering algorithms. Prima::ImageViewer module employs this scheme. .SS "Monochrome bitmaps" .IX Subsection "Monochrome bitmaps" A special case of \f(CW\*(C`put_image\*(C'\fR is taken where the object to be drawn is a monochrome DeviceBitmap object. This object doesn't possess the color palette, and is by definition a bitmap, where there are only two values present, 0s and 1s. When it is drawn, 0s are drawn with the color value of the target canvas \&\f(CW\*(C`color\*(C'\fR property, and 1s with \f(CW\*(C`backColor\*(C'\fR. .PP This means that the following code .PP .Vb 4 \& $bitmap\-> color(0); \& $bitmap\-> line(0,0,100,100); \& $target\-> color(cl::Green); \& $target\-> put_image(0,0,$bitmap); .Ve .PP produces a green line on \f(CW$target\fR. .PP When using monochrome bitmaps for logical operations, note that target colors should not be explicit 0 and 0xffffff, nor \f(CW\*(C`cl::Black\*(C'\fR and \f(CW\*(C`cl::White\*(C'\fR, but \&\f(CW\*(C`cl::Clear\*(C'\fR and \f(CW\*(C`cl::Set\*(C'\fR instead. The reason is that on paletted displays, system palette may not necessarily contain the white color under palette index (2^ScreenDepth\-1). \f(CW\*(C`cl::Set\*(C'\fR thus signals that the value should be \*(L"all ones\*(R", no matter what color it represents, because it will be used for logical operations. .SS "Fonts" .IX Subsection "Fonts" Prima maintains its own font naming convention, that usually does not conform to system's. Since its goal is interoperability, it might be so that some system fonts would not be accessible from within the toolkit. .PP Prima::Drawable provides property \f(CW\*(C`::font\*(C'\fR, that accepts/returns a hash, that represents the state of a font in the object-bound graphic context. The font hash keys that are acceptable on set-call are: .IP "name" 4 .IX Item "name" The font name string. If there is no such font, a default font name is used. To select default font, a 'Default' string can be passed with the same result ( unless the system has a font named 'Default', of course). .IP "height" 4 .IX Item "height" An integer value from 1 to \s-1MAX_INT\s0. Specifies the desired extent of a font glyph between descent and ascent lines in pixels. .IP "size" 4 .IX Item "size" An integer value from 1 to \s-1MAX_INT\s0. Specifies the desired extent of a font glyph between descent and internal leading lines in points. The relation between \f(CW\*(C`size\*(C'\fR and \f(CW\*(C`height\*(C'\fR is .Sp .Vb 3 \& height \- internal_leading \& size = \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- * 72.27 \& resolution .Ve .Sp That differs from some other system representations: Win32, for example, rounds 72.27 constant to 72. .IP "width" 4 .IX Item "width" A integer value from 0 to \s-1MAX_INT\s0. If greater than 0, specifies the desired extent of a font glyph width in pixels. If 0, sets the default ( designed ) width corresponding to the font size or height. .IP "style" 4 .IX Item "style" A combination of \f(CW\*(C`fs::\*(C'\fR ( font style ) constants. The constants hight .Sp .Vb 7 \& fs::Normal \& fs::Bold \& fs::Thin \& fs::Italic \& fs::Underlined \& fs::StruckOut \& fs::Outline .Ve .Sp and can be OR-ed together to express the font style. fs::Normal equals to 0 and usually never used. If some styles are not supported by a system-dependent font subsystem, they are ignored. .IP "pitch" 4 .IX Item "pitch" A one of three constants: .Sp .Vb 3 \& fp::Default \& fp::Fixed \& fp::Variable .Ve .Sp fp::Default specifies no interest about font pitch selection. fp::Fixed is set when a monospaced (all glyphs are of same width) font is desired. fp::Variable pitch specifies a font with different glyph widths. This key is of the highest priority; all other keys may be altered for the consistency of the pitch key. .IP "direction" 4 .IX Item "direction" A counter-clockwise rotation angle \- 0 is default, 90 is pi/2, 180 is pi, etc. If a font could not be rotated, it is usually substituted to the one that can. .IP "encoding" 4 .IX Item "encoding" A string value, one of the strings returned by \&\f(CW\*(C`Prima::Application::font_encodings\*(C'\fR. Selects desired font encoding; if empty, picks the first matched encoding, preferably the locale set up by the user. .Sp The encodings provided by different systems are different; in addition, the only encodings are recognizable by the system, that are represented by at least one font in the system. .Sp Unix systems and the toolkit PostScript interface usually provide the following encodings: .Sp .Vb 4 \& iso8859\-1 \& iso8859\-2 \& ... other iso8859 ... \& fontspecific .Ve .Sp Win32 returns the literal strings like .Sp .Vb 5 \& Western \& Baltic \& Cyrillic \& Hebrew \& Symbol .Ve .PP A hash that \f(CW\*(C`::font\*(C'\fR returns, is a tied hash, whose keys are also available as separate properties. For example, .PP .Vb 1 \& $x = $d\-> font\-> {style}; .Ve .PP is equivalent to .PP .Vb 1 \& $x = $d\-> font\-> style; .Ve .PP While the latter gives nothing but the arguable coding convenience, its usage in set-call is much more usable: .PP .Vb 1 \& $d\-> font\-> style( fs::Bold); .Ve .PP instead of .PP .Vb 3 \& my %temp = %{$d\-> font}; \& $temp{ style} = fs::Bold; \& $d\-> font( \e%temp); .Ve .PP The properties of a font tied hash are also accessible through \fIset()\fR call, like in Prima::Object: .PP .Vb 2 \& $d\-> font\-> style( fs::Bold); \& $d\-> font\-> width( 10); .Ve .PP is adequate to .PP .Vb 4 \& $d\-> font\-> set( \& style => fs::Bold, \& width => 10, \& ); .Ve .PP When get-called, \f(CW\*(C`::font\*(C'\fR property returns a hash where more entries than the described above can be found. These keys are read-only, their values are discarded if passed to \f(CW\*(C`::font\*(C'\fR in a set-call. .PP In order to query the full list of fonts available to a graphic device, a \f(CW\*(C`::fonts\*(C'\fR method is used. This method is not present in Prima::Drawable namespace; it can be found in two built-in class instances, \f(CW\*(C`Prima::Application\*(C'\fR and \f(CW\*(C`Prima::Printer\*(C'\fR. .PP \&\f(CW\*(C`Prima::Application::fonts\*(C'\fR returns metrics for the fonts available to a screen device, while \f(CW\*(C`Prima::Printer::fonts\*(C'\fR ( or its substitute Prima::PS::Printer ) returns fonts for the printing device. The result of this method is an array of font metrics, fully analogous to these returned by \f(CW\*(C`Prima::Drawable::font\*(C'\fR method. .IP "family" 4 .IX Item "family" A string with font family name. The family is a secondary string key, used for distinguishing between fonts with same name but of different vendors ( for example, Adobe Courier and Microsoft Courier). .IP "vector" 4 .IX Item "vector" A boolean; true if the font is vector ( e.g. can be scaled with no quality loss ), false otherwise. The false value does not show if the font can be scaled at all \- the behavior is system-dependent. Win32 and \s-1OS/2\s0 can scale all non-vector fonts; X11 only the fonts specified as the scalable. .IP "ascent" 4 .IX Item "ascent" Number of pixels between a glyph baseline and descent line. .IP "descent" 4 .IX Item "descent" Number of pixels between a glyph baseline and descent line. .IP "internalLeading" 4 .IX Item "internalLeading" Number of pixels between ascent and internal leading lines. Negative if the ascent line is below the internal leading line. .IP "externalLeading" 4 .IX Item "externalLeading" Number of pixels between ascent and external leading lines. Negative if the ascent line is above the external leading line. .Sp .Vb 1 \& \-\-\-\-\-\-\-\-\-\-\-\-\- external leading line \& \& $ \-\-\-\-\-\-\-\-\-\-\-\-\- ascent line \& $ $ \& \-\-\-\-\-\-\-\-\-\-\-\-\- internal leading line \& $ \& $$$ \& $ $ \& $ $ $ \& $$$$$$$ $$$ \& $ $ $ $ \& $ $ $ $ \& $ $ $$$ \-\-\-\- baseline \& $ \& $ \& $ \& $$$$ \-\-\-\- descent line .Ve .IP "weight" 4 .IX Item "weight" A font designed weight. Can be one of .Sp .Vb 9 \& fw::UltraLight \& fw::ExtraLight \& fw::Light \& fw::SemiLight \& fw::Medium \& fw::SemiBold \& fw::Bold \& fw::ExtraBold \& fw::UltraBold .Ve .Sp constants. .IP "maximalWidth" 4 .IX Item "maximalWidth" Maximal extent of a glyph in pixels. Equals to \fBwidth\fR in monospaced fonts. .IP "xDeviceRes" 4 .IX Item "xDeviceRes" Designed horizontal font resolution in dpi. .IP "yDeviceRes" 4 .IX Item "yDeviceRes" Designed vertical font resolution in dpi. .IP "firstChar" 4 .IX Item "firstChar" Index of the first glyph present in a font. .IP "lastChar" 4 .IX Item "lastChar" Index of the last glyph present in a font. .IP "breakChar" 4 .IX Item "breakChar" Index of the default character used to divide words. In a typical western language font it is 32, \s-1ASCII\s0 space character. .IP "defaultChar" 4 .IX Item "defaultChar" Index of a glyph that is drawn instead of nonexistent glyph if its index is passed to the text drawing routines. .SS "Font \s-1ABC\s0 metrics" .IX Subsection "Font ABC metrics" Besides these characteristics, every font glyph has an ABC-metric, the three integer values that describe horizontal extents of a glyph's black part relative to the glyph extent: .PP .Vb 10 \& . . . . . . . . \& . . $$$. . . . . \& . . $$. $ . . . . \& . . $$. . . . $$ . . \& . $$$$$$$$$$. . .$$$$$ . . \& . . $$ . . . $ $$ . . \& . . $$ . . . .$$$$$ . . \& . . $$ . . . . $$ . . \& . .$$ . . . . $$$ $$$. . \& $$ .$$ . . . $ $$ . \& .$$$ . . . .$$$$$$$$. . \& . . . . . . . . \& . . . . \& .<\-.\-\-B\-\-.\->. . .<\-\-B\-\-\->. . \& \& A = \-3 A = 3 \& B = 13 B = 10 \& C = \-3 C = 3 .Ve .PP A and C are negative, if a glyphs 'hangs' over it neighbors, as shown in picture on the left. A and C values are positive, if a glyph contains empty space in front or behind the neighbor glyphs, like in picture on the right. As can be seen, B is the width of a glyph's black part. .PP \&\s-1ABC\s0 metrics returned by \fIget_font_abc()\fR method. .SS "Raster operations" .IX Subsection "Raster operations" A drawable has two raster operation properties: \f(CW\*(C`::rop\*(C'\fR and \f(CW\*(C`::rop2\*(C'\fR. These define how the graphic primitives are plotted. \f(CW\*(C`::rop\*(C'\fR deals with the foreground color drawing, and \f(CW\*(C`::rop2\*(C'\fR with the background. .PP The toolkit defines the following operations: .PP .Vb 10 \& rop::Blackness # = 0 \& rop::NotOr # = !(src | dest) \& rop::NotSrcAnd # &= !src \& rop::NotPut # = !src \& rop::NotDestAnd # = !dest & src \& rop::Invert # = !dest \& rop::XorPut # ^= src \& rop::NotAnd # = !(src & dest) \& rop::AndPut # &= src \& rop::NotXor # = !(src ^ dest) \& rop::NotSrcXor # alias for rop::NotXor \& rop::NotDestXor # alias for rop::NotXor \& rop::NoOper # = dest \& rop::NotSrcOr # |= !src \& rop::CopyPut # = src \& rop::NotDestOr # = !dest | src \& rop::OrPut # |= src \& rop::Whiteness # = 1 .Ve .PP Usually, however, graphic devices support only a small part of the above set, limiting \f(CW\*(C`::rop\*(C'\fR to the most important operations: Copy, And, Or, Xor, NoOp. \f(CW\*(C`::rop2\*(C'\fR is usually even more restricted \- it is only \s-1OS/2\s0 system that supports currently rop2 modes others than Copy and NoOp. .PP The raster operations apply to all graphic primitives except SetPixel. .SS "Coordinates" .IX Subsection "Coordinates" The Prima toolkit employs a geometrical \s-1XY\s0 grid, where X ascends rightwards and Y ascends upwards. There, the (0,0) location is the bottom-left pixel of a canvas. .PP All graphic primitives use inclusive-inclusive boundaries. For example, .PP .Vb 1 \& $d\-> bar( 0, 0, 1, 1); .Ve .PP plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1). .PP The coordinate origin can be shifted using \f(CW\*(C`::translate\*(C'\fR property, that translates the (0,0) point to the given offset. Calls to \&\f(CW\*(C`::translate\*(C'\fR, \f(CW\*(C`::clipRect\*(C'\fR and \f(CW\*(C`::region\*(C'\fR always use the 'physical' (0,0) point, whereas the plotting methods use the transformation result, the 'logical' (0,0) point. .PP As noted before, these three properties can not be used in when an object is in its disabled state. .SH "API" .IX Header "API" .SS "Graphic context properties" .IX Subsection "Graphic context properties" .IP "backColor \s-1COLOR\s0" 4 .IX Item "backColor COLOR" Reflects background color in the graphic context. All drawing routines that use non-solid or transparent fill or line patterns use this property value. .IP "color \s-1COLOR\s0" 4 .IX Item "color COLOR" Reflects foreground color in the graphic context. All drawing routines use this property value. .IP "clipRect X1, Y1, X2, Y2" 4 .IX Item "clipRect X1, Y1, X2, Y2" Selects the clipping rectangle corresponding to the physical canvas origin. On get-call, returns the extent of the clipping area, if it is not rectangular, or the clipping rectangle otherwise. The code .Sp .Vb 2 \& $d\-> clipRect( 1, 1, 2, 2); \& $d\-> bar( 0, 0, 1, 1); .Ve .Sp thus affects only one pixel at (1,1). .Sp Set-call discards the previous \f(CW\*(C`::region\*(C'\fR value. .Sp Note: \f(CW\*(C`::clipRect\*(C'\fR can not be used while the object is in the paint-disabled state, its context is neither recorded nor used as a template ( see \*(L"Graphic context and canvas\*(R"). .IP "fillWinding \s-1BOOLEAN\s0" 4 .IX Item "fillWinding BOOLEAN" Affect filling style of complex polygonal shapes filled by \f(CW\*(C`fillpoly\*(C'\fR. If 1, the filled shape contains no holes; otherwise, holes are present where the shape edges cross. .Sp Default value: 0 .ie n .IP "fillPattern ( [ @PATTERN ] ) or ( fp::XXX )" 4 .el .IP "fillPattern ( [ \f(CW@PATTERN\fR ] ) or ( fp::XXX )" 4 .IX Item "fillPattern ( [ @PATTERN ] ) or ( fp::XXX )" Selects 8x8 fill pattern that affects primitives that plot filled shapes: \&\fIbar()\fR, \fIfill_chord()\fR, \fIfill_ellipse()\fR, \fIfillpoly()\fR, \fIfill_sector()\fR, \fIfloodfill()\fR. .Sp Accepts either a \f(CW\*(C`fp::\*(C'\fR constant or a reference to an array of 8 integers, each representing 8 bits of each line in a pattern, where the first integer is the topmost pattern line, and the bit 0x80 is the leftmost pixel in the line. .Sp There are some predefined patterns, that can be referred via \f(CW\*(C`fp::\*(C'\fR constants: .Sp .Vb 10 \& fp::Empty \& fp::Solid \& fp::Line \& fp::LtSlash \& fp::Slash \& fp::BkSlash \& fp::LtBkSlash \& fp::Hatch \& fp::XHatch \& fp::Interleave \& fp::WideDot \& fp::CloseDot \& fp::SimpleDots \& fp::Borland \& fp::Parquet .Ve .Sp ( the actual patterns are hardcoded in primguts.c ) The default pattern is fp::Solid. .Sp An example below shows encoding of fp::Parquet pattern: .Sp .Vb 2 \& # 76543210 \& 84218421 Hex \& \& 0 $ $ $ 51 \& 1 $ $ 22 \& 2 $ $ $ 15 \& 3 $ $ 88 \& 4 $ $ $ 45 \& 5 $ $ 22 \& 6 $ $ $ 54 \& 7 $ $ 88 \& \& $d\-> fillPattern([ 0x51, 0x22, 0x15, 0x88, 0x45, 0x22, 0x54, 0x88 ]); .Ve .Sp On a get-call always returns an array, never a \f(CW\*(C`fp::\*(C'\fR constant. .IP "font \e%FONT" 4 .IX Item "font %FONT" Manages font context. \s-1FONT\s0 hash acceptable values are \&\f(CW\*(C`name\*(C'\fR, \f(CW\*(C`height\*(C'\fR, \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`width\*(C'\fR, \f(CW\*(C`style\*(C'\fR and \f(CW\*(C`pitch\*(C'\fR. .Sp Synopsis: .Sp .Vb 6 \& $d\-> font\-> size( 10); \& $d\-> font\-> name( \*(AqCourier\*(Aq); \& $d\-> font\-> set( \& style => $x\-> font\-> style | fs::Bold, \& width => 22 \& ); .Ve .Sp See \*(L"Fonts\*(R" for the detailed descriptions. .Sp Applies to \fItext_out()\fR, \fIget_text_width()\fR, \fIget_text_box()\fR, \fIget_font_abc()\fR. .IP "lineEnd \s-1VALUE\s0" 4 .IX Item "lineEnd VALUE" Selects a line ending cap for plotting primitives. \s-1VALUE\s0 can be one of .Sp .Vb 3 \& le::Flat \& le::Square \& le::Round \& \& constants. le::Round is the default value. .Ve .IP "lineJoin \s-1VALUE\s0" 4 .IX Item "lineJoin VALUE" Selects a line joining style for polygons. \s-1VALUE\s0 can be one of .Sp .Vb 3 \& lj::Round \& lj::Bevel \& lj::Miter .Ve .Sp constants. lj::Round is the default value. .IP "linePattern \s-1PATTERN\s0" 4 .IX Item "linePattern PATTERN" Selects a line pattern for plotting primitives. \&\s-1PATTERN\s0 is either a predefined \f(CW\*(C`lp::\*(C'\fR constant, or a string where each even byte is a length of a dash, and each odd byte is a length of a gap. .Sp The predefined constants are: .Sp .Vb 9 \& lp::Null # "" /* */ \& lp::Solid # "\e1" /* _\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_ */ \& lp::Dash # "\ex9\e3" /* _\|_ _\|_ _\|_ _\|_ */ \& lp::LongDash # "\ex16\e6" /* _\|_\|_\|_\|_ _\|_\|_\|_\|_ */ \& lp::ShortDash # "\e3\e3" /* _ _ _ _ _ _ */ \& lp::Dot # "\e1\e3" /* . . . . . . */ \& lp::DotDot # "\e1\e1" /* ............ */ \& lp::DashDot # "\ex9\e6\e1\e3" /* _._._._._._ */ \& lp::DashDotDot # "\ex9\e3\e1\e3\e1\e3" /* _.._.._.._.. */ .Ve .Sp Not all systems are capable of accepting user-defined line patterns, and in such situation the \f(CW\*(C`lp::\*(C'\fR constants are mapped to the system-defined patterns. In Win9x, for example, lp::DashDotDot is much different from its string definition therefore. .Sp Default value is lp::Solid. .IP "lineWidth \s-1WIDTH\s0" 4 .IX Item "lineWidth WIDTH" Selects a line width for plotting primitives. If a \s-1VALUE\s0 is 0, then a 'cosmetic' pen is used \- the thinnest possible line that a device can plot. If a \s-1VALUE\s0 is greater than 0, then a 'geometric' pen is used \- the line width is set in device units. There is a subtle difference between \s-1VALUE\s0 0 and 1 in a way the lines are joined. .Sp Default value is 0. .ie n .IP "palette [ @PALETTE ]" 4 .el .IP "palette [ \f(CW@PALETTE\fR ]" 4 .IX Item "palette [ @PALETTE ]" Selects solid colors in a system palette, as many as possible. \&\s-1PALETTE\s0 is an array of integer triplets, where each is R, G and B component. The call .Sp .Vb 1 \& $d\-> palette([128, 240, 240]); .Ve .Sp selects a gray-cyan color, for example. .Sp The return value from get-call is the content of the previous set-call, not the actual colors that were copied to the system palette. .IP "region \s-1OBJECT\s0" 4 .IX Item "region OBJECT" Selects a clipping region applied to all drawing and painting routines. The \s-1OBJECT\s0 is either undef, then the clip region is erased ( no clip ), or a Prima::Image object with a bit depth of 1. The bit mask of \s-1OBJECT\s0 is applied to the system clipping region. If the \s-1OBJECT\s0 is smaller than the drawable, its exterior is assigned to clipped area as well. Discards the previous \f(CW\*(C`::clipRect\*(C'\fR value; successive get-calls to \f(CW\*(C`::clipRect\*(C'\fR return the boundaries of the region. .Sp Note: \f(CW\*(C`::region\*(C'\fR can not be used while the object is in the paint-disabled state, its context is neither recorded nor used as a template ( see \*(L"Graphic context and canvas\*(R"). .IP "resolution X, Y" 4 .IX Item "resolution X, Y" A read-only property. Returns horizontal and vertical device resolution in dpi. .IP "rop \s-1OPERATION\s0" 4 .IX Item "rop OPERATION" Selects raster operation that applies to foreground color plotting routines. .Sp See also: \f(CW\*(C`::rop2\*(C'\fR, \*(L"Raster operations\*(R". .IP "rop2 \s-1OPERATION\s0" 4 .IX Item "rop2 OPERATION" Selects raster operation that applies to background color plotting routines. .Sp See also: \f(CW\*(C`::rop\*(C'\fR, \*(L"Raster operations\*(R". .IP "splinePrecision \s-1INT\s0" 4 .IX Item "splinePrecision INT" Selects number of steps to use for each spline segment in \f(CW\*(C`spline\*(C'\fR and \f(CW\*(C`fill_spline\*(C'\fR calls. In other words, determines smoothness of a curve. Minimum accepted value, 1, produces straight lines; maximum value is not present, though it is hardly practical to set it higher than the output device resolution. .Sp Default value: 24 .IP "textOpaque \s-1FLAG\s0" 4 .IX Item "textOpaque FLAG" If \s-1FLAG\s0 is 1, then \fItext_out()\fR fills the text background area with \f(CW\*(C`::backColor\*(C'\fR property value before drawing the text. Default value is 0, when \fItext_out()\fR plots text only. .Sp See \fIget_text_box()\fR. .IP "textOutBaseline \s-1FLAG\s0" 4 .IX Item "textOutBaseline FLAG" If \s-1FLAG\s0 is 1, then \fItext_out()\fR plots text on a given Y coordinate correspondent to font baseline. If \s-1FLAG\s0 is 0, a Y coordinate is mapped to font descent line. Default is 0. .IP "translate X_OFFSET, Y_OFFSET" 4 .IX Item "translate X_OFFSET, Y_OFFSET" Translates the origin point by X_OFFSET and Y_OFFSET. Does not affect \f(CW\*(C`::clipRect\*(C'\fR and \f(CW\*(C`::region\*(C'\fR. Not cumulative, so the call sequence .Sp .Vb 2 \& $d\-> translate( 5, 5); \& $d\-> translate( 15, 15); .Ve .Sp is equivalent to .Sp .Vb 1 \& $d\-> translate( 15, 15); .Ve .Sp Note: \f(CW\*(C`::translate\*(C'\fR can not be used while the object is in the paint-disabled state, its context is neither recorded nor used as a template ( see \*(L"Graphic context and canvas\*(R"). .SS "Other properties" .IX Subsection "Other properties" .IP "height \s-1HEIGHT\s0" 4 .IX Item "height HEIGHT" Selects the height of a canvas. .IP "size \s-1WIDTH\s0, \s-1HEIGHT\s0" 4 .IX Item "size WIDTH, HEIGHT" Selects the extent of a canvas. .IP "width \s-1WIDTH\s0" 4 .IX Item "width WIDTH" Selects the width of a canvas. .SS "Graphic primitives methods" .IX Subsection "Graphic primitives methods" .IP "arc X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0, \s-1START_ANGLE\s0, \s-1END_ANGLE\s0" 4 .IX Item "arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE" Plots an arc with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis from \s-1START_ANGLE\s0 to \s-1END_ANGLE\s0. .Sp Context used: color, backColor, lineEnd, linePattern, lineWidth, rop, rop2 .IP "bar X1, Y1, X2, Y2" 4 .IX Item "bar X1, Y1, X2, Y2" Draws a filled rectangle with (X1,Y1) \- (X2,Y2) extents. .Sp Context used: color, backColor, fillPattern, rop, rop2 .IP "chord X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0, \s-1START_ANGLE\s0, \s-1END_ANGLE\s0" 4 .IX Item "chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE" Plots an arc with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis from \s-1START_ANGLE\s0 to \s-1END_ANGLE\s0 and connects its ends with a straight line. .Sp Context used: color, backColor, lineEnd, linePattern, lineWidth, rop, rop2 .IP "clear " 4 .IX Item "clear " Draws rectangle filled with pure background color with (X1,Y1) \- (X2,Y2) extents. Can be called without parameters, in this case fills all canvas area. .Sp Context used: backColor, rop2 .IP "draw_text \s-1CANVAS\s0, \s-1TEXT\s0, X1, Y1, X2, Y2, [ \s-1FLAGS\s0 = dt::Default, \s-1TAB_INDENT\s0 = 1 ]" 4 .IX Item "draw_text CANVAS, TEXT, X1, Y1, X2, Y2, [ FLAGS = dt::Default, TAB_INDENT = 1 ]" Draws several lines of text one under another with respect to align and break rules, specified in \s-1FLAGS\s0 and \s-1TAB_INDENT\s0 tab character expansion. .Sp \&\f(CW\*(C`draw_text\*(C'\fR is a convenience wrapper around \f(CW\*(C`text_wrap\*(C'\fR for drawing the wrapped text, and also provides the tilde ( ~ )\- character underlining support. .Sp The \s-1FLAGS\s0 is a combination of the following constants: .Sp .Vb 10 \& dt::Left \- text is aligned to the left boundary \& dt::Right \- text is aligned to the right boundary \& dt::Center \- text is aligned horizontally in center \& dt::Top \- text is aligned to the upper boundary \& dt::Bottom \- text is aligned to the lower boundary \& dt::VCenter \- text is aligned vertically in center \& dt::DrawMnemonic \- tilde\-escapement and underlining is used \& dt::DrawSingleChar \- sets tw::BreakSingle option to \& Prima::Drawable::text_wrap call \& dt::NewLineBreak \- sets tw::NewLineBreak option to \& Prima::Drawable::text_wrap call \& dt::SpaceBreak \- sets tw::SpaceBreak option to \& Prima::Drawable::text_wrap call \& dt::WordBreak \- sets tw::WordBreak option to \& Prima::Drawable::text_wrap call \& dt::ExpandTabs \- performs tab character ( \et ) expansion \& dt::DrawPartial \- draws the last line, if it is visible partially \& dt::UseExternalLeading \- text lines positioned vertically with respect to \& the font external leading \& dt::UseClip \- assign ::clipRect property to the boundary rectangle \& dt::QueryLinesDrawn \- calculates and returns number of lines drawn \& ( contrary to dt::QueryHeight ) \& dt::QueryHeight \- if set, calculates and returns vertical extension \& of the lines drawn \& dt::NoWordWrap \- performs no word wrapping by the width of the boundaries \& dt::WordWrap \- performs word wrapping by the width of the boundaries \& dt::Default \- dt::NewLineBreak|dt::WordBreak|dt::ExpandTabs| \& dt::UseExternalLeading .Ve .Sp Context used: color, backColor, font, rop, textOpaque, textOutBaseline .IP "ellipse X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0" 4 .IX Item "ellipse X, Y, DIAMETER_X, DIAMETER_Y" Plots an ellipse with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis. .Sp Context used: color, backColor, linePattern, lineWidth, rop, rop2 .IP "fill_chord X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0, \s-1START_ANGLE\s0, \s-1END_ANGLE\s0" 4 .IX Item "fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE" Fills a chord outline with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis from \s-1START_ANGLE\s0 to \s-1END_ANGLE\s0 (see \fIchord()\fR). .Sp Context used: color, backColor, fillPattern, rop, rop2 .IP "fill_ellipse X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0" 4 .IX Item "fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y" Fills an elliptical outline with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis. .Sp Context used: color, backColor, fillPattern, rop, rop2 .IP "fillpoly \e@POLYGON" 4 .IX Item "fillpoly @POLYGON" Fills a polygonal area defined by \s-1POLYGON\s0 set of points. \&\s-1POLYGON\s0 must present an array of integer pair in (X,Y) format. Example: .Sp .Vb 1 \& $d\-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle .Ve .Sp Context used: color, backColor, fillPattern, rop, rop2, fillWinding .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp See also: \fIpolyline()\fR. .IP "fill_sector X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0, \s-1START_ANGLE\s0, \s-1END_ANGLE\s0" 4 .IX Item "fill_sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE" Fills a sector outline with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis from \s-1START_ANGLE\s0 to \s-1END_ANGLE\s0 (see \fIsector()\fR). .Sp Context used: color, backColor, fillPattern, rop, rop2 .IP "fill_spline \e@POLYGON" 4 .IX Item "fill_spline @POLYGON" Fills a polygonal area defined by a curve, projected by applying cubic spline interpolation to \s-1POLYGON\s0 set of points. Number of vertices between each polygon equals to current value of \f(CW\*(C`splinePrecision\*(C'\fR property. \&\s-1POLYGON\s0 must present an array of integer pair in (X,Y) format. Example: .Sp .Vb 1 \& $d\-> fill_spline([ 0, 0, 15, 20, 30, 0]); .Ve .Sp Context used: color, backColor, fillPattern, rop, rop2, splinePrecision .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp See also: spline, splinePrecision, render_spline .IP "flood_fill X, Y, \s-1COLOR\s0, \s-1SINGLEBORDER\s0 = 1" 4 .IX Item "flood_fill X, Y, COLOR, SINGLEBORDER = 1" Fills an area of the canvas in current fill context. The area is assumed to be bounded as specified by the \s-1SINGLEBORDER\s0 parameter. \&\s-1SINGLEBORDER\s0 can be 0 or 1. .Sp \&\s-1SINGLEBORDER\s0 = 0: The fill area is bounded by the color specified by the \s-1COLOR\s0 parameter. .Sp \&\s-1SINGLEBORDER\s0 = 1: The fill area is defined by the color that is specified by \s-1COLOR\s0. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries. .Sp Context used: color, backColor, fillPattern, rop, rop2 .IP "line X1, Y1, X2, Y2" 4 .IX Item "line X1, Y1, X2, Y2" Plots a straight line from (X1,Y1) to (X2,Y2). .Sp Context used: color, backColor, linePattern, lineWidth, rop, rop2 .IP "lines \e@LINES" 4 .IX Item "lines @LINES" \&\s-1LINES\s0 is an array of integer quartets in format (X1,Y1,X2,Y2). \&\fIlines()\fR plots a straight line per quartet. .Sp Context used: color, backColor, linePattern, lineWidth, rop, rop2 .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .IP "pixel X, Y, <\s-1COLOR\s0>" 4 .IX Item "pixel X, Y, " ::pixel is a property \- on set-call it changes the pixel value at (X,Y) to \s-1COLOR\s0, on get-call ( without \s-1COLOR\s0 ) it does return a pixel value at (X,Y). .Sp No context is used. .IP "polyline \e@POLYGON" 4 .IX Item "polyline @POLYGON" Draws a polygonal area defined by \s-1POLYGON\s0 set of points. \&\s-1POLYGON\s0 must present an array of integer pair in (X,Y) format. .Sp Context used: color, backColor, linePattern, lineWidth, lineJoin, lineEnd, rop, rop2 .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp See also: \fIfillpoly()\fR. .IP "put_image X, Y, \s-1OBJECT\s0, [ \s-1ROP\s0 ]" 4 .IX Item "put_image X, Y, OBJECT, [ ROP ]" Draws an \s-1OBJECT\s0 at coordinates (X,Y). \s-1OBJECT\s0 must be Prima::Image, Prima::Icon or Prima::DeviceBitmap. If \s-1ROP\s0 raster operation is specified, it is used. Otherwise, value of \f(CW\*(C`::rop\*(C'\fR property is used. .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp Context used: rop; color and backColor for a monochrome DeviceBitmap .IP "put_image_indirect \s-1OBJECT\s0, X, Y, X_FROM, Y_FROM, \s-1DEST_WIDTH\s0, \s-1DEST_HEIGHT\s0, \s-1SRC_WIDTH\s0, \s-1SRC_HEIGHT\s0, \s-1ROP\s0" 4 .IX Item "put_image_indirect OBJECT, X, Y, X_FROM, Y_FROM, DEST_WIDTH, DEST_HEIGHT, SRC_WIDTH, SRC_HEIGHT, ROP" Copies a \s-1OBJECT\s0 from a source rectangle into a destination rectangle, stretching or compressing the \s-1OBJECT\s0 to fit the dimensions of the destination rectangle, if necessary. The source rectangle starts at (X_FROM,Y_FROM), and is \s-1SRC_WIDTH\s0 pixels wide and \s-1SRC_HEIGHT\s0 pixels tall. The destination rectangle starts at (X,Y), and is abs(\s-1DEST_WIDTH\s0) pixels wide and abs(\s-1DEST_HEIGHT\s0) pixels tall. If \s-1DEST_WIDTH\s0 or \s-1DEST_HEIGHT\s0 are negative, a mirroring by respective axis is performed. .Sp \&\s-1OBJECT\s0 must be Prima::Image, Prima::Icon or Prima::DeviceBitmap. .Sp No context is used, except color and backColor for a monochrome DeviceBitmap .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .IP "rect3d X1, Y1, X2, Y2, \s-1WIDTH\s0, \s-1LIGHT_COLOR\s0, \s-1DARK_COLOR\s0, [ \s-1BACK_COLOR\s0 ]" 4 .IX Item "rect3d X1, Y1, X2, Y2, WIDTH, LIGHT_COLOR, DARK_COLOR, [ BACK_COLOR ]" Draws 3d\-shaded rectangle in boundaries X1,Y1 \- X2,Y2 with \s-1WIDTH\s0 line width and \s-1LIGHT_COLOR\s0 and \s-1DARK_COLOR\s0 colors. If \s-1BACK_COLOR\s0 is specified, paints an inferior rectangle with it, otherwise the inferior rectangle is not touched. .Sp Context used: rop; color and backColor for a monochrome DeviceBitmap .IP "rect_focus X1, Y1, X2, Y2, [ \s-1WIDTH\s0 = 1 ]" 4 .IX Item "rect_focus X1, Y1, X2, Y2, [ WIDTH = 1 ]" Draws a marquee rectangle in boundaries X1,Y1 \- X2,Y2 with \s-1WIDTH\s0 line width. .Sp No context is used. .IP "rectangle X1, Y1, X2, Y2" 4 .IX Item "rectangle X1, Y1, X2, Y2" Plots a rectangle with (X1,Y1) \- (X2,Y2) extents. .Sp Context used: color, backColor, linePattern, lineWidth, rop, rop2 .IP "sector X, Y, \s-1DIAMETER_X\s0, \s-1DIAMETER_Y\s0, \s-1START_ANGLE\s0, \s-1END_ANGLE\s0" 4 .IX Item "sector X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE" Plots an arc with center in X, Y and \s-1DIAMETER_X\s0 and \s-1DIAMETER_Y\s0 axis from \s-1START_ANGLE\s0 to \s-1END_ANGLE\s0 and connects its ends and (X,Y) with two straight lines. .Sp Context used: color, backColor, lineEnd, linePattern, lineWidth, rop, rop2 .IP "spline \e@POLYGON" 4 .IX Item "spline @POLYGON" Draws a cubic spline defined by set of \s-1POLYGON\s0 points. Number of vertices between each polygon equals to current value of \f(CW\*(C`splinePrecision\*(C'\fR property. \&\s-1POLYGON\s0 must present an array of integer pair in (X,Y) format. .Sp Context used: color, backColor, linePattern, lineWidth, lineEnd, rop, rop2 .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp See also: fill_spline, splinePrecision, render_spline. .IP "stretch_image X, Y, \s-1DEST_WIDTH\s0, \s-1DEST_HEIGHT\s0, \s-1OBJECT\s0, [ \s-1ROP\s0 ]" 4 .IX Item "stretch_image X, Y, DEST_WIDTH, DEST_HEIGHT, OBJECT, [ ROP ]" Copies a \s-1OBJECT\s0 into a destination rectangle, stretching or compressing the \s-1OBJECT\s0 to fit the dimensions of the destination rectangle, if necessary. If \s-1DEST_WIDTH\s0 or \s-1DEST_HEIGHT\s0 are negative, a mirroring is performed. The destination rectangle starts at (X,Y) and is \s-1DEST_WIDTH\s0 pixels wide and \s-1DEST_HEIGHT\s0 pixels tall. .Sp If \s-1ROP\s0 raster operation is specified, it is used. Otherwise, value of \f(CW\*(C`::rop\*(C'\fR property is used. .Sp \&\s-1OBJECT\s0 must be Prima::Image, Prima::Icon or Prima::DeviceBitmap. .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp Context used: rop .IP "text_out \s-1TEXT\s0, X, Y" 4 .IX Item "text_out TEXT, X, Y" Draws \s-1TEXT\s0 string at (X,Y). .Sp Returns success flag; if failed, \f(CW$@\fR contains the error. .Sp Context used: color, backColor, font, rop, textOpaque, textOutBaseline .SS "Methods" .IX Subsection "Methods" .IP "begin_paint" 4 .IX Item "begin_paint" Enters the enabled ( active paint ) state, returns success flag; if failed, \&\f(CW$@\fR contains the error. Once the object is in enabled state, painting and drawing methods can perform write operations on a canvas. .Sp See also: \f(CW\*(C`end_paint\*(C'\fR, \f(CW\*(C`begin_paint_info\*(C'\fR, \*(L"Graphic context and canvas\*(R" .IP "begin_paint_info" 4 .IX Item "begin_paint_info" Enters the information state, returns success flag; if failed, \&\f(CW$@\fR contains the error. The object information state is same as enabled state ( see \f(CW\*(C`begin_paint\*(C'\fR), except painting and drawing methods do not change the object canvas. .Sp See also: \f(CW\*(C`end_paint_info\*(C'\fR, \f(CW\*(C`begin_paint\*(C'\fR, \*(L"Graphic context and canvas\*(R" .IP "end_paint" 4 .IX Item "end_paint" Exits the enabled state and returns the object to a disabled state. .Sp See also: \f(CW\*(C`begin_paint\*(C'\fR, \*(L"Graphic context and canvas\*(R" .IP "end_paint_info" 4 .IX Item "end_paint_info" Exits the information state and returns the object to a disabled state. .Sp See also: \f(CW\*(C`begin_paint_info\*(C'\fR, \*(L"Graphic context and canvas\*(R" .IP "font_match \e%SOURCE, \e%DEST, \s-1PICK\s0 = 1" 4 .IX Item "font_match %SOURCE, %DEST, PICK = 1" Performs merging of two font hashes, \s-1SOURCE\s0 and \s-1DEST\s0. Returns the merge result. If \s-1PICK\s0 is true, matches the result with a system font repository. .Sp Called implicitly by \f(CW\*(C`::font\*(C'\fR on set-call, allowing the following example to work: .Sp .Vb 2 \& $d\-> font\-> set( size => 10); \& $d\-> font\-> set( style => fs::Bold); .Ve .Sp In the example, the hash 'style => fs::Bold' does not overwrite the previous font context ( 'size => 10' ) but gets added to it ( by \fIfont_match()\fR), providing the resulting font with both font properties set. .ie n .IP "fonts <\s-1FAMILY\s0 = """", \s-1ENCODING\s0 = """">" 4 .el .IP "fonts <\s-1FAMILY\s0 = ``'', \s-1ENCODING\s0 = ``''>" 4 .IX Item "fonts " Member of \f(CW\*(C`Prima::Application\*(C'\fR and \f(CW\*(C`Prima::Printer\*(C'\fR, does not present in \f(CW\*(C`Prima::Drawable\*(C'\fR. .Sp Returns an array of font metric hashes for a given font \s-1FAMILY\s0 and \s-1ENCODING\s0. Every hash has full set of elements described in \*(L"Fonts\*(R". .Sp If called without parameters, returns an array of same hashes where each hash represents a member of font family from every system font set. It this special case, each font hash contains additional \f(CW\*(C`encodings\*(C'\fR entry, which points to an array of encodings available for the font. .Sp If called with \s-1FAMILY\s0 parameter set but no \s-1ENCODING\s0 is set, enumerates all combinations of fonts with all available encodings. .Sp If called with \s-1FAMILY\s0 set to an empty string, but \s-1ENCODING\s0 specified, returns only fonts that can be displayed with the encoding. .Sp Example: .Sp .Vb 1 \& print sort map {"$_\->{name}\en"} @{$::application\-> fonts}; .Ve .IP "get_bpp" 4 .IX Item "get_bpp" Returns device color depth. 1 is for black-and-white monochrome, 24 for true color, etc. .IP "get_font_abc \s-1FIRST_CHAR\s0 = \-1, \s-1LAST_CHAR\s0 = \-1, \s-1UNICODE\s0 = 0" 4 .IX Item "get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0" Returns \s-1ABC\s0 font metrics for the given range, starting at \&\s-1FIRST_CHAR\s0 and ending with \s-1LAST_CHAR\s0. If parameters are \-1, the default range ( 0 and 255 ) is assumed. \s-1UNICODE\s0 boolean flag is responsible of representation of characters in 127\-255 range. If 0, the default, encoding-dependent characters are assumed. If 1, the U007F\-U00FF glyphs from Latin\-1 set are used. .Sp The result is an integer array reference, where every character glyph is referred by three integers, each triplet containing A, B and C values. .Sp For detailed explanation of \s-1ABC\s0 meaning, see \*(L"Font \s-1ABC\s0 metrics\*(R"; .Sp Context used: font .IP "get_nearest_color \s-1COLOR\s0" 4 .IX Item "get_nearest_color COLOR" Returns a nearest possible solid color in representation of object-bound graphic device. Always returns same color if the device bit depth is equals or greater than 24. .IP "get_paint_state" 4 .IX Item "get_paint_state" Returns paint state value \- 0 if the object is in the disabled state, 1 for the enabled state, 2 for the information state. .IP "get_physical_palette" 4 .IX Item "get_physical_palette" Returns an anonymous array of integers, in (R,G,B) format, every color entry described by three values, in range 0 \- 255. .Sp The physical palette array is non-empty only on paletted graphic devices, the true color devices return an empty array. .Sp The physical palette reflects the solid colors currently available to all programs in the system. The information is volatile if the system palette can change colors, since any other application may change the system colors at any moment. .IP "get_text_width \s-1TEXT\s0, \s-1ADD_OVERHANG\s0 = 0" 4 .IX Item "get_text_width TEXT, ADD_OVERHANG = 0" Returns \s-1TEXT\s0 string width if it would be drawn using currently selected font. .Sp If \s-1ADD_OVERHANG\s0 is 1, the first character's absolute A value and the last character's absolute C value are added to the string if they are negative. .Sp See more on \s-1ABC\s0 values at \*(L"Font \s-1ABC\s0 metrics\*(R". .Sp Context used: font .IP "get_text_box \s-1TEXT\s0" 4 .IX Item "get_text_box TEXT" Returns \s-1TEXT\s0 string extensions if it would be drawn using currently selected font. .Sp The result is an anonymous array of 5 points ( 5 integer pairs in (X,Y) format). These 5 points are offsets for the following string extents, given the string is plotted at (0,0): .Sp 1: start of string at ascent line ( top left ) .Sp 2: start of string at descent line ( bottom left ) .Sp 3: end of string at ascent line ( top right ) .Sp 4: end of string at descent line ( bottom right ) .Sp 5: concatenation point .Sp The concatenation point coordinates (\s-1XC\s0,YC) are coordinated passed to consequent \fItext_out()\fR call so the conjoint string would plot as if it was a part of \s-1TEXT\s0. Depending on the value of the \f(CW\*(C`textOutBaseline\*(C'\fR property, the concatenation point is located either on the baseline or on the descent line. .Sp Context used: font, textOutBaseline .Sp .Vb 7 \& 1 3 3 4 \& ** **** \& * * * \& *** *** \& * * * \& **** ** \& 2 4 1 2 .Ve .IP "render_spline \s-1VERTICES\s0, [ \s-1PRECISION\s0 ]" 4 .IX Item "render_spline VERTICES, [ PRECISION ]" Renders cubic spline from set of \s-1VERTICES\s0 to a polyline with given precision. The method can be called as static, i.e. with no object initialized. \s-1PRECISION\s0 integer, if not given, is read from \f(CW\*(C`splinePrecision\*(C'\fR property if the method was called on an alive object; in case of static call, default value 24 is used. .Sp The method is internally used by \f(CW\*(C`spline\*(C'\fR and \f(CW\*(C`fill_spline\*(C'\fR, and is provided for cases when these are insufficient. .IP "text_wrap \s-1TEXT\s0, \s-1WIDTH\s0, \s-1OPTIONS\s0, \s-1TAB_INDENT\s0 = 8" 4 .IX Item "text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8" Breaks \s-1TEXT\s0 string in chunks that would fit into \s-1WIDTH\s0 pixels wide box. .Sp The break algorithm and its result are governed by \s-1OPTIONS\s0 integer value which is a combination of \f(CW\*(C`tw::\*(C'\fR constants: .RS 4 .IP "tw::CalcMnemonic" 4 .IX Item "tw::CalcMnemonic" Use 'hot key' semantics, when a character preceded by ~ has special meaning \- it gets underlined. If this bit is set, the first tilde character used as an escapement is not calculated, and never appeared in the result apart from the escaped character. .IP "tw::CollapseTilde" 4 .IX Item "tw::CollapseTilde" In addition to tw::CalcMnemonic, removes '~' character from the resulting chunks. .IP "tw::CalcTabs" 4 .IX Item "tw::CalcTabs" If set, calculates a tab ('\et') character as \s-1TAB_INDENT\s0 times space characters. .IP "tw::ExpandTabs" 4 .IX Item "tw::ExpandTabs" If set, expands tab ('\et') character as \s-1TAB_INDENT\s0 times space characters. .IP "tw::BreakSingle" 4 .IX Item "tw::BreakSingle" Defines procedure behavior when the text cannot be fit in \s-1WIDTH\s0, does not affect anything otherwise. .Sp If set, returns an empty array. If unset, returns a text broken by minimum number of characters per chunk. In the latter case, the width of the resulting text blocks \fBwill\fR exceed \s-1WIDTH\s0. .IP "tw::NewLineBreak" 4 .IX Item "tw::NewLineBreak" Forces new chunk after a newline character ('\en') is met. If \s-1UTF8\s0 text is passed, unicode line break characters \f(CW0x2028\fR and \f(CW0x2029\fR produce same effect as the newline character. .IP "tw::SpaceBreak" 4 .IX Item "tw::SpaceBreak" Forces new chunk after a space character (' ') or a tab character ('\et') are met. .IP "tw::ReturnChunks" 4 .IX Item "tw::ReturnChunks" Defines the result of \fItext_wrap()\fR function. .Sp If set, the array consists of integer pairs, each consists of a text offset within \s-1TEXT\s0 and a its length. .Sp If unset, the resulting array consists from text chunks. .IP "tw::ReturnLines" 4 .IX Item "tw::ReturnLines" Equals to 0, is a mnemonic to an unset tw::ReturnChunks. .IP "tw::WordBreak" 4 .IX Item "tw::WordBreak" If unset, the \s-1TEXT\s0 breaks as soon as the chunk width exceeds \s-1WIDTH\s0. If set, tries to keep words in \s-1TEXT\s0 so they do not appear in two chunks, e.g. keeps breaking \s-1TEXT\s0 by words, not by characters. .IP "tw::ReturnFirstLineLength" 4 .IX Item "tw::ReturnFirstLineLength" If set, \f(CW\*(C`text_wrap\*(C'\fR proceeds until the first line is wrapped, either by width or ( if specified ) by break characters. Returns length of the resulting line. Used for efficiency when the reverse function to \f(CW\*(C`get_text_width\*(C'\fR is needed. .RE .RS 4 .Sp If \s-1OPTIONS\s0 has tw::CalcMnemonic or tw::CollapseTilde bits set, then the last scalar in the array result is a special hash reference. The hash contains extra information regarding the 'hot key' underline position \- it is assumed that '~' \- escapement denotes an underlined character. The hash contains the following keys: .IP "tildeLine" 4 .IX Item "tildeLine" Chunk index that contains the escaped character. Set to undef if no ~ \- escapement was found. The other hash information is not relevant in this case. .IP "tildeStart" 4 .IX Item "tildeStart" Horizontal offset of a beginning of the line that underlines the escaped character. .IP "tildeEnd" 4 .IX Item "tildeEnd" Horizontal offset of an end of the line that underlines the escaped character. .IP "tildeChar" 4 .IX Item "tildeChar" The escaped character. .RE .RS 4 .Sp Context used: font .RE .SH "AUTHOR" .IX Header "AUTHOR" Dmitry Karasik, . .SH "SEE ALSO" .IX Header "SEE ALSO" Prima, Prima::Object, Prima::Image