Region


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.swt.graphics;
12  
13  
14  import org.eclipse.swt.internal.carbon.*;
15  import org.eclipse.swt.*;
16  
17  /**
18   * Instances of this class represent areas of an x-y coordinate
19   * system that are aggregates of the areas covered by a number
20   * of polygons.
21   * <p>
22   * Application code must explicitly invoke the <code>Region.dispose()</code> 
23   * method to release the operating system resources managed by each instance
24   * when those instances are no longer required.
25   * </p>
26   */
27  public final class Region extends Resource {
28      /**
29       * the OS resource for the region
30       * (Warning: This field is platform dependent)
31       * <p>
32       * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
33       * public API. It is marked public only so that it can be shared
34       * within the packages provided by SWT. It is not available on all
35       * platforms and should never be accessed from application code.
36       * </p>
37       */
38      public int handle;
39  
40  /**
41   * Constructs a new empty region.
42   * 
43   * @exception SWTError <ul>
44   *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
45   * </ul>
46   */
47  public Region() {
48      this(null);
49  }
50  
51  /**
52   * Constructs a new empty region.
53   * <p>
54   * You must dispose the region when it is no longer required. 
55   * </p>
56   *
57   * @param device the device on which to allocate the region
58   *
59   * @exception IllegalArgumentException <ul>
60   *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
61   * </ul>
62   * @exception SWTError <ul>
63   *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
64   * </ul>
65   *
66   * @see #dispose
67   * 
68   * @since 3.0
69   */
70  public Region(Device device) {
71      if (device == null) device = Device.getDevice();
72      if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
73      this.device = device;
74      handle = OS.NewRgn();
75      if (handle == 0) SWT.error(SWT.ERROR_NO_HANDLES);
76  }
77  
78  Region(Device device, int handle) {
79      this.device = device;
80      this.handle = handle;
81  }
82  
83  /**
84   * Adds the given polygon to the collection of polygons
85   * the receiver maintains to describe its area.
86   *
87   * @param pointArray points that describe the polygon to merge with the receiver
88   *
89   * @exception IllegalArgumentException <ul>
90   *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
91   * </ul>
92   * @exception SWTException <ul>
93   *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
94   * </ul>
95   *
96   * @since 3.0
97  *
98   */
99  public void add (int[] pointArray) {
100     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
101     if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
102     if (pointArray.length < 2) return;
103     int polyRgn = OS.NewRgn();
104     OS.OpenRgn();
105     OS.MoveTo((short)pointArray[0], (short)pointArray[1]);
106     for (int i = 1; i < pointArray.length / 2; i++) {
107         OS.LineTo((short)pointArray[2 * i], (short)pointArray[2 * i + 1]);
108     }
109     OS.LineTo((short)pointArray[0], (short)pointArray[1]);
110     OS.CloseRgn(polyRgn);
111     OS.UnionRgn(handle, polyRgn, handle);
112     OS.DisposeRgn(polyRgn);
113 }
114 
115 /**
116  * Adds the given rectangle to the collection of polygons
117  * the receiver maintains to describe its area.
118  *
119  * @param rect the rectangle to merge with the receiver
120  *
121  * @exception IllegalArgumentException <ul>
122  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
123  *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
124  * </ul>
125  * @exception SWTException <ul>
126  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
127  * </ul>
128  */
129 public void add(Rectangle rect) {
130     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
131     if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
132     if (rect.width < 0 || rect.height < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
133     add (rect.x, rect.y, rect.width, rect.height);
134 }
135 
136 /**
137  * Adds the given rectangle to the collection of polygons
138  * the receiver maintains to describe its area.
139  *
140  * @param x the x coordinate of the rectangle
141  * @param y the y coordinate of the rectangle
142  * @param width the width coordinate of the rectangle
143  * @param height the height coordinate of the rectangle
144  *
145  * @exception IllegalArgumentException <ul>
146  *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
147  * </ul>
148  * @exception SWTException <ul>
149  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
150  * </ul>
151  * 
152  * @since 3.1
153  */
154 public void add(int x, int y, int width, int height) {
155     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
156     if (width < 0 || height < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
157     int rectRgn = OS.NewRgn();
158     Rect r = new Rect();
159     OS.SetRect(r, (short)x, (short)y, (short)(x + width),(short)(y + height));
160     OS.RectRgn(rectRgn, r);
161     OS.UnionRgn(handle, rectRgn, handle);
162     OS.DisposeRgn(rectRgn);
163 }
164 
165 /**
166  * Adds all of the polygons which make up the area covered
167  * by the argument to the collection of polygons the receiver
168  * maintains to describe its area.
169  *
170  * @param region the region to merge
171  *
172  * @exception IllegalArgumentException <ul>
173  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
174  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
175  * </ul>
176  * @exception SWTException <ul>
177  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
178  * </ul>
179  */
180 public void add(Region region) {
181     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
182     if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
183     if (region.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
184     OS.UnionRgn(handle, region.handle, handle);
185 }
186 
187 /**
188  * Returns <code>true</code> if the point specified by the
189  * arguments is inside the area specified by the receiver,
190  * and <code>false</code> otherwise.
191  *
192  * @param x the x coordinate of the point to test for containment
193  * @param y the y coordinate of the point to test for containment
194  * @return <code>true</code> if the region contains the point and <code>false</code> otherwise
195  *
196  * @exception SWTException <ul>
197  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
198  * </ul>
199  */
200 public boolean contains(int x, int y) {
201     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
202     org.eclipse.swt.internal.carbon.Point point = new org.eclipse.swt.internal.carbon.Point();
203     OS.SetPt(point, (short)x, (short)y);
204     return OS.PtInRgn(point, handle);
205 }
206 
207 /**
208  * Returns <code>true</code> if the given point is inside the
209  * area specified by the receiver, and <code>false</code>
210  * otherwise.
211  *
212  * @param pt the point to test for containment
213  * @return <code>true</code> if the region contains the point and <code>false</code> otherwise
214  *
215  * @exception IllegalArgumentException <ul>
216  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
217  * </ul>
218  * @exception SWTException <ul>
219  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
220  * </ul>
221  */
222 public boolean contains(Point pt) {
223     if (pt == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
224     return contains(pt.x, pt.y);
225 }
226 /**
227  * Disposes of the operating system resources associated with
228  * the region. Applications must dispose of all regions which
229  * they allocate.
230  */
231 public void dispose() {
232     if (handle == 0) return;
233     OS.DisposeRgn(handle);
234     handle = 0;
235     device = null;
236 }
237 
238 /**
239  * Compares the argument to the receiver, and returns true
240  * if they represent the <em>same</em> object using a class
241  * specific comparison.
242  *
243  * @param object the object to compare with this object
244  * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
245  *
246  * @see #hashCode
247  */
248 public boolean equals(Object   object) {
249     if (this == object) return true;
250     if (!(object instanceof Region)) return false;
251     Region region = (Region)object;
252     return handle == region.handle;
253 }
254 
255 /**
256  * Returns a rectangle which represents the rectangular
257  * union of the collection of polygons the receiver
258  * maintains to describe its area.
259  *
260  * @return a bounding rectangle for the region
261  *
262  * @exception SWTException <ul>
263  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
264  * </ul>
265  *
266  * @see Rectangle#union
267  */
268 public Rectangle getBounds() {
269     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
270     Rect bounds = new Rect();
271     OS.GetRegionBounds(handle, bounds);
272     int width = bounds.right - bounds.left;
273     int height = bounds.bottom - bounds.top;
274     return new Rectangle(bounds.left, bounds.top, width, height);
275 }
276 
277 public static Region carbon_new(Device device, int handle) {
278     return new Region(device, handle);
279 }
280 
281 /**
282  * Returns an integer hash code for the receiver. Any two 
283  * objects that return <code>true</code> when passed to 
284  * <code>equals</code> must return the same value for this
285  * method.
286  *
287  * @return the receiver's hash
288  *
289  * @see #equals
290  */
291 public int hashCode() {
292     return handle;
293 }
294 
295 /**
296  * Intersects the given rectangle to the collection of polygons
297  * the receiver maintains to describe its area.
298  *
299  * @param rect the rectangle to intersect with the receiver
300  *
301  * @exception IllegalArgumentException <ul>
302  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
303  *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
304  * </ul>
305  * @exception SWTException <ul>
306  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
307  * </ul>
308  * 
309  * @since 3.0
310  */
311 public void intersect(Rectangle rect) {
312     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
313     if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
314     intersect (rect.x, rect.y, rect.width, rect.height);
315 }
316 
317 /**
318  * Intersects the given rectangle to the collection of polygons
319  * the receiver maintains to describe its area.
320  *
321  * @param x the x coordinate of the rectangle
322  * @param y the y coordinate of the rectangle
323  * @param width the width coordinate of the rectangle
324  * @param height the height coordinate of the rectangle
325  *
326  * @exception IllegalArgumentException <ul>
327  *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
328  * </ul>
329  * @exception SWTException <ul>
330  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
331  * </ul>
332  * 
333  * @since 3.1
334  */
335 public void intersect(int x, int y, int width, int height) {
336     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
337     if (width < 0 || height < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
338     int rectRgn = OS.NewRgn();
339     Rect r = new Rect();
340     OS.SetRect(r, (short)x, (short)y, (short)(x + width),(short)(y + height));
341     OS.RectRgn(rectRgn, r);
342     OS.SectRgn(handle, rectRgn, handle);
343     OS.DisposeRgn(rectRgn);
344 }
345 
346 /**
347  * Intersects all of the polygons which make up the area covered
348  * by the argument to the collection of polygons the receiver
349  * maintains to describe its area.
350  *
351  * @param region the region to intersect
352  *
353  * @exception IllegalArgumentException <ul>
354  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
355  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
356  * </ul>
357  * @exception SWTException <ul>
358  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
359  * </ul>
360  * 
361  * @since 3.0
362  */
363 public void intersect(Region region) {
364     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
365     if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
366     if (region.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
367     OS.SectRgn(handle, region.handle, handle);
368 }
369 
370 /**
371  * Returns <code>true</code> if the rectangle described by the
372  * arguments intersects with any of the polygons the receiver
373  * maintains to describe its area, and <code>false</code> otherwise.
374  *
375  * @param x the x coordinate of the origin of the rectangle
376  * @param y the y coordinate of the origin of the rectangle
377  * @param width the width of the rectangle
378  * @param height the height of the rectangle
379  * @return <code>true</code> if the rectangle intersects with the receiver, and <code>false</code> otherwise
380  *
381  * @exception SWTException <ul>
382  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
383  * </ul>
384  *
385  * @see Rectangle#intersects(Rectangle)
386  */
387 public boolean intersects (int x, int y, int width, int height) {
388     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
389     Rect rect = new Rect();
390     OS.SetRect(rect, (short)x, (short)y, (short)(x + width),(short)(y + height));
391     return OS.RectInRgn(rect, handle);
392 }
393 
394 /**
395  * Returns <code>true</code> if the given rectangle intersects
396  * with any of the polygons the receiver maintains to describe
397  * its area and <code>false</code> otherwise.
398  *
399  * @param rect the rectangle to test for intersection
400  * @return <code>true</code> if the rectangle intersects with the receiver, and <code>false</code> otherwise
401  *
402  * @exception IllegalArgumentException <ul>
403  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
404  * </ul>
405  * @exception SWTException <ul>
406  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
407  * </ul>
408  *
409  * @see Rectangle#intersects(Rectangle)
410  */
411 public boolean intersects(Rectangle rect) {
412     if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
413     return intersects(rect.x, rect.y, rect.width, rect.height);
414 }
415 
416 /**
417  * Returns <code>true</code> if the region has been disposed,
418  * and <code>false</code> otherwise.
419  * <p>
420  * This method gets the dispose state for the region.
421  * When a region has been disposed, it is an error to
422  * invoke any other method using the region.
423  *
424  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
425  */
426 public boolean isDisposed() {
427     return handle == 0;
428 }
429 
430 /**
431  * Returns <code>true</code> if the receiver does not cover any
432  * area in the (x, y) coordinate plane, and <code>false</code> if
433  * the receiver does cover some area in the plane.
434  *
435  * @return <code>true</code> if the receiver is empty, and <code>false</code> otherwise
436  *
437  * @exception SWTException <ul>
438  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
439  * </ul>
440  */
441 public boolean isEmpty() {
442     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
443     return OS.EmptyRgn(handle);
444 }
445 
446 /**
447  * Subtracts the given polygon from the collection of polygons
448  * the receiver maintains to describe its area.
449  *
450  * @param pointArray points that describe the polygon to merge with the receiver
451  *
452  * @exception IllegalArgumentException <ul>
453  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
454  * </ul>
455  * @exception SWTException <ul>
456  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
457  * </ul>
458  * 
459  * @since 3.0
460  */
461 public void subtract (int[] pointArray) {
462     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
463     if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
464     if (pointArray.length < 2) return;
465     int polyRgn = OS.NewRgn();
466     OS.OpenRgn();
467     OS.MoveTo((short)pointArray[0], (short)pointArray[1]);
468     for (int i = 1; i < pointArray.length / 2; i++) {
469         OS.LineTo((short)pointArray[2 * i], (short)pointArray[2 * i + 1]);
470     }
471     OS.LineTo((short)pointArray[0], (short)pointArray[1]);
472     OS.CloseRgn(polyRgn);
473     OS.DiffRgn(handle, polyRgn, handle);
474     OS.DisposeRgn(polyRgn);
475 }
476 
477 /**
478  * Subtracts the given rectangle from the collection of polygons
479  * the receiver maintains to describe its area.
480  *
481  * @param rect the rectangle to subtract from the receiver
482  *
483  * @exception IllegalArgumentException <ul>
484  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
485  *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
486  * </ul>
487  * @exception SWTException <ul>
488  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
489  * </ul>
490  * 
491  * @since 3.0
492  */
493 public void subtract(Rectangle rect) {
494     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
495     if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
496     subtract (rect.x, rect.y, rect.width, rect.height);
497 }
498 
499 /**
500  * Subtracts the given rectangle from the collection of polygons
501  * the receiver maintains to describe its area.
502  *
503  * @param x the x coordinate of the rectangle
504  * @param y the y coordinate of the rectangle
505  * @param width the width coordinate of the rectangle
506  * @param height the height coordinate of the rectangle
507  *
508  * @exception IllegalArgumentException <ul>
509  *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
510  * </ul>
511  * @exception SWTException <ul>
512  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
513  * </ul>
514  * 
515  * @since 3.1
516  */
517 public void subtract(int x, int y, int width, int height) {
518     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
519     if (width < 0 || height < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
520     int rectRgn = OS.NewRgn();
521     Rect r = new Rect();
522     OS.SetRect(r, (short)x, (short)y, (short)(x + width),(short)(y + height));
523     OS.RectRgn(rectRgn, r);
524     OS.DiffRgn(handle, rectRgn, handle);
525     OS.DisposeRgn(rectRgn);
526 }
527 
528 /**
529  * Subtracts all of the polygons which make up the area covered
530  * by the argument from the collection of polygons the receiver
531  * maintains to describe its area.
532  *
533  * @param region the region to subtract
534  *
535  * @exception IllegalArgumentException <ul>
536  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
537  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
538  * </ul>
539  * @exception SWTException <ul>
540  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
541  * </ul>
542  * 
543  * @since 3.0
544  */
545 public void subtract(Region region) {
546     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
547     if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
548     if (region.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
549     OS.DiffRgn(handle, region.handle, handle);
550 }
551 
552 /**
553  * Translate all of the polygons the receiver maintains to describe
554  * its area by the specified point.
555  *
556  * @param x the x coordinate of the point to translate
557  * @param y the y coordinate of the point to translate
558  *
559  * @exception SWTException <ul>
560  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
561  * </ul>
562  * 
563  * @since 3.1
564  */
565 public void translate (int x, int y) {
566     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
567     OS.OffsetRgn (handle, (short)x, (short)y);
568 }
569 
570 /**
571  * Translate all of the polygons the receiver maintains to describe
572  * its area by the specified point.
573  *
574  * @param pt the point to translate
575  *
576  * @exception IllegalArgumentException <ul>
577  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
578  * </ul>
579  * @exception SWTException <ul>
580  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
581  * </ul>
582  * 
583  * @since 3.1
584  */
585 public void translate (Point pt) {
586     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
587     if (pt == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
588     translate (pt.x, pt.y);
589 }
590 
591 /**
592  * Returns a string containing a concise, human-readable
593  * description of the receiver.
594  *
595  * @return a string representation of the receiver
596  */
597 public String   toString () {
598     if (isDisposed()) return "Region {*DISPOSED*}";
599     return "Region {" + handle + "}";
600 }
601 }
602
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags