Package org.eclipse.swt.graphics

## Class Region

- java.lang.Object
- - org.eclipse.swt.graphics.Resource
  - - org.eclipse.swt.graphics.Region

    public final class Region
    extends Resource

Instances of this class represent areas of an x-y coordinate system that are aggregates of the areas covered by a number of polygons.

Application code must explicitly invoke the `Region.dispose()` method to release the operating system resources managed by each instance when those instances are no longer required.

See Also:
  SWT Example: GraphicsExample, Sample code and further information

### Field Summary

Fields
`long` `handle` the OS resource for the region (Warning: This field is platform dependent)

### Constructor Summary

Constructors
`Region()` Constructs a new empty region.
`Region​(Device device)` Constructs a new empty region.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `add​(int[] pointArray)` Adds the given polygon to the collection of polygons the receiver maintains to describe its area.
`void` `add​(int x, int y, int width, int height)` Adds the given rectangle to the collection of polygons the receiver maintains to describe its area.
`void` `add​(Rectangle rect)` Adds the given rectangle to the collection of polygons the receiver maintains to describe its area.
`void` `add​(Region region)` Adds all of the polygons which make up the area covered by the argument to the collection of polygons the receiver maintains to describe its area.
`boolean` `contains​(int x, int y)` Returns `true` if the point specified by the arguments is inside the area specified by the receiver, and `false` otherwise.
`boolean` `contains​(Point pt)` Returns `true` if the given point is inside the area specified by the receiver, and `false` otherwise.
`boolean` `equals​(Object object)` Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.
`Rectangle` `getBounds()` Returns a rectangle which represents the rectangular union of the collection of polygons the receiver maintains to describe its area.
`int` `hashCode()` Returns an integer hash code for the receiver.
`void` `intersect​(int x, int y, int width, int height)` Intersects the given rectangle to the collection of polygons the receiver maintains to describe its area.
`void` `intersect​(Rectangle rect)` Intersects the given rectangle to the collection of polygons the receiver maintains to describe its area.
`void` `intersect​(Region region)` Intersects all of the polygons which make up the area covered by the argument to the collection of polygons the receiver maintains to describe its area.
`boolean` `intersects​(int x, int y, int width, int height)` Returns `true` if the rectangle described by the arguments intersects with any of the polygons the receiver maintains to describe its area, and `false` otherwise.
`boolean` `intersects​(Rectangle rect)` Returns `true` if the given rectangle intersects with any of the polygons the receiver maintains to describe its area and `false` otherwise.
`boolean` `isDisposed()` Returns `true` if the region has been disposed, and `false` otherwise.
`boolean` `isEmpty()` Returns `true` if the receiver does not cover any area in the (x, y) coordinate plane, and `false` if the receiver does cover some area in the plane.
`void` `subtract​(int[] pointArray)` Subtracts the given polygon from the collection of polygons the receiver maintains to describe its area.
`void` `subtract​(int x, int y, int width, int height)` Subtracts the given rectangle from the collection of polygons the receiver maintains to describe its area.
`void` `subtract​(Rectangle rect)` Subtracts the given rectangle from the collection of polygons the receiver maintains to describe its area.
`void` `subtract​(Region region)` Subtracts all of the polygons which make up the area covered by the argument from the collection of polygons the receiver maintains to describe its area.
`String` `toString()` Returns a string containing a concise, human-readable description of the receiver.
`void` `translate​(int x, int y)` Translate all of the polygons the receiver maintains to describe its area by the specified point.
`void` `translate​(Point pt)` Translate all of the polygons the receiver maintains to describe its area by the specified point.
`static Region` `win32_new​(Device device, int handle)` Invokes platform specific functionality to allocate a new region.

### Methods inherited from class org.eclipse.swt.graphics.Resource

`dispose, getDevice`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### handle

    public long handle

the OS resource for the region (Warning: This field is platform dependent)

IMPORTANT: This field is not part of the SWT public API. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms and should never be accessed from application code.

Restriction:
  This field is not intended to be referenced by clients.

### Constructor Detail

#### Region

    public Region()

Constructs a new empty region.

You must dispose the region when it is no longer required.

Throws:
  `SWTError` -
  - ERROR_NO_HANDLES if a handle could not be obtained for region creation
See Also:
  `Resource.dispose()`

#### Region

    public Region​(Device device)

Constructs a new empty region.

You must dispose the region when it is no longer required.

Parameters:
  `device` - the device on which to allocate the region
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if device is null and there is no current device
  `SWTError` -
  - ERROR_NO_HANDLES if a handle could not be obtained for region creation
Since:
  3.0
See Also:
  `Resource.dispose()`

### Method Detail

#### add

    public void add​(int[] pointArray)

Adds the given polygon to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `pointArray` - points that describe the polygon to merge with the receiver
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.0

#### add

    public void add​(Rectangle rect)

Adds the given rectangle to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `rect` - the rectangle to merge with the receiver
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  - ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

#### add

    public void add​(int x,
                    int y,
                    int width,
                    int height)

Adds the given rectangle to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `x` - the x coordinate of the rectangle
  `y` - the y coordinate of the rectangle
  `width` - the width coordinate of the rectangle
  `height` - the height coordinate of the rectangle
Throws:
  `IllegalArgumentException` -
  - ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.1

#### add

    public void add​(Region region)

Adds all of the polygons which make up the area covered by the argument to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `region` - the region to merge
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  - ERROR_INVALID_ARGUMENT - if the argument has been disposed
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

#### contains

    public boolean contains​(int x,
                            int y)

Returns `true` if the point specified by the arguments is inside the area specified by the receiver, and `false` otherwise.

Parameters:
  `x` - the x coordinate of the point to test for containment
  `y` - the y coordinate of the point to test for containment
Returns:
  `true` if the region contains the point and `false` otherwise
Throws:
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

#### contains

    public boolean contains​(Point pt)

Returns `true` if the given point is inside the area specified by the receiver, and `false` otherwise.

Parameters:
  `pt` - the point to test for containment
Returns:
  `true` if the region contains the point and `false` otherwise
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

#### equals

    public boolean equals​(Object object)

Compares the argument to the receiver, and returns true if they represent the same object using a class specific comparison.

Overrides:
  `equals` in class `Object`
Parameters:
  `object` - the object to compare with this object
Returns:
  `true` if the object is the same as this object and `false` otherwise
See Also:
  `hashCode()`

#### getBounds

    public Rectangle getBounds()

Returns a rectangle which represents the rectangular union of the collection of polygons the receiver maintains to describe its area.

Returns:
  a bounding rectangle for the region
Throws:
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
See Also:
  `Rectangle.union(org.eclipse.swt.graphics.Rectangle)`

#### hashCode

    public int hashCode()

Returns an integer hash code for the receiver. Any two objects that return `true` when passed to `equals` must return the same value for this method.

Overrides:
  `hashCode` in class `Object`
Returns:
  the receiver's hash
See Also:
  `equals(java.lang.Object)`

#### intersect

    public void intersect​(Rectangle rect)

Intersects the given rectangle to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `rect` - the rectangle to intersect with the receiver
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  - ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.0

#### intersect

    public void intersect​(int x,
                          int y,
                          int width,
                          int height)

Intersects the given rectangle to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `x` - the x coordinate of the rectangle
  `y` - the y coordinate of the rectangle
  `width` - the width coordinate of the rectangle
  `height` - the height coordinate of the rectangle
Throws:
  `IllegalArgumentException` -
  - ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.1

#### intersect

    public void intersect​(Region region)

Intersects all of the polygons which make up the area covered by the argument to the collection of polygons the receiver maintains to describe its area.

Parameters:
  `region` - the region to intersect
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  - ERROR_INVALID_ARGUMENT - if the argument has been disposed
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.0

#### intersects

    public boolean intersects​(int x,
                              int y,
                              int width,
                              int height)

Returns `true` if the rectangle described by the arguments intersects with any of the polygons the receiver maintains to describe its area, and `false` otherwise.

Parameters:
  `x` - the x coordinate of the origin of the rectangle
  `y` - the y coordinate of the origin of the rectangle
  `width` - the width of the rectangle
  `height` - the height of the rectangle
Returns:
  `true` if the rectangle intersects with the receiver, and `false` otherwise
Throws:
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
See Also:
  `Rectangle.intersects(Rectangle)`

#### intersects

    public boolean intersects​(Rectangle rect)

Returns `true` if the given rectangle intersects with any of the polygons the receiver maintains to describe its area and `false` otherwise.

Parameters:
  `rect` - the rectangle to test for intersection
Returns:
  `true` if the rectangle intersects with the receiver, and `false` otherwise
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
See Also:
  `Rectangle.intersects(Rectangle)`

#### isDisposed

    public boolean isDisposed()

Returns `true` if the region has been disposed, and `false` otherwise.

This method gets the dispose state for the region. When a region has been disposed, it is an error to invoke any other method (except `Resource.dispose()`) using the region.

Specified by:
  `isDisposed` in class `Resource`
Returns:
  `true` when the region is disposed, and `false` otherwise

#### isEmpty

    public boolean isEmpty()

Returns `true` if the receiver does not cover any area in the (x, y) coordinate plane, and `false` if the receiver does cover some area in the plane.

Returns:
  `true` if the receiver is empty, and `false` otherwise
Throws:
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed

#### subtract

    public void subtract​(int[] pointArray)

Subtracts the given polygon from the collection of polygons the receiver maintains to describe its area.

Parameters:
  `pointArray` - points that describe the polygon to merge with the receiver
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.0

#### subtract

    public void subtract​(Rectangle rect)

Subtracts the given rectangle from the collection of polygons the receiver maintains to describe its area.

Parameters:
  `rect` - the rectangle to subtract from the receiver
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  - ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.0

#### subtract

    public void subtract​(int x,
                         int y,
                         int width,
                         int height)

Subtracts the given rectangle from the collection of polygons the receiver maintains to describe its area.

Parameters:
  `x` - the x coordinate of the rectangle
  `y` - the y coordinate of the rectangle
  `width` - the width coordinate of the rectangle
  `height` - the height coordinate of the rectangle
Throws:
  `IllegalArgumentException` -
  - ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.1

#### subtract

    public void subtract​(Region region)

Subtracts all of the polygons which make up the area covered by the argument from the collection of polygons the receiver maintains to describe its area.

Parameters:
  `region` - the region to subtract
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  - ERROR_INVALID_ARGUMENT - if the argument has been disposed
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.0

#### translate

    public void translate​(int x,
                          int y)

Translate all of the polygons the receiver maintains to describe its area by the specified point.

Parameters:
  `x` - the x coordinate of the point to translate
  `y` - the y coordinate of the point to translate
Throws:
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.1

#### translate

    public void translate​(Point pt)

Translate all of the polygons the receiver maintains to describe its area by the specified point.

Parameters:
  `pt` - the point to translate
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the argument is null
  `SWTException` -
  - ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed
Since:
  3.1

#### toString

    public String toString()

Returns a string containing a concise, human-readable description of the receiver.

Overrides:
  `toString` in class `Object`
Returns:
  a string representation of the receiver

#### win32_new

    public static Region win32_new​(Device device,
                                   int handle)

Invokes platform specific functionality to allocate a new region.

IMPORTANT: This method is not part of the public API for `Region`. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

Parameters:
  `device` - the device on which to allocate the region
  `handle` - the handle for the region
Returns:
  a new region object containing the specified device and handle
Restriction:
  This method is not intended to be referenced by clients.