Class Region

public class Region implements Cloneable
{
  // Fields
  final public static int AND;
  final public static int COMPLEX;
  final public static int DIFF;
  final public static int EMPTY;
  final public static int OR;
  final public static int SIMPLE;
  final public static int XOR;

  // Constructors
  public Region();
  public Region(int x, int y, int width, int height);
  public Region(Rectangle rect);
  public Region(Region other);
  public Region(Region srcA, Region srcB, int operation)
        throws IllegalArgumentException;
  public Region(Rectangle rectA, Rectangle rectsB[], int operation)
        throws IllegalArgumentException;
  public Region(Rectangle rectA, Rectangle rectsB[], int count, int
        operation) throws IllegalArgumentException;

  // Methods
  public final Object clone();
  public final Region combine(Region other, int operation)
        throws IllegalArgumentException;
  public final Region combine(Rectangle rect, int operation) throws
        IllegalArgumentException;
  public final int complexity();
  public final boolean contains(int x, int y);
  public final boolean contains(Point pt);
  public final Region copy(Region other)
        throws IllegalArgumentException;
  public final Region empty();
  public final boolean equals(Region other);
  public final boolean equals(Object other);
  public final boolean fillBounds(Rectangle rect);
  public final Rectangle getBounds();
  public final int[][] getGeometry();
  public final int hashCode();
  public final boolean intersects(int x, int y, int width,
        int height);
  public final boolean intersects(Rectangle rect);
  public final Region invert() throws IllegalArgumentException;
  public final boolean isEmpty();
  public final Region offset(int deltaX, int deltaY);
  public final Region offset(Point delta);
  public final Region set(int x, int y, int width, int height);
  public final Region set(Rectangle rect);
  public final String toString();
}

This class is a data structure that represents arbitary shapes, and is used to support windowless controls in the Application Foundation Classes.

Constructors

Region

public Region();

Constructs an empty region.

Region

public Region(int x, int y, int width, int height);

Creates a rectangular region.

Parameter	Description
x	The region's upper-left x coordinate.
y	The region's upper-left y coordinate.
width	The width of the region (in pixels).
height	The height of the region (in pixels).

Region

public Region(Rectangle rect);

Creates a region from a Rectangle.

Parameter	Description
rect	The rectangle used to initialize the region.

Region

public Region(Region other);

Creates a region with geometry identical to the given Region parameter.

Parameter	Description
other	The Region to copy from.

Region

public Region(Region srcA, Region srcB, int operation)
        throws IllegalArgumentException;

Creates a region that is the combination of two other regions.

Parameter	Description
srcA	The first source region.
srcB	The second source region.
operation	The operation used to combine the source regions. These operations may be one of the following: AND Produces the intersection of the source operands. OR Produces the union of the source operands. XOR Produces the exclusive OR of the source operands. DIFF Subtracts one or more source operands from another.

Exceptions:

IllegalArgumentException

Region

public Region(Rectangle rectA, Rectangle rectsB[], int operation)
        throws IllegalArgumentException;

Creates a region from an arbitrary set of rectangles.

Parameter	Description
rectA	The first source rectangle.
rectsB	An array of additional source rectangles.
operation	The operation used to combine the rectangles. These operations may be one of the following: AND Produces the intersection of the source operands. OR Produces the union of the source operands. XOR Produces the exclusive OR of the source operands. DIFF Subtracts one or more source operands from another.

Exceptions:

IllegalArgumentException

Region

public Region(Rectangle rectA, Rectangle rectsB[], int count,
        int operation) throws IllegalArgumentException;

Creates a region from an arbitrary set of rectangles.

Parameter	Description
rectA	The first source rectangle.
rectsB	An array of additional source rectangles.
count	The number of rectangles.
operation	The operation used to combine the rectangles. These operations may be one of the following: AND Produces the intersection of the source operands. OR Produces the union of the source operands. XOR Produces the exclusive OR of the source operands. DIFF Subtracts one or more source operands from another.

Exceptions:

IllegalArgumentException

Methods

clone

public final Object clone();

Creates a clone of the region.

Return Value:

Returns a copy of the region.

combine

public final Region combine(Region other, int operation)
        throws IllegalArgumentException;

Combines the region with another region.

Return Value:

Returns the Region combined with the one specified by other.

Parameter	Description
other	The region to combine the current region with.
operation	The operation used to combine the regions. This operation may be one of the following: AND Produces the intersection of the source operands. OR Produces the union of the source operands. XOR Produces the exclusive OR of the source operands. DIFF Subtracts one or more source operands from another.

Exceptions:

IllegalArgumentException

combine

public final Region combine(Rectangle rect, int operation)
        throws IllegalArgumentException;

Combines the region with a specified rectangle.

Return Value:

Returns the Region combined with the rectangle specified by rect.

Parameter	Description
rect	The rectangle to combine the region with.
operation	The operation used to combine the shapes. This operation may be one of the following: AND Produces the intersection of the source operands. OR Produces the union of the source operands. XOR Produces the exclusive OR of the source operands. and DIFF Subtracts one or more source operands from another.

Exceptions:

IllegalArgumentException

complexity

public final int complexity();

Retrieves the complexity of the region.

Return Value:

Returns an integer describing the region's complexity.

Remarks:

A region's complexity is either EMPTY, SIMPLE or COMPLEX. An EMPTY region contains no space and has no bounds. A SIMPLE region describes a rectangular shape equal to its bounding box. A COMPLEX region describes a nonrectangular shape.

contains

public final boolean contains(int x, int y);

