On this page:
get-bounding-box
get-dc
in-region?
intersect
is-empty?
set-arc
set-ellipse
set-path
set-polygon
set-rectangle
set-rounded-rectangle
subtract
union
xor

region% : class?

  superclass: object%

A region% object specifies a portion of a drawing area (possibly discontinuous). It is normally used for clipping drawing operations.

A region% object can be associated to a particular dc<%> object when the region is created. In that case, the region uses the drawing context’s current transformation matrix, translation, scaling, and rotation, independent of the transformation that is in place when the region is installed. Otherwise, the region is transformed as usual when it is installed into a dc<%>. For an auto-scrolled canvas, the canvas’s current scrolling always applies when the region is used (and it does not affect the region’s bounding box).

Region combination with operations like region% union are approximate, and they are implemented by combining paths. Certain combinations work only if the paths have a suitable fill mode, which can be either 'winding, 'even-odd, or a flexible fill mode. When a region is installed as a device context’s clipping region, any subpath with a flexible fill mode uses 'even-odd mode if any other path uses 'even-odd mode.

See also set-clipping-region in dc<%> and get-clipping-region in dc<%>.

(new region% [dc dc])  (is-a?/c region%)
  dc : (or/c (is-a?/c dc<%>) #f)
Creates an empty region. If dc is a dc<%> object, the dc<%>’s current transformation matrix is essentially recorded in the region.

(send a-region get-bounding-box)  
real? real? real? real?
Returns a rectangle that approximately encloses the region. The return values are the left, top, width, and height of the rectangle. If the region has an associated drawing context, the bounding box is in the drawing context’s current logical coordinates.

(send a-region get-dc)  (or/c (is-a?/c dc<%>) #f)
Returns the region’s drawing context, if it was created for one.

(send a-region in-region? x y)  boolean?
  x : real?
  y : real?
Returns #t if the given point is approximately within the region, #f otherwise. If the region has an associated drawing context, the given point is effectively transformed according to the region’s dc<%>’s current transformation matrix.

(send a-region intersect rgn)  void?
  rgn : (is-a?/c region%)
Sets the region to the intersection of itself with the given region.

The drawing context of rgn and a-region must be the same, or they must both be unassociated to any drawing context.

An intersect corresponds to clipping with this region’s path, and then clipping with the given region’s path. Further combining sends to this region correspond to combination with the original path before initial clip, and further combination with this region as an argument correspond to a combination with the given path after the initial clip. Thus, an intersecting region is a poor input for union, subtract, or xor, but it intersects properly in further calls to intersect.

(send a-region is-empty?)  boolean?
Returns #t if the region is approximately empty, #f otherwise, but only if the region is associated with a drawing context. If the region is unassociated to any drawing context, the exn:fail:contract exception is raised.

(send a-region set-arc x    
  y    
  width    
  height    
  start-radians    
  end-radians)  void?
  x : real?
  y : real?
  width : (and/c real? (not/c negative?))
  height : (and/c real? (not/c negative?))
  start-radians : real?
  end-radians : real?
Sets the region to the interior of the specified wedge.

See also draw-ellipse in dc<%>, since the region content is determined the same way as brush-based filling in a dc<%>.

The region corresponds to a clockwise path with a flexible fill. The region is also atomic for the purposes of region combination.

(send a-region set-ellipse x y width height)  void?
  x : real?
  y : real?
  width : (and/c real? (not/c negative?))
  height : (and/c real? (not/c negative?))
Sets the region to the interior of the specified ellipse.

See also draw-ellipse in dc<%>, since the region content is determined the same way as brush-based filling in a dc<%>.

The region corresponds to a clockwise path with a flexible fill. The region is also atomic for the purposes of region combination.

(send a-region set-path path    
  [xoffset    
  yoffset    
  fill-style])  void?
  path : (is-a?/c dc-path%)
  xoffset : real? = 0
  yoffset : real? = 0
  fill-style : (one-of/c 'odd-even 'winding) = 'odd-even
Sets the region to the content of the given path.

See also draw-path in dc<%>, since the region content is determined the same way as brush-based filling in a dc<%>.

The fill style affects how well the region reliably combines with other regions (via union, xor, and subtract). The region is also atomic for the purposes of region combination.

(send a-region set-polygon points    
  [xoffset    
  yoffset    
  fill-style])  void?
  points : 
(or/c (listof (is-a?/c point%))
      (listof (cons/c real? real?)))
  xoffset : real? = 0
  yoffset : real? = 0
  fill-style : (one-of/c 'odd-even 'winding) = 'odd-even
Sets the region to the interior of the polygon specified by points. A pair is treated as a point where the car of the pair is the x-value and the cdr is the y-value.

See also draw-polygon in dc<%>, since the region content is determined the same way as brush-based filling in a dc<%>.

The fill style affects how well the region reliably combines with other regions (via union, xor, and subtract). The region is also atomic for the purposes of region combination.

(send a-region set-rectangle x    
  y    
  width    
  height)  void?
  x : real?
  y : real?
  width : (and/c real? (not/c negative?))
  height : (and/c real? (not/c negative?))
Sets the region to the interior of the specified rectangle.

The region corresponds to a clockwise path with a flexible fill. The region is also atomic for the purposes of region combination.

(send a-region set-rounded-rectangle x    
  y    
  width    
  height    
  [radius])  void?
  x : real?
  y : real?
  width : (and/c real? (not/c negative?))
  height : (and/c real? (not/c negative?))
  radius : real? = -0.25
Sets the region to the interior of the specified rounded rectangle.

See also draw-rounded-rectangle in dc<%>, since the region content is determined the same way as brush-based filling in a dc<%>.

The region corresponds to a clockwise path with a flexible fill. The region is also atomic for the purposes of region combination.

(send a-region subtract rgn)  void?
  rgn : (is-a?/c region%)
Sets the region to the subtraction of itself minus the given region. In other words, a point is removed from the region if it is included in the given region. (The given region may contain points that are not in the current region; such points are ignored.)

This region’s drawing context and given region’s drawing context must be the same, or they must both be unassociated to any drawing context.

The result is consistent across platforms and devices, but it is never a true subtraction. A subtraction corresponds to combining the sub-paths of this region with the reversed sub-paths of the given region, then intersecting the result with this region. This fails as a true subtraction, because the boundary of loops (with either 'odd-even or 'winding filling) is ambiguous.

(send a-region union rgn)  void?
  rgn : (is-a?/c region%)
Sets the region to the union of itself with the given region.

This region’s drawing context and given region’s drawing context must be the same, or they must both be unassociated to any drawing context.

A union corresponds to combining the sub-paths of each region into one path, using an 'odd-even fill if either of the region uses an 'odd-even fill (otherwise using a 'winding fill), a 'winding fill in either region uses a winding fill, or the fill remains a flexible fill if both paths have a flexible fill. Consequently, while the result is consistent across platforms and devices, it is a true union only for certain input regions. For example, it is a true union for non-overlapping atomic and union regions. It is also a true union for atomic and union regions (potentially overlapping) that are all clockwise and use 'winding fill or if the fills are all flexible fills.

(send a-region xor rgn)  void?
  rgn : (is-a?/c region%)
Sets the region to the xoring of itself with the given region (i.e., contains points that are enclosed by exactly one of the two regions).

This region’s drawing context and given region’s drawing context must be the same, or they must both be unassociated to any drawing context.

The result is consistent across platforms and devices, but it is not necessarily a true xoring. An xoring corresponds to combining the sub-paths of this region with the reversed sub-paths of the given region. The result uses an 'odd-even fill if either of the region uses an 'odd-even fill, a 'winding fill in either region uses a winding fill, or the fill remains a flexible fill if both paths have a flexible fill. Consequently, the result is a reliable xoring only for certain input regions. For example, it is reliable for atomic and xoring regions that all use 'even-odd fill.