Eclipse Platform
Release 3.7

org.eclipse.swt.graphics
Class Region

java.lang.Object
  extended by org.eclipse.swt.graphics.Resource
      extended by 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
 int handle
          the OS resource for the region (Warning: This field is platform dependent) IMPORTANT: This field is not part of the SWT public API.
 
Constructor Summary
Region()
          Constructs a new empty region.
Region(Device device)
          Constructs a new empty region.
 
Method Summary
 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 int 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.

Throws:
SWTError -
  • ERROR_NO_HANDLES if a handle could not be obtained for region creation

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.

Eclipse Platform
Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.