NAME

Prima::Drawable - 2-D graphic interface

SYNOPSIS

   if ( $object-> isa('Prima::Drawable')) {
        $object-> begin_paint;
	$object-> color( cl::Black);
	$object-> line( 100, 100, 200, 200);
	$object-> ellipse( 100, 100, 200, 200);
        $object-> end_paint;
   }

DESCRIPTION

Prima::Drawable is a descendant of Prima::Component. It provides access to the system 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.

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, begin_paint() method is used. Once in the enabled state, the object drawing and painting methods apply to the system canvas. To return to the disabled state, end_paint() method is called. The information state can be managed by using begin_paint_info() and end_paint_info() methods pair. An object cannot be triggered from the information state to the enabled state ( and vice versa ) directly. These work differently with the graphic context and the canvas.

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, connected to the Prima object, where the drawing and painting methods are used on.

In all three states a graphic context is allowed to be modified, but in different ways. In the disabled state a graphic context value is saved as a template; when an object enters the information or the enabled state, all 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 the enabled state. The code example below illustrates the idea:

$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

( Note: ::region, ::clipRect and ::translate properties are exceptions. They cannot be used in the disabled state; their values are neither recorded nor used as a template).

That is, in the disabled state any Drawable maintains only the graphic context values. To draw on a canvas, the object must enter the enabled state by calling begin_paint(). This function can be unsuccessful, because the object binds with system resources during this stage, and allocation of those may fail. Only after the enabled state is entered, the canvas is accessible:

$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't draw on image:$@";
}

Different objects are mapped to different types of canvases - Prima::Image canvas pertains its content after end_paint(), Prima::Widget maps it to some screen area, which content is of more transitory nature, etc.

The information state is as same as the enabled state, but the changes to the canvas are not visible. Its sole purpose is to read, not to write information. Because begin_paint() requires some amount of system resources, there is a chance that a resource request can fail, for any reason. The begin_paint_info() 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 get_text_width() method, that returns the length of a text string in pixels. It works in both enabled and information states, but code

$d = Prima::Image-> create( width => 10000, height => 10000);
$d-> begin_paint;
$x = $d-> get_text_width('A');
$d-> end_paint;

is much more 'expensive' than

$d = Prima::Image-> create( width => 10000, height => 10000);
$d-> begin_paint_info;
$x = $d-> get_text_width('A');
$d-> end_paint_info;

for the obvious reasons.

It must be noted that some information methods like get_text_width() work even under the disabled state; the object is switched to the information state implicitly if it is necessary.

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 Prima definitions. Often the only information available about color space is its color depth.

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 on the object in the disabled state, it is recorded verbatim; color properties are no exception. After the object switched to the enabled state, a color value is translated to the system color representation, which might be different from Prima's. For example, if the display color depth is 15 bits, 5 bits for every component, then the white color value 0xffffff is mapped to

11111000 11111000 11111000
--R----- --G----- --B-----

that equals to 0xf8f8f8, not 0xffffff ( See Prima::gp-problems for inevident graphic issues discussion ).

The Prima::Drawable color format is RRGGBB, 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 insufficient, dithering algorithms may apply.

Note: not only color properties, but all graphic context properties allow all possible values in the disabled state, which are translated into system-allowed values when entering 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:

$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;

There are ( at least ) two color properties on each drawable - ::color and ::backColor. The values they operate are unsigned integers in the discussed above RRGGBB format, however, the toolkit defines some mnemonic color constants as well:

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

As stated before, it is not unlikely that if a device color depth is insufficient, where the primitives could be drawn with dithered or incorrect colors. This usually happens on paletted displays, with 256 or less colors.

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 get_nearest_color() and get_physical_palette() provide possibility to avoid mixed colors drawing by obtaining indirect information about solid colors, supported by a device. Another method is to use ::palette 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.

Both of these methods are applicable both with drawing routines and image output. An application that desires to display an image 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.

Monochrome bitmaps

