001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.swt.graphics;
011:
012: import org.eclipse.swt.*;
013:
014: /**
015: * Instances of this class represent patterns to use while drawing. Patterns
016: * can be specified either as bitmaps or gradients.
017: * <p>
018: * Application code must explicitly invoke the <code>Pattern.dispose()</code>
019: * method to release the operating system resources managed by each instance
020: * when those instances are no longer required.
021: * </p>
022: * <p>
023: * This class requires the operating system's advanced graphics subsystem
024: * which may not be available on some platforms.
025: * </p>
026: *
027: * @since 3.1
028: */
029: public class Pattern extends Resource {
030:
031: /**
032: * the OS resource for the Pattern
033: * (Warning: This field is platform dependent)
034: * <p>
035: * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
036: * public API. It is marked public only so that it can be shared
037: * within the packages provided by SWT. It is not available on all
038: * platforms and should never be accessed from application code.
039: * </p>
040: */
041: public int handle;
042:
043: /**
044: * Constructs a new Pattern given an image. Drawing with the resulting
045: * pattern will cause the image to be tiled over the resulting area.
046: * <p>
047: * This operation requires the operating system's advanced
048: * graphics subsystem which may not be available on some
049: * platforms.
050: * </p>
051: *
052: * @param device the device on which to allocate the pattern
053: * @param image the image that the pattern will draw
054: *
055: * @exception IllegalArgumentException <ul>
056: * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
057: * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
058: * </ul>
059: * @exception SWTException <ul>
060: * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li>
061: * </ul>
062: * @exception SWTError <ul>
063: * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained</li>
064: * </ul>
065: *
066: * @see #dispose()
067: */
068: public Pattern(Device device, Image image) {
069: if (device == null)
070: device = Device.getDevice();
071: if (device == null)
072: SWT.error(SWT.ERROR_NULL_ARGUMENT);
073: if (image == null)
074: SWT.error(SWT.ERROR_NULL_ARGUMENT);
075: if (image.isDisposed())
076: SWT.error(SWT.ERROR_INVALID_ARGUMENT);
077: this .device = device;
078: if (handle == 0)
079: SWT.error(SWT.ERROR_NO_HANDLES);
080: if (device.tracking)
081: device.new_Object(this );
082: }
083:
084: /**
085: * Constructs a new Pattern that represents a linear, two color
086: * gradient. Drawing with the pattern will cause the resulting area to be
087: * tiled with the gradient specified by the arguments.
088: * <p>
089: * This operation requires the operating system's advanced
090: * graphics subsystem which may not be available on some
091: * platforms.
092: * </p>
093: *
094: * @param device the device on which to allocate the pattern
095: * @param x1 the x coordinate of the starting corner of the gradient
096: * @param y1 the y coordinate of the starting corner of the gradient
097: * @param x2 the x coordinate of the ending corner of the gradient
098: * @param y2 the y coordinate of the ending corner of the gradient
099: * @param color1 the starting color of the gradient
100: * @param color2 the ending color of the gradient
101: *
102: * @exception IllegalArgumentException <ul>
103: * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device,
104: * or if either color1 or color2 is null</li>
105: * <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
106: * </ul>
107: * @exception SWTException <ul>
108: * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li>
109: * </ul>
110: * @exception SWTError <ul>
111: * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained</li>
112: * </ul>
113: *
114: * @see #dispose()
115: */
116: public Pattern(Device device, float x1, float y1, float x2,
117: float y2, Color color1, Color color2) {
118: this (device, x1, y1, x2, y2, color1, 0xFF, color2, 0xFF);
119: }
120:
121: /**
122: * Constructs a new Pattern that represents a linear, two color
123: * gradient. Drawing with the pattern will cause the resulting area to be
124: * tiled with the gradient specified by the arguments.
125: * <p>
126: * This operation requires the operating system's advanced
127: * graphics subsystem which may not be available on some
128: * platforms.
129: * </p>
130: *
131: * @param device the device on which to allocate the pattern
132: * @param x1 the x coordinate of the starting corner of the gradient
133: * @param y1 the y coordinate of the starting corner of the gradient
134: * @param x2 the x coordinate of the ending corner of the gradient
135: * @param y2 the y coordinate of the ending corner of the gradient
136: * @param color1 the starting color of the gradient
137: * @param alpha1 the starting alpha value of the gradient
138: * @param color2 the ending color of the gradient
139: * @param alpha2 the ending alpha value of the gradient
140: *
141: * @exception IllegalArgumentException <ul>
142: * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device,
143: * or if either color1 or color2 is null</li>
144: * <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
145: * </ul>
146: * @exception SWTException <ul>
147: * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li>
148: * </ul>
149: * @exception SWTError <ul>
150: * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained</li>
151: * </ul>
152: *
153: * @see #dispose()
154: *
155: * @since 3.2
156: */
157: public Pattern(Device device, float x1, float y1, float x2,
158: float y2, Color color1, int alpha1, Color color2, int alpha2) {
159: if (device == null)
160: device = Device.getDevice();
161: if (device == null)
162: SWT.error(SWT.ERROR_NULL_ARGUMENT);
163: if (color1 == null)
164: SWT.error(SWT.ERROR_NULL_ARGUMENT);
165: if (color1.isDisposed())
166: SWT.error(SWT.ERROR_INVALID_ARGUMENT);
167: if (color2 == null)
168: SWT.error(SWT.ERROR_NULL_ARGUMENT);
169: if (color2.isDisposed())
170: SWT.error(SWT.ERROR_INVALID_ARGUMENT);
171: this .device = device;
172: if (handle == 0)
173: SWT.error(SWT.ERROR_NO_HANDLES);
174: if (device.tracking)
175: device.new_Object(this );
176: }
177:
178: /**
179: * Disposes of the operating system resources associated with
180: * the Pattern. Applications must dispose of all Patterns that
181: * they allocate.
182: */
183: public void dispose() {
184: if (handle == 0)
185: return;
186: if (device.isDisposed())
187: return;
188: handle = 0;
189: if (device.tracking)
190: device.dispose_Object(this );
191: device = null;
192: }
193:
194: /**
195: * Returns <code>true</code> if the Pattern has been disposed,
196: * and <code>false</code> otherwise.
197: * <p>
198: * This method gets the dispose state for the Pattern.
199: * When a Pattern has been disposed, it is an error to
200: * invoke any other method using the Pattern.
201: *
202: * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
203: */
204: public boolean isDisposed() {
205: return handle == 0;
206: }
207:
208: /**
209: * Returns a string containing a concise, human-readable
210: * description of the receiver.
211: *
212: * @return a string representation of the receiver
213: */
214: public String toString() {
215: if (isDisposed())
216: return "Pattern {*DISPOSED*}";
217: return "Pattern {" + handle + "}";
218: }
219:
220: }
|