NAME

Prima::Region - generic shape for clipping and hit testing

SYNOPSIS

$empty = Prima::Region->new;

$rect  = Prima::Region->new( rect => [ 10, 10, 20, 20 ]);
$rect  = Prima::Region->new( box  => [ 10, 10, 10, 10 ]); # same

$poly  = Prima::Region->new( polygon => [ 0, 0, 100, 0, 100, 100 ]);

$bits  = Prima::Region->new( image => $image );

$drawable-> region( $rect );

my $rgn = $drawable->region;
$rgn->image->save('region.png') if $rgn;

DESCRIPTION

Prima::Region is a descendant of Prima::Component. It serves a representation of a generic shape, that can be applied to a drawable, and checked whether points are within its boundaries.

API

new %OPTIONS

Creates new region object. Without options, the region is empty. Following options can be used:

rect => [ X1, Y1, X2, Y2 ]

Create rectangular region with inclusive-inclusive coordinates.

box => [ X, Y, WIDTH, HEIGHT ]

Same as rect but using other semantics.

polygon => \@POINTS, fillMode = 0

Creates a polygon shape with vertices given in @POINTS, and using an optional fillMode ( see "fillMode" in Drawable ).

image => IMAGE

Creates a region that mirrors 1-bits in the image. If no pixels are set to 1, the region will be effectively empty.

bitmap with_offset => 0, type => dbt::Bitmap

Paints the region on a newly created bitmap and returns it. By default, region offset is not included.

box

Returns (X,Y,WIDTH,HEIGHT) bounding box, that encloses smallest possible rectangle, or (0,0,0,0) if the region is empty.

combine REGION, OPERATION = rgnop::Copy

Applies one of the following set operation to the region:

rgnop::Copy

Makes a copy of the REGION

rgnop::Intersect

The resulting region is an intersection of the two regions.

rgnop::Union

The resulting region is a union of the two regions.

rgnop::Xor

Performs XOR operation on the two regions.

rgnop::Diff

The resulting region is a difference of the two regions.

dup

Creates a duplicate region object

get_boxes

Returns a Prima::array object filled with 4-integer tuples, where each is a box defined as (x,y,width,height).

get_handle

Returns a system handle for the region

equals REGION

Returns true if the regions are equal, false otherwise.

image with_offset => 0, type => dbt::Bitmap

Paints the region on a newly created image and returns it. By default, region offset is not included.

is_empty

Returns true if the region is empty, false otherwise.

offset DX, DY

Shifts the region vertically and/or horizontally

point_inside X, Y

Returns true if the (X,Y) point is inside the region

rect_inside X1,Y1,X2,Y2

Checks whether a rectangle given by inclusive-inclusive coordinates is inside, outside, or partially covered by the region. Return values are:

rgn::Inside
rgn::Outside
rgn::Partially

where rgn::Outside has value of 0.

AUTHOR

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

SEE ALSO

Prima, Prima::Drawable, Prima::Drawable::Path