1 <!-- ##### SECTION Title ##### -->
2 Points, Rectangles and Regions
4 <!-- ##### SECTION Short_Description ##### -->
5 simple graphical data types.
7 <!-- ##### SECTION Long_Description ##### -->
9 GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
10 for representing pixels and sets of pixels on the screen.
13 #GdkPoint is a simple structure containing an x and y coordinate of a point.
16 #GdkRectangle is a structure holding the position and size of a rectangle.
17 The intersection of two rectangles can be computed with
18 gdk_rectangle_intersect(). To find the union of two rectangles use
19 gdk_rectangle_union().
22 #GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
23 usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
26 #GdkSpan is a structure holding a spanline. A spanline is a horizontal line that
27 is one pixel wide. It is mainly used when rasterizing other graphics primitives.
28 It can be intersected to regions by using gdk_region_spans_intersect_foreach().
31 <!-- ##### SECTION See_Also ##### -->
36 <!-- ##### STRUCT GdkPoint ##### -->
44 <!-- ##### STRUCT GdkRectangle ##### -->
54 <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
65 <!-- ##### FUNCTION gdk_rectangle_union ##### -->
75 <!-- ##### STRUCT GdkRegion ##### -->
77 A GdkRegion represents a set of pixels on the screen.
78 The only user-visible field of the structure is the user_data member, which
79 can be used to attach arbitrary data to the #GdkRegion.
83 <!-- ##### FUNCTION gdk_region_new ##### -->
85 Creates a new empty #GdkRegion.
88 @Returns: a new empty #GdkRegion.
91 <!-- ##### FUNCTION gdk_region_polygon ##### -->
93 Creates a new #GdkRegion using the polygon defined by a number of points.
97 @points: an array of #GdkPoint structs.
98 @npoints: the number of elements in the @points array.
99 @fill_rule: specifies which pixels are included in the region when the polygon
101 @Returns: a new #GdkRegion based on the given polygon.
104 <!-- ##### ENUM GdkFillRule ##### -->
106 The method for determining which pixels are included in a region, when
107 creating a #GdkRegion from a polygon.
108 The fill rule is only relevant for polygons which overlap themselves.
111 @GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
112 included in the region, while areas overlapped an even number of times are not.
113 @GDK_WINDING_RULE: overlapping areas are always included.
115 <!-- ##### FUNCTION gdk_region_copy ##### -->
124 <!-- ##### FUNCTION gdk_region_rectangle ##### -->
133 <!-- ##### FUNCTION gdk_region_destroy ##### -->
135 Destroys a #GdkRegion.
138 @region: a #GdkRegion.
141 <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
143 Returns the smallest rectangle which includes the entire #GdkRegion.
146 @region: a #GdkRegion.
147 @rectangle: returns the smallest rectangle which includes all of @region.
150 <!-- ##### FUNCTION gdk_region_empty ##### -->
152 Returns TRUE if the #GdkRegion is empty.
155 @region: a #GdkRegion.
156 @Returns: TRUE if @region is empty.
159 <!-- ##### FUNCTION gdk_region_equal ##### -->
161 Returns TRUE if the two regions are the same.
164 @region1: a #GdkRegion.
165 @region2: a #GdkRegion.
166 @Returns: TRUE if @region1 and @region2 are equal.
169 <!-- ##### FUNCTION gdk_region_point_in ##### -->
171 Returns TRUE if a point is in a region.
174 @region: a #GdkRegion.
175 @x: the x coordinate of a point.
176 @y: the y coordinate of a point.
177 @Returns: TRUE if the point is in @region.
180 <!-- ##### FUNCTION gdk_region_rect_in ##### -->
182 Tests whether a rectangle is within a region.
185 @region: a #GdkRegion.
186 @rect: a #GdkRectangle.
187 @Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or
188 GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
189 outside, or partly inside the #GdkRegion, respectively.
192 <!-- ##### ENUM GdkOverlapType ##### -->
194 Specifies the possible values returned by gdk_region_rect_in().
197 @GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion.
198 @GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion.
199 @GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion.
201 <!-- ##### FUNCTION gdk_region_offset ##### -->
203 Moves a region the specified distance.
206 @region: a #GdkRegion.
207 @dx: the distance to move the region horizontally.
208 @dy: the distance to move the region vertically.
211 <!-- ##### FUNCTION gdk_region_shrink ##### -->
213 Resizes a region by the specified amount.
214 Positive values shrink the region. Negative values expand it.
217 @region: a #GdkRegion.
218 @dx: the number of pixels to shrink the region horizontally.
219 @dy: the number of pixels to shrink the region vertically.
222 <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
224 Returns the union of a region and a rectangle.
227 @region: a #GdkRegion.
228 @rect: a #GdkRectangle.
229 <!-- # Unused Parameters # -->
230 @Returns: the union of @region and @rect.
233 <!-- ##### FUNCTION gdk_region_intersect ##### -->
242 <!-- ##### FUNCTION gdk_region_union ##### -->
251 <!-- ##### FUNCTION gdk_region_subtract ##### -->
260 <!-- ##### FUNCTION gdk_region_xor ##### -->