001: /*
002: * @(#)Region.java 1.16 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package sun.porting.graphicssystem;
029:
030: import java.util.Enumeration;
031: import java.awt.*;
032:
033: /**
034: * This is the interface for an object which represents rectilinear regions
035: * (e.g. window visibility and clip regions).
036: *
037: * @version 1.11, 08/19/02
038: */
039: public interface Region extends java.awt.Shape {
040: /**
041: * Create an independent copy of the region.
042: */
043: Region copy();
044:
045: /**
046: * Test for equality against the given region.
047: * @param r The region against which to test.
048: * @return true if this region is equal to r, false otherwise.
049: */
050: boolean equals(Region r);
051:
052: /**
053: * Does the region represent a simple rectangle?
054: * @return true if this region contains only one rectangle, false otherwise.
055: */
056: boolean isRectangle();
057:
058: /**
059: * Is the region empty?
060: * @return true if this region contains no area, false otherwise.
061: */
062: boolean isEmpty();
063:
064: /**
065: * Set the region to an empty region.
066: */
067: void setEmpty();
068:
069: /**
070: * Translate the entire region by the vector (dx, dy).
071: * @param dx The x component of the translation.
072: * @param dy The y component of the translation.
073: */
074: void translate(int dx, int dy);
075:
076: /**
077: * Return an <code>Enumeration</code> object which can be used to loop
078: * through the elements of this region. WARNING: the enumeration
079: * is not responsible for making sure that the region is not changed
080: * in the meantime. If there is any risk of this, you should do
081: * <code>region.copy().getRectangles()</code>
082: * @return An <code>Enumeration</code> object associated with this region.
083: */
084: Enumeration getRectangles();
085:
086: /**
087: * Defragment a region. This call is a convenience for the <code>Region</code>
088: * implementation; it indicates that a number of successive operations
089: * have been done and now the region can be expected to stay static for
090: * a period of time.
091: * @param isClip Indicates that the region is going to be used directly
092: * as a clip region.
093: */
094: void defragment(boolean isClip);
095:
096: /**
097: * Get the bounding box of the region, <i>i.e.</i> the smallest rectangle
098: * which completely encloses the region's current contents. If the
099: * region is empty, returns the rectangle (0,0,0,0).
100: * @return A <code>Rectangle</code> describing the bounding box.
101: */
102: Rectangle getBounds();
103:
104: /**
105: * Do a destructive union operation with the given region.
106: * @param r The other <code>Region</code> with which this <code>Region</code>
107: * should be combined.
108: */
109: void union(Region r);
110:
111: /**
112: * Do a destructive union operation with the rectangle (x,y,w,h).
113: * @param x The x coordinate of the rectangle used for the union.
114: * @param y The y coordinate of the rectangle used for the union.
115: * @param w The width of the rectangle used for the union.
116: * @param h The height of the rectangle used for the union.
117: */
118: void union(int x, int y, int w, int h);
119:
120: /**
121: * Do a destructive union operation with the given <code>Rectangle</code>.
122: * @param r The rectangle which should be added to this region.
123: */
124: void union(Rectangle r);
125:
126: /**
127: * Do a destructive subtract operation with the given region.
128: * @param r The region which should be subtracted out.
129: */
130: void subtract(Region r);
131:
132: /**
133: * Do a destructive subtraction, removing the rectangle (x,y,w,h)
134: * from the current region.
135: * @param x The x coordinate of the rectangle to be subtracted.
136: * @param y The y coordinate of the rectangle to be subtracted.
137: * @param w The width of the rectangle to be subtracted.
138: * @param h The height of the rectangle to be subtracted.
139: */
140: void subtract(int x, int y, int w, int h);
141:
142: /**
143: * Do a destructive subtraction, removing the given <code>Rectangle</code>.
144: * @param r The rectangle to be subtracted out.
145: */
146: void subtract(Rectangle r);
147:
148: /**
149: * Do a destructive intersection operation with the given region.
150: * @param r The region with which this region should be intersected.
151: */
152: void intersect(Region r);
153:
154: /**
155: * Do a destructive intersection operation with a region described by
156: * the rectangle (x,y,w,h).
157: * @param x The x coordinate of the rectangle used for the intersection.
158: * @param y The y coordinate of the rectangle used for the intersection.
159: * @param w The width of the rectangle used for the intersection.
160: * @param h The height of the rectangle used for the intersection.
161: */
162: void intersect(int x, int y, int w, int h);
163:
164: /**
165: * Do a destructive intersection operation with a region described by
166: * the given <code>Rectangle</code>.
167: * @param r The rectangle with which this region should be intersected.
168: */
169: void intersect(Rectangle r);
170:
171: /**
172: * Does the region contain the given point?
173: * @param x The x coordinate of the test point
174: * @param y The y coordinate of the test point
175: * @return true if (x,y) is in the region, false otherwise.
176: */
177: boolean contains(int x, int y);
178:
179: /**
180: * Does the region contain the given rectangle (in its entirety)?
181: * @param x The x coordinate of the test rectangle
182: * @param y The y coordinate of the test rectangle
183: * @param w The width of the test rectangle
184: * @param h The height of the test rectangle
185: * @return true if (x,y,w,h) is entirely in the region, false otherwise.
186: */
187: boolean contains(int x, int y, int w, int h);
188:
189: /**
190: * A quick, bounding box overlap test to see whether this region occupies
191: * the same general space as the given region r.
192: * An overlap is possible only if the bounding box of this region
193: * overlaps the bounding box of r. The bounding box test quickly eliminates
194: * regions from consideration if they can't possibly intersect.
195: * @param r The region which is to be tested for overlap.
196: * @return true if an overlap is possible, false otherwise.
197: */
198: boolean mayIntersect(Region r);
199:
200: /**
201: * A quick, bounding box overlap test to see whether this region occupies
202: * the same general space as a rectangle described by the given (x,y,w,h) tuple.
203: * An overlap is possible only if the bounding box of this region
204: * overlaps the area of the rectangle. The bounding box test quickly eliminates
205: * regions from consideration if they can't possibly intersect.
206: * @param x The x coordinate of the test rectangle
207: * @param y The y coordinate of the test rectangle
208: * @param w The width of the test rectangle
209: * @param h The height of the test rectangle
210: * @return true if an overlap is possible, false otherwise.
211: */
212: boolean mayIntersect(int x, int y, int w, int h);
213:
214: /**
215: * A quick, bounding box overlap test to see whether this region occupies
216: * the same general space as the given rectangle r.
217: * An overlap is possible only if the bounding box of this region
218: * overlaps the area of the rectangle. The bounding box test quickly eliminates
219: * regions from consideration if they can't possibly intersect.
220: * @param r The rectangle which is to be tested for overlap.
221: * @return true If an overlap is possible, false otherwise.
222: */
223: boolean mayIntersect(Rectangle r);
224: }
|