Prima has special rules when drawing a monochrome Prima::DeviceBitmap. Such objects don't possess an inherent color palette, and by definition are bitmaps with only two pixel values present, 0s and 1s. When a monochrome bitmap is drawn, 0s are painted using the color value of the target canvas color property, and 1s using the backColor value.

That means that the following code

$bitmap-> color(0);
$bitmap-> line(0,0,100,100);
$target-> color(cl::Green);
$target-> put_image(0,0,$bitmap);

produces a green line on $target.

When using monochrome bitmaps for logical operations, note that the target colors should not be explicit 0 and 0xffffff, nor cl::Black and cl::White, but cl::Clear and cl::Set instead. The reason is that on paletted displays, system palette may not necessarily contain the white color under palette index (2^ScreenDepth-1). cl::Set thus signals that the value should be "all ones", no matter what color it represents, because it will be used for logical operations.

Fonts

Prima maintains its own font naming convention, that usually does not conform to the system's. Since Prima's goal is interoperability, it might be so that some system fonts would not be accessible from within the toolkit.

Prima::Drawable provides property ::font, that accepts/returns a hash, that represents the state of a font in the system graphic context. The font hash keys that are acceptable on set-call are:

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).

height

An integer value from 1 to MAX_INT. Specifies the desired extent of a font glyph between descent and ascent lines in pixels.

size

An integer value from 1 to MAX_INT. Specifies the desired extent of a font glyph between descent and internal leading lines in points. The relation between size and height is

          height - internal_leading
size =  --------------------------- * 72.27
               resolution

That differs from some other system representations: Win32, for example, rounds 72.27 constant to 72.

width

A integer value from 0 to MAX_INT. 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.

style

A combination of fs:: ( font style ) constants. The constants

fs::Normal
fs::Bold
fs::Thin
fs::Italic
fs::Underlined
fs::StruckOut
fs::Outline

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.

pitch

One of three constants:

fp::Default
fp::Fixed
fp::Variable

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.

vector

One of three constants:

fv::Default
fv::Bitmap
fv::Outline

fv::Default specifies no interest about font type selection, fv::Bitmap sets priority for the bitmap fonts, fv::Outline for the vector fonts.

Additionally, font entries returned from fonts method may set vector to fv::ScalableBitmap, to distingush a bitmap font face that comes with predefined bitmap sets from a scalable font.

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 with the one that can.

encoding

A string value, one of the strings returned by Prima::Application::font_encodings. Selects desired font encoding; if empty, picks the first matched encoding, preferably the locale set up by the user.

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.

Unix systems and the toolkit PostScript interface usually provide the following encodings:

iso8859-1
iso8859-2
... other iso8859 ...
fontspecific

Win32 returns the literal strings like

Western
Baltic
Cyrillic
Hebrew
Symbol

A hash that ::font returns, is a tied hash, whose keys are also available as separate properties. For example,

$x = $d-> font-> {style};

is equivalent to

$x = $d-> font-> style;

While the latter gives nothing but the arguable coding convenience, its usage in set-call is much more usable:

$d-> font-> style( fs::Bold);

instead of

my %temp = %{$d-> font};
$temp{ style} = fs::Bold;
$d-> font( \%temp);

The properties of a font tied hash are also accessible through set() call, like in Prima::Object:

$d-> font-> style( fs::Bold);
$d-> font-> width( 10);

is an equivalent to

$d-> font-> set(
   style => fs::Bold,
   width => 10,
);

When get-called, ::font property returns a hash where more entries than the described above can be found. These keys are read-only, their values are ignored if passed to ::font in a set-call.

In order to query the full list of fonts available to a graphic device, the ::fonts method is used. This method is not present in Prima::Drawable namespace; it can be found in two built-in class instances, Prima::Application and Prima::Printer.

Prima::Application::fonts returns metrics for the fonts available to the screen device, while Prima::Printer::fonts ( 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 Prima::Drawable::font method.

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).

ascent

Number of pixels between a glyph baseline and descent line.

descent

Number of pixels between a glyph baseline and descent line.

internalLeading

Number of pixels between ascent and internal leading lines. Negative if the ascent line is below the internal leading line.

externalLeading

Number of pixels between ascent and external leading lines. Negative if the ascent line is above the external leading line.

weight

Font designed weight. Can be one of

fw::UltraLight
fw::ExtraLight
fw::Light
fw::SemiLight
fw::Medium
fw::SemiBold
fw::Bold
fw::ExtraBold
fw::UltraBold

constants.

maximalWidth

Maximal extent of a glyph in pixels. Equals to width in monospaced fonts.

xDeviceRes

Designed horizontal font resolution in dpi.

yDeviceRes

Designed vertical font resolution in dpi.

firstChar

Index of the first glyph present in a font.

lastChar

Index of the last glyph present in a font.

breakChar

Index of the default character used to divide words. In a typical western language font it is 32, ASCII space character.

defaultChar

Index of a glyph that is drawn instead of nonexistent glyph if its index is passed to the text drawing routines.

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:

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.

ABC metrics returned by the get_font_abc() method.

The corresponding vertical metrics, called in Prima DEF metrics, are returned by the get_font_def() method.

Raster operations

A drawable has two raster operation properties: ::rop and ::rop2. These define how the graphic primitives are plotted. ::rop deals with the foreground color drawing, and ::rop2 with the background.

Universal ROPs

The toolkit defines the following operations:

Usually, however, graphic devices support only a small part of the above set, limiting ::rop to the most important operations: Copy, And, Or, Xor, NoOp. ::rop2 is usually even more restricted, supports only Copy and NoOp.

The raster operations apply to all graphic primitives except SetPixel.

Note for layering: using layered images and device bitmaps with put_image and stretch_image can only use rop::SrcCopy and rop::SrcOver raster operations on OS-provided surfaces.

Also, rop::AlphaCopy operation is available for accessing alpha bits only. When used, the source image is treated as alpha mask, and therefore it has to be grayscale. It can be used to apply the alpha bits independently, without need to construct an Icon object.

Additional ROPs

Prima implements extra features for compositing on images outside the begin_paint/end_paint brackets. It supports the following 12 Porter-Duff operators and some selected Photoshop blend operators:

Transparency control

There is defined a set of constants to apply a constant source and destination alpha to when there is no alpha channel available:

rop::SrcAlpha
rop::SrcAlphaShift
rop::DstAlpha
rop::DstAlphaShift

Combine the rop constant using this formula:

$rop = rop::XXX |
   rop::SrcAlpha | ( $src_alpha << rop::SrcAlphaShift ) |
   rop::DstAlpha | ( $src_alpha << rop::DstAlphaShift )

or rop::alpha($rop, [ $src_alpha, [ $dst_alpha ]]) call that does the same.

Also, the function rop::blend($alpha) creates a rop constant for simple blending of two images by the following formula:

$dst = ( $src * $alpha + $dst * ( 255 - $alpha ) ) / 255

rop::alpha also can be used for drawing on image outside begin_paint/end_paint:

$image->rop( rop::alpha( rop::SrcOver, 128 ));
$image->ellipse( 5, 5, 5, 5 );

When used with icons, their source and/or destination alpha channels are additionally multiplied with these values.

rop::Premultiply

When this bit is set, source pixels will be multiplied with alpha before blending

rop::ConstantColor

This bit is used when the alpha is defined but the main bits aren't. In this case, the main bits are filled from the destination's image color, and the source image treated as alpha channel. The following code applies a solid green shade with a mask loaded from file.

$src->load('8-bit gray mask.png');
$dst->color(cl::LightGreen);
$dst->put_image( 0,0,$src,rop::SrcOver | rop::ConstantColor | rop::Premultiply);

Also, remember rop::Premultiply for proper results.

Coordinates

The Prima toolkit employs the XY grid, where X ascends rightwards and Y ascends upwards. There, the (0,0) location is the bottom-left pixel of a canvas.

All graphic primitives use inclusive-inclusive boundaries. For example,

$d-> bar( 0, 0, 1, 1);

plots a bar that covers 4 pixels: (0,0), (0,1), (1,0) and (1,1).

The coordinate origin can be shifted using ::translate property, that translates the (0,0) point to the given offset. Calls to ::translate, ::clipRect and ::region always use the 'physical' (0,0) point, whereas the plotting methods use the transformation result, the 'logical' (0,0) point.

As noted before, these three properties cannot be used in when an object is in the disabled state.

API

Graphic context properties

backColor COLOR

Sets background color to the graphic context. All drawing routines that use non-solid or transparent fill or line patterns use this property value.

color COLOR

Sets foreground color to the graphic context. All drawing routines use this property value.

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

$d-> clipRect( 1, 1, 2, 2);
$d-> bar( 0, 0, 1, 1);

thus affects only one pixel at (1,1).

Set-call discards the previous ::region value.

Note: ::clipRect can not be used while the object is in the paint-disabled state, its context is neither recorded nor used as a template ( see "Graphic context and canvas").

fillMode INTEGER

Affects filling style of complex polygonal shapes filled by fillpoly. If fm::Winding, the filled shape contains no holes; if fm::EvenOdd, holes are present where the shape edges cross.

fm::Overlay flag can be combined with these to counter an intrinsic defect of filled shaped both in Win32 and X11 that don't exactly follow polygon vertices. When supplied, it overlays a polygon over the filled shape, so that the latter falls exactly in the boundaries defined by vertices. This is desirable when one wants to follow polygon vertices, but is not desirable when a shape has holes in it connected in a way that the polygon overlay may leave connection edges over them.

Default value: fm::Winding|fm::Overlay

fillPattern ( [ @PATTERN ] ) or ( fp::XXX )

Selects 8x8 fill pattern that affects primitives that plot filled shapes: bar(), fill_chord(), fill_ellipse(), fillpoly(), fill_sector(), floodfill().

Accepts either a fp:: 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.

There are some predefined patterns, that can be referred via fp:: constants:

( the actual patterns are hardcoded in primguts.c ) The default pattern is fp::Solid.

An example below shows encoding of fp::Parquet pattern:

# 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 ]);

On a get-call always returns an array, never a fp:: constant.

fillPatternOffset X, Y

Origin coordinates for the fillPattern, from 0 to 7.

font \%FONT

Manages font context. FONT hash acceptable values are name, height, size, width, style and pitch.

Synopsis:

$d-> font-> size( 10);
$d-> font-> name( 'Courier');
$d-> font-> set(
  style => $x-> font-> style | fs::Bold,
  width => 22
);

See "Fonts" for the detailed descriptions.

Applies to text_out(), get_text_width(), get_text_box(), get_font_abc(), get_font_def(), render_glyph().

fontMapperPalette INDEX, [\%FONT | COMMAND]

A pseudo-property that manages access to a set of fonts used for substitution in polyfont shaping (see "text_shape"). INDEX is the same font index used in fonts array returned from text_shape, if polyfont was used (where 0 is the current font).

There are two font lists used in the substituion mechanism, passive and active. The passive font list is initiated during the toolkit start and is never changed. Each font there is addressed by INDEX. When the actual search for a glyph is initiated, these fonts are queried in the loop and are checked if they contain the required glyphs. These queries are cached, so that next time lookups run much quicker. That way, an active font list is built, and next substitutions use it before trying to look into the passive list. Since the ordering of fonts is system based, and is rather random, some fonts may not be a good or aesthetic substition. Therefore fontMapperPallette can assist in adding or removing particular fonts to the active list, potentially allowing an application to store and load user-driven selection of substitution fonts.

fontMapperPallette is a pseudo-property, such that it is not symmetric as real properties are; its call formats are several and not orthogonal to each other neither in syntax nor functionality. Therefore these may change in future.

As a getter, the property returns the following depending on INDEX: If it is -1, returns how many fonts are in the passive list. If 0, which means the current font, returns the index of the current font if it is found in the palette, or 0 otherwise. If greater than zero, returns the substitution FONT record from the passive list.

As a setter, manages the active list, and uses COMMAND integer as a second argument. If COMMAND is 0, removes the INDEXth font from the active list, and if 1, marks it for immediate scanning and adding to the active list. The font is added in the end of the list, after the existing active entries.

lineEnd VALUE

Selects a line ending cap for plotting primitives. VALUE can be one of

constants. le::Round is the default value.

lineJoin VALUE

Selects a line joining style for polygons. VALUE can be one of

constants. lj::Round is the default value.

linePattern PATTERN

Selects a line pattern for plotting primitives. PATTERN is either a predefined lp:: constant, or a string where each even byte is a length of a dash, and each odd byte is a length of a gap.

The predefined constants are:

Not all systems are capable of accepting user-defined line patterns, and in such situation the lp:: constants are mapped to the system-defined patterns. In Win9x, for example, lp::DashDotDot is much different from its string definition.

Default value is lp::Solid.

lineWidth WIDTH

Selects a line width for plotting primitives. If a VALUE is 0, then a cosmetic pen is used - the thinnest possible line that a device can plot. If a VALUE is greater than 0, then a geometric pen is used - the line width is set in device units. There is a subtle difference between VALUE 0 and 1 in a way the lines are joined.

Default value is 0.

miterLimit VALUE

When path segments connect at a sharp angle, a miter join results in a spike that extends well beyond the connection point. The purpose of the miter limit is to cut off such spikes when they become objectionably long. At any given corner, the miter length is the distance from the point at which the inner edges of the stroke intersect to the point at which the outside edges of the strokes intersect-in other words, the diagonal length of the miter. This distance increases as the angle between the segments decreases. If the ratio of the miter length to the line width exceeds the miter limit parameter, stroke treats the corner with a bevel join instead of a miter join. The ratio of miter length to line width is directly related to the angle j between the segments by the formula:

r = 1/sin(j/2)

Default value is 10.0.

Asssuming line join is lj::Miter and line angle is 30 degrees:

Note: does not work under X11.

palette [ @PALETTE ]

Selects solid colors in a system palette, as many as possible. PALETTE is an array of integer triplets, where each is R, G and B component. The call

$d-> palette([128, 240, 240]);

selects a gray-cyan color, for example.

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.

region OBJECT

Selects a clipping region applied to all drawing and painting routines. On setting, the OBJECT 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 OBJECT is applied to the system clipping region. Or, it is a Prima::Region object. If the OBJECT is smaller than the drawable, its exterior is assigned to clipped area as well. Discards the previous ::clipRect value; successive get-calls to ::clipRect return the boundaries of the region.

On getting, OBJECT is either undef or Prima::Region object.

Note: ::region can not be used while the object is in the paint-disabled state, its context is neither recorded nor used as a template ( see "Graphic context and canvas").

resolution X, Y

A read-only property. Returns horizontal and vertical device resolution in dpi.

rop OPERATION

Selects raster operation that applies to foreground color plotting routines.

See also: ::rop2, "Raster operations".

rop2 OPERATION

Selects raster operation that applies to background color plotting routines.

Other properties

height HEIGHT: Selects the height of a canvas.
size WIDTH, HEIGHT: Selects the extent of a canvas.
width WIDTH: Selects the width of a canvas.

Graphic primitives methods

alpha ALPHA <X1, Y1, X2, Y2>

Fills rectangle in the alpha channel, filled with ALPHA value (0-255) within (X1,Y1) - (X2,Y2) extents. Can be called without parameters, in this case fills all canvas area.

Has only effect on layered surfaces.

arc X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE

Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes from START_ANGLE to END_ANGLE.

Context used: color, backColor, lineEnd, linePattern, lineWidth, miterLimit, rop, rop2

bar X1, Y1, X2, Y2

Draws a filled rectangle within (X1,Y1) - (X2,Y2) extents.

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2

bars @RECTS

Draws a set of filled rectangles. RECTS is an array of integer quartets in format (X1,Y1,X2,Y2).

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2

chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE

Plots an arc with center in X, Y and DIAMETER_X and DIAMETER_Y axes from START_ANGLE to END_ANGLE and connects its ends with the straight line.

Context used: color, backColor, lineEnd, linePattern, lineWidth, miterLimit, rop, rop2

clear <X1, Y1, X2, Y2>

Draws rectangle filled with pure background color within (X1,Y1) - (X2,Y2) extents. Can be called without parameters, in this case fills all canvas area.

Context used: backColor, rop2

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 FLAGS and TAB_INDENT tab character expansion.

draw_text is a convenience wrapper around text_wrap for drawing the wrapped text, and also provides the tilde ( ~ )- character underlining support.

The FLAGS is a combination of the following constants:

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 ( \t ) 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

Context used: color, backColor, font, rop, textOpaque, textOutBaseline

ellipse X, Y, DIAMETER_X, DIAMETER_Y

Plots an ellipse with center in X, Y and DIAMETER_X and DIAMETER_Y axes.

Context used: color, backColor, linePattern, lineWidth, rop, rop2

fill_chord X, Y, DIAMETER_X, DIAMETER_Y, START_ANGLE, END_ANGLE

Fills a chord outline with center in X, Y and DIAMETER_X and DIAMETER_Y axes from START_ANGLE to END_ANGLE (see chord()).

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2

fill_ellipse X, Y, DIAMETER_X, DIAMETER_Y

Fills an elliptical outline with center in X, Y and DIAMETER_X and DIAMETER_Y axes.

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2

fillpoly \@POLYGON

Fills a polygonal area defined by POLYGON set of points. POLYGON must present an array of integer pair in (X,Y) format. Example:

$d-> fillpoly([ 0, 0, 15, 20, 30, 0]); # triangle

Context used: color, backColor, fillPattern, fillPatternOffset, rop, rop2, fillMode

Returns success flag; if failed, $@ contains the error.

Methods

begin_paint

Enters the enabled ( active paint ) state, returns success flag; if failed, $@ contains the error. Once the object is in enabled state, painting and drawing methods can perform write operations on a canvas.

See also: end_paint, begin_paint_info, "Graphic context and canvas"

begin_paint_info

Enters the information state, returns success flag; if failed, $@ contains the error. The object information state is same as enabled state ( see begin_paint), except painting and drawing methods do not change the object canvas.

See also: end_paint_info, begin_paint, "Graphic context and canvas"

end_paint

Exits the enabled state and returns the object to a disabled state.

See also: begin_paint, "Graphic context and canvas"

end_paint_info

Exits the information state and returns the object to a disabled state.

See also: begin_paint_info, "Graphic context and canvas"

font_match \%SOURCE, \%DEST, PICK = 1

Performs merging of two font hashes, SOURCE and DEST. Returns the merge result. If PICK is true, matches the result with a system font repository.

Called implicitly by ::font on set-call, allowing the following example to work:

$d-> font-> set( size => 10);
$d-> font-> set( style => fs::Bold);

In the example, the hash 'style => fs::Bold' does not overwrite the previous font context ( 'size => 10' ) but gets added to it ( by font_match()), providing the resulting font with both font properties set.

fonts <FAMILY = "", ENCODING = "">

Member of Prima::Application and Prima::Printer, does not present in Prima::Drawable.

Returns an array of font metric hashes for a given font FAMILY and ENCODING. Every hash has full set of elements described in "Fonts".

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 encodings entry, which points to an array of encodings available for the font.

If called with FAMILY parameter set but no ENCODING is set, enumerates all combinations of fonts with all available encodings.

If called with FAMILY set to an empty string, but ENCODING specified, returns only fonts that can be displayed with the encoding.

Example:

print sort map {"$_->{name}\n"} @{$::application-> fonts};

get_bpp

Returns device color depth. 1 is for black-and-white monochrome, 24 for true color, etc.

get_font_abc FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0

Returns ABC font metrics for the given range, starting at FIRST_CHAR and ending with LAST_CHAR. If parameters are -1, the default range ( 0 and 255 ) is assumed. UNICODE 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.

The result is an integer array reference, where every character glyph is referred by three integers, each triplet containing A, B and C values.

For detailed explanation of ABC meaning, see "Font ABC metrics";

Context used: font

get_font_def FIRST_CHAR = -1, LAST_CHAR = -1, UNICODE = 0

Same as get_font_abc, but for vertical mertics. Is expensive on bitmap fonts, because to find out the correct values Prima has to render glyphs on bitmaps and scan for black and white pixels.

Vector fonts are not subject to this, and the call is as effective as get_font_abc.

get_font_languages

Returns array of ISO 639 strings that can be displayed using glyphs available in the currently selected font.

get_font_ranges

Returns array of integer pairs denoting unicode indices of glyphs covered by the currently selected font. Each pair is the first and the last index of a contiguous range.

Context used: font

get_nearest_color COLOR

Returns a nearest possible solid color in representation of the graphic device. Always returns same color if the device bit depth is equal or greater than 24.

get_paint_state

Returns paint state value on of ps:: constants - ps::Disabled if the object is in the disabled state, ps::Enabled for the enabled state, ps::Information for the information state.

For brevity, mb::Disabled is equal to 0 so this allows for simple boolean testing whether one can get/set graphical properties on an object.

See "Graphic context and canvas" for more.

get_physical_palette

Returns an array of integers in (R,G,B) format, where each color entry is in the 0 - 255 range.

The physical palette array is non-empty only on paletted graphic devices, the true color devices return an empty array.

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 request to change the system colors at any moment.

get_text_shape_width TEXT, [ FLAGS ]

Runs shaping on TEXT character string with text direction either taken from FLAGS & to::RTL value, or from the or $::application->textDirection. Returns the shaping result width as if it would be drawn using currently selected font.

If FLAGS & to::AddOverhangs is set, the first character's absolute A value and the last character's absolute C value are added to the string if they are negative.

get_text_width TEXT, ADD_OVERHANG = 0

Returns TEXT string width if it would be drawn using currently selected font. TEXT is either a character string, or a Prima::Drawable::Glyphs object returned from text_shape, or Prima::Drawable::Glyphs-> glyphs glyph string.

If ADD_OVERHANG 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.

See more on ABC values at "Font ABC metrics".

Context used: font

get_text_box TEXT

Returns TEXT string extensions if it would be drawn using currently selected font. TEXT is either a character string, or a Prima::Drawable::Glyphs object returned from text_shape, or Prima::Drawable::Glyphs-> glyphs glyph string.

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):

1: start of string at ascent line ( top left )

2: start of string at descent line ( bottom left )

3: end of string at ascent line ( top right )

4: end of string at descent line ( bottom right )

5: concatenation point

The concatenation point coordinates (XC,YC) are coordinated passed to consequent text_out() call so the conjoint string would plot as if it was a part of TEXT. Depending on the value of the textOutBaseline property, the concatenation point is located either on the baseline or on the descent line.

Context used: font, textOutBaseline

render_glyph INDEX, %OPTIONS

Returns glyph representation as an outline. The outline is an integer array, formed as a set of plotting commands. Each commnds is a ggo:: constant, followed by number of points, followed by the 2D point coordinates in 1/64 pixels.

Options recognized:

glyph BOOL: If set, INDEX is treated as the glyph index rather than character index. Default is false.
hints BOOL: Is set, hinting is enabled. Default is true.
unicode BOOL: If set, INDEX is threated as a utf8 character index, otherwise a locale-specific index. Default is false.

The ggo:: commands are:

ggo::Move  - move point
ggo::Line  - plot line
ggo::Conic - plot 2-degree spline
ggo::Cubic - plot 3-degree spline

render_spline \@VERTICES, %OPTIONS

Renders B-spline curve from set of VERTICES to a polyline with given options.

The method is internally used by spline and fill_spline, and is provided for cases when these are insufficient. See description of options in spline.

text_wrap TEXT, WIDTH, OPTIONS, TAB_INDENT = 8

Breaks TEXT string in chunks that must fit into WIDTH pixels wide box. TEXT is either character string, or a Prima::Drawable::Glyphs object returned from text_shape, or Prima::Drawable::Glyphs->glyphs strings of glyphs. In the glyph cases, some wrapping options are not applicable.

The break algorithm and its result are governed by OPTIONS integer value which is a combination of tw:: constants:

tw::CalcMnemonic

Use 'hot key' semantics, when a character preceded by ~ has special meaning, f ex it gets underlined when used in menus. If this bit is set, the first tilde character used as an escape is not calculated, and never appears in the result apart from the escaped character.

Not applicable in glyph wrapping.

tw::CollapseTilde

In addition to tw::CalcMnemonic, removes '~' character from the resulting chunks.

Not applicable in glyph wrapping.

tw::CalcTabs

If set, calculates a tab ('\t') character as TAB_INDENT times space characters.

Not applicable in glyph wrapping.

tw::ExpandTabs

If set, expands tab ('\t') character as TAB_INDENT times space characters.

Not applicable in glyph wrapping.

tw::BreakSingle

Defines procedure behavior when the text cannot be fit in WIDTH, does not affect anything otherwise.

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 will exceed WIDTH.

tw::NewLineBreak

Forces new chunk after a newline character ('\n') is met. If UTF8 text is passed, unicode line break characters 0x2028 and 0x2029 produce same effect as the newline character.

Not applicable in glyph wrapping.

tw::SpaceBreak

Forces new chunk after a space character (' ') or a tab character ('\t') are met.

Not applicable in glyph wrapping.

tw::ReturnChunks

Defines the result of text_wrap() function.

If set, the array consists of integer pairs, where each is a text offset within TEXT and its length.

If unset, the resulting array consists of text chunks.

tw::ReturnLines

Equals to 0, is a mnemonic to an unset tw::ReturnChunks.

Not applicable in glyph wrapping.

tw::WordBreak

If unset, the TEXT breaks as soon as the chunk width exceeds WIDTH. If set, tries to keep words in TEXT so they do not appear in two chunks, e.g. breaks TEXT by words, not by characters.

Not applicable in glyph wrapping.

tw::ReturnFirstLineLength

If set, text_wrap proceeds until the first line is wrapped, either by width or ( if specified ) by break characters. Returns the length of the resulting line. Used for efficiency as the inverted get_text_width function.

If OPTIONS has tw::CalcMnemonic or tw::CollapseTilde bits set, then the last scalar of the array is a special hash reference. The hash contains extra information regarding the 'hot key' underline position - it is assumed that '~' - escapement denotes the underlined character. The hash contains the following keys:

tildeLine: Chunk index that contains the escaped character. Set to undef if no ~ - escape was found; the rest of the information in the hash is not relevant in this case.
tildeStart: Horizontal offset of a beginning of the line that underlines the escaped character.
tildeEnd: Horizontal offset of an end of the line that underlines the escaped character.
tildeChar: The escaped character.

Context used: font

text_wrap_shape TEXT, WIDTH, %OPTIONS

Runs text_shape over results from text_wrap call, with TEXT, WIDTH, $OPTIONS{options} and $OPTIONS{tabs}. Other %OPTIONS are used in text_shape call. Where text_wrap returns text substrings or positions, return glyphs objects or their positions instead.

When called with tw::CalcMnemonic options, recalculates the tilde position so it adapts to the glyph positions returned.

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

USAGE

Graphic context and canvas

Color space

Monochrome bitmaps

Fonts

Font ABC metrics

Raster operations

Universal ROPs

Additional ROPs

Coordinates

API

Graphic context properties

Other properties

Graphic primitives methods

Methods

AUTHOR

SEE ALSO

Module Install Instructions