►Draw:   Drawing Toolkit
▼5 Drawing Utensils
5.1 Color
5.2 Pen
5.3 Brush
5.4 Font
5.5 Region
5.6 Path
On this page:
Region
Region.dc
Region.is_  empty
Region.contains
Region.polygon
Region.rectangle
Region.rounded_  rectangle
Region.ellipse
Region.arc
Region.path
Region.union
Region.intersect
Region.subtract
Region.xor
Region.Fill
Region.Fill.odd_  even
Region.Fill.winding
Region.handle
Region.from_  handle
0.45+9.0.900
Rhombus
  top  contents    up   

5.5 Region🔗ℹ

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

class

class draw.Region():

  constructor (dc :: maybe(DC) = #false)

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 Rhombus.union 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.

property

property (rgn :: draw.Region).dc :: maybe(DC)

Reports the drawing context that the region is specific to, if any.

method

method (rgn :: draw.Region).is_empty() :: Boolean

 

method

method (rgn :: draw.Region).contains(pt :: PointLike) :: Boolean

Queries the content represented by the region.

method

method (rgn :: draw.Region).polygon(

  [pt :: PointLike, ...],

  ~dpt: dpt :: PointLike = Point.zero,

  ~dx: dx :: Real = 0,

  ~dy: dy :: Real = 0,

  ~fill: fill :: Region.Fill = #'even_odd

) :: Void

Sets the region to the interior of the polygon specified by pts. Them fill style determines how multiple loops are handled in the same way as DC.polygon.

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

method

method (rgn :: draw.Region).rectangle(r :: RectLike)

  :: Void

Sets the region to the interior of the specified rectangle. See also DC.rectangle, 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.

method

method (rgn :: draw.Region).rounded_rectangle(r :: RectLike,

                                              radius :: Real = -0.25)

  :: Void

Sets the region to the interior of the specified rounded rectangle. See also DC.rounded_rectangle, 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.

method

method (rgn :: draw.Region).ellipse(r :: RectLike)

  :: Void

Sets the region to the interior of an ellipse bounded by the specified rectangle. See also DC.ellipse, 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.

method

method (rgn :: draw.Region).arc(r :: RectLike,

                                start :: Real, end :: Real)

  :: Void

Sets the region to the interior of a wedged form by the specified arc. See also DC.arc, 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.

method

method (rgn :: draw.Region).path(

  p :: draw.Path,

  ~dpt: dpt :: PointLike = Point.zero,

  ~dx: dx :: Real = 0,

  ~dy: dy :: Real = 0,

  ~fill: fill :: Region.Fill = #'odd_even

) :: Void

Sets the region’s path to the given path. Them fill style determines how multiple loops are handled in the same way as Region.polygon. See also DC.path, 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 Region.union, Region.xor, and Region.subtract. The region is also atomic for the purposes of region combination.

method

method (rgn :: draw.Region).union(rgn2 :: Region) :: Void

 

method

method (rgn :: draw.Region).intersect(rgn2 :: Region) :: Void

 

method

method (rgn :: draw.Region).subtract(rgn2 :: Region) :: Void

 

method

method (rgn :: draw.Region).xor(rgn2 :: Region) :: Void

Changes the region by applying a combination with another region. The other region, rgn2, is not modified. The drawing context of rgn and rgn2 must be the same, or they must both be unassociated to any drawing context.

A Region.intersect corresponds to clipping with rgn’s path, and then clipping with rgn2’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 intersected region is a poor input for Region.union, Region.subtract, or Region.xor, but it intersects properly in further calls to Region.intersect.

A Region.union corresponds to combining the subpaths 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 if 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.

A Region.subtract corresponds to combining the subpaths of rgn region with the reversed subpaths of rgn2, then intersecting the result with rgn. This fails as a true subtraction, because the boundary of loops (with either #'odd_even or #'winding filling) is ambiguous.

A Region.xor corresponds to combining the subpaths of rgn with the reversed subpaths of rgn2. 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 #'odd_even fill.

enumeration

enum draw.Region.Fill

| odd_even

| winding

A region polygon-fill mode.

property

property (path :: draw.Region).handle :: Any

 

function

fun draw.Region.from_handle(hand :: Any) :: Region

The Region.handle property returns a Racket object that corresponds to the region for use directly with racket/draw. The Region.from_handle function creates a Region from such a Racket object.

  top  contents    up