Determines whether the specified point lies within the region.

Return Value:

Returns true if the specified position is inside the region; otherwise, returns false.

Parameter	Description
x	The x coordinate of the point to test.
y	The y coordinate of the point to test.

contains

public final boolean contains(Point pt);

Determines whether the specified Point lies within the region.

Return Value:

Returns true if the specified point is inside the region; otherwise, returns false.

Parameter	Description
pt	The point to test.

copy

public final Region copy(Region other) throws IllegalArgumentException;

Copies the geometry of another region to the current region.

Return Value:

Returns the Region with a copy of other's geometry.

Parameter	Description
other	The region to copy from.

Exceptions:

IllegalArgumentException

empty

public final Region empty();

Empties a region.

Return Value:

Returns the Region emptied and set to null.

equals

public final boolean equals(Region other);

Tests a region for equality with another region.

Return Value:

Returns true if the geometry of the two regions are identical; otherwise, return false.

Parameter	Description
other	The region to compare the current region with.

equals

public final boolean equals(Object other);

Tests a region for equality with another object.

Return Value:

Returns true if the geometry's of the two regions are identical; otherwise, returns false.

Parameter	Description
other	The Object to compare with.

fillBounds

public final boolean fillBounds(Rectangle rect);

Fills the rectangle with the region's bounds.

Return Value:

Returns true if the region is not empty and the rectangle is filled; otherwise, returns false.

Parameter	Description
rect	The rectangle to be filled in.

Remarks:

The design of Rectangle prevents it from representing all possible rectangles in integer space.

getBounds

public final Rectangle getBounds();

Retrieves the bounding rectangle of the region.

Return Value:

Returns a Rectangle identifying the bounding box; returns null if the region is empty.

Remarks:

The design of Rectangle prevents it from representing all possible rectangles in integer space.

getGeometry

public final int[][] getGeometry();

Retrieves a description of the geometry of the region.

Return Value:

Returns a description of the region's geometry.

Remarks:

The description of the region's geometry is a two-dimensional array (an array of arrays of ints). Each sub-array represents a horizontal strip of the region's geometry. The first two values in a strip represent its upper and lower coordinates. The remaining values in the strip are pairs of coordinates that identify the left and right bounds of space inside the region.

hashCode

public final int hashCode();

Computes a hash code of the region's geometry.

Return Value:

Returns an integer hash code based on the current geometry of the region.

intersects

public final boolean intersects(int x, int y, int width, int height);

Determines whether the specified rectangle intersects a Region

Return Value:

Returns true if the rectangle intersects a Region.

Parameter	Description
x	The upper-left x coordinate of the given rectangle.
y	The upper-left y coordinate of the given rectangle.
width	The rectangle width (in pixels).
height	The rectangle height (in pixels).

intersects

public final boolean intersects(Rectangle rect);

Determines whether the specified rectangle intersects a Region.

Return Value:

Returns true if the rectangle intersects a Region; otherwise, returns false.

Parameter	Description
rect	The Rectangle to test.

invert

public final Region invert() throws IllegalArgumentException;

Inverts the region.

Return Value:

Returns the inverted region.

Exceptions:

IllegalArgumentException

isEmpty

public final boolean isEmpty();

Tests whether a region is empty.

Return Value:

Returns true if the region is empty; otherwise, returns false.

offset

public final Region offset(int deltaX, int deltaY);

Translates a region through space.

Return Value:

Returns the offset Region.

Parameter	Description
deltaX	The distance to translate in x.
deltaY	The distance to translate in y.

Remarks:

The Region is not actually offset within this method; rather, the offsets are stored for later computation. This is efficient for operations in which you need to temporarily offset a Region, and then reset it back at a later time. Using this technique with the offset method, you won't incur the overhead of translating an entire region twice.

offset

public final Region offset(Point delta);

Translates a region through space.

Return Value:

Returns the offset Region.

Parameter	Description
delta	The distance to translate in x and y.

Remarks:

The Region is not actually offset within this method; rather, the offsets are stored for later computation. This is efficient for operations in which you need to temporarily offset a Region, and then reset it back at a later time. Using this technique with the offset method, you won't incur the overhead of translating an entire region twice.

set

public final Region set(int x, int y, int width, int height);

Makes the region a simple rectangular region.

Return Value:

Returns a Region as a rectangle.

Parameter	Description
x	The region's upper-left x coordinate.
y	The region's upper-left y coordinate.
width	The width of the region (in pixels).
height	The height of the region (in pixels).

set

public final Region set(Rectangle rect);

Makes the region a simple rectangular region.

Return Value:

Returns a Region as a rectangle.

Parameter	Description
rect	The Rectangle that defines the region's new geometry.

toString

public final String toString();

Generates a string identifying the region.

Return Value:

Returns a String identifying the region.

Fields

AND

Produces the intersection of the source operands. This operation is used in the Region.combine method, as well as the Region class-combining constructors.

COMPLEX

Denotes a region with complex geometry. This is one of the values that may be returned from Region.complexity.

DIFF

Subtracts one or more source operands from another. This operation is used in the Region.combine method, as well as the Region class' combining constructors.

EMPTY

Denotes an empty region. This is one of the values that may be returned from Region.complexity.

OR

Produces the union of the source operands. This operation is used in the Region.combine method, as well as the Region class' combining constructors.

SIMPLE

Denotes a simple rectangular region. This is one of the values that may be returned from Region.complexity.

XOR

Produces the exclusive OR of the source operands. This operation is used in the Region.combine method, as well as the Region class' combining constructors.