The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

KARASIK / Prima-1.76 / pod / Prima / Region.pod 

            

              
—
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

              
=head1 NAME
Prima::Region - generic shapes for clipping and hit testing
=head1 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;
=head1 DESCRIPTION
The Prima::Region class is a descendant of the Prima::Component class. A
Prima::Region object is a representation of a generic shape that can be
applied to a drawable and checked whether points are within its boundaries.
=head1 API
=over
=item new %OPTIONS
Creates a new region object. If called without any options then the resulting region will be empty
The following options can be used:
=over
=item rect => [ X1, Y1, X2, Y2 ]
Creates a rectangular region with inclusive-inclusive coordinates.
=item box => [ X, Y, WIDTH, HEIGHT ]
Same as C<rect> but using the I<box> semantics.
=item polygon => \@POINTS, fillMode = 0
Creates a polygon shape with vertices given in C<@POINTS>, and using
the optional fillMode ( see L<Drawable/fillMode> ).
=item image => IMAGE
Creates a region from a 1-bit image. If the image contains no pixels that are
set to 1, the resulting region is created as an empty region.
=back
=item bitmap with_offset => 0, type => dbt::Bitmap
Paints the region on a newly created bitmap and returns it. By default,
the region offset is not included.
=item box
Returns the (X,Y,WIDTH,HEIGHT) bounding box that encloses the smallest possible
rectangle, or (0,0,0,0) if the region is empty.
=item combine REGION, OPERATION = rgnop::Copy
Applies one of the following set operations to the region:
=over
=item rgnop::Copy
Makes a copy of the REGION
=item rgnop::Intersect
The resulting region is an intersection of the two regions.
=item rgnop::Union
The resulting region is a union of the two regions.
=item rgnop::Xor
Performs XOR operation on the two regions.
=item rgnop::Diff
The resulting region is a difference between the two regions.
=back
=item dup
Creates a duplicate region object
=item get_boxes
Returns a C<Prima::array> object filled with 4-integer tuples, where each is a
box defined as a (x,y,width,height) tuple.
=item get_handle
Returns the system handle for the region
=item equals REGION
Returns true if the regions are equal, false otherwise.
=item image with_offset => 0, type => dbt::Bitmap
Paints the region on a newly created image and returns it. By default,
the region offset is not included.
=item is_empty
Returns true if the region is empty, false otherwise.
=item offset DX, DY
Shifts the region vertically and/or horizontally
=item point_inside X, Y
Returns true if the (X,Y) point is inside the region
=item rect_inside X1,Y1,X2,Y2
Checks whether a rectangle given by the inclusive-inclusive coordinates is inside, outside,
or partially covered by the region. The return value can be one of these flags:
   rgn::Inside
   rgn::Outside
   rgn::Partially
where the C<rgn::Outside> constant has the value of 0.
=back
=head1 AUTHOR
Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.
=head1 SEE ALSO
L<Prima>, L<Prima::Drawable>, L<Prima::Drawable::Path>