001: /*
002: * @(#)GraphicsSystem.java 1.31 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 sun.porting.windowsystem.EventHandler;
031: import java.awt.AWTError;
032: import java.awt.Cursor;
033: import java.awt.Dimension;
034: import java.awt.Image;
035: import java.awt.Point;
036: import java.security.AccessController;
037: import sun.security.action.GetPropertyAction;
038:
039: /**
040: * This is the top-level entry point for a graphics system implementation.
041: * It manages creation of resources (images, fonts, cursors), access to the
042: * screen, and drawing to offscreen memory regions.
043: *
044: * @version 1.26, 08/19/02
045: */
046: public abstract class GraphicsSystem {
047: private static GraphicsSystem graphicsSystem = null;
048:
049: /**
050: * Get a <code>GraphicsSystem</code> object corresponding to the default graphics system.
051: * The default graphics system is determined by the value of the system property
052: * <code>sun.graphicssystem</code>.
053: * @return A <code>GraphicsSystem</code> object for the default graphics system.
054: */
055: public static GraphicsSystem getDefaultGraphicsSystem() {
056: if (graphicsSystem == null) {
057: String nm = (String) AccessController
058: .doPrivileged(new GetPropertyAction(
059: "sun.graphicssystem",
060: "sun.awt.aw.GraphicsSystem"));
061: try {
062: graphicsSystem = (GraphicsSystem) Class.forName(nm)
063: .newInstance();
064: } catch (ClassNotFoundException e) {
065: throw new AWTError("GraphicsSystem not found: " + nm);
066: } catch (InstantiationException e) {
067: throw new AWTError(
068: "Could not instantiate GraphicsSystem: " + nm);
069: } catch (IllegalAccessException e) {
070: throw new AWTError("Could not access GraphicsSystem: "
071: + nm);
072: }
073: }
074: return graphicsSystem;
075: }
076:
077: /**
078: * Register a callback handler for receiving events.
079: * @param h The callback handler, an <code>EventHandler</code> object.
080: * @throws IllegalStateException if there is already a handler
081: * registered.
082: */
083: public abstract void registerEventHandler(EventHandler h)
084: throws IllegalStateException;
085:
086: /**
087: * Get an implementation of a typeface with the given name and
088: * style. Style values are as in <code>java.awt.Font</code>. If an exact match
089: * is not possible, returns the closest available match according to
090: * a system-dependent algorithm.
091: * @param name The name of the typeface
092: * @param style The style (e.g. <code>PLAIN</code>, <code>BOLD</code>, <code>ITALIC</code>) of the font.
093: * @return A <code>FontPeer</code> corresponding to the nearest matching font.
094: * @see java.awt.Font
095: */
096: public abstract sun.awt.peer.FontPeer getFont(String name, int style);
097:
098: /**
099: * Get a valid <code>FontMetrics</code> object for the given font.
100: * @param font The java font descriptor for the font
101: * @return The corresponding <code>FontMetrics</code> object.
102: * @see java.awt.Font
103: */
104: public abstract java.awt.FontMetrics getFontMetrics(
105: java.awt.Font font);
106:
107: /**
108: * Create an <code>Image</code> object with the given <code>ImageProducer</code>.
109: * The width, height and color model will all be determined later, when
110: * the image data is decoded.
111: * @param producer The <code>ImageProducer</code> object which will supply the image data
112: * @return An <code>Image</code>, initialized from the given <code>ImageProducer</code> object.
113: */
114: public abstract java.awt.Image getImage(
115: java.awt.image.ImageProducer producer);
116:
117: /**
118: * Get an <code>Image</code> object for use as an offscreen
119: * drawing area related to the given component.
120: * The desired width and height must be supplied.
121: * @param component The <code>Component</code> with which this image is associated
122: * @param w the width of the image
123: * @param h the height of the image
124: * @return An offscreen <code>Image</code> into which graphics can be drawn.
125: * @see java.awt.Image
126: * @see sun.awt.Image
127: * @see sun.awt.ImageRepresentation
128: */
129: public abstract Image makeDrawableImage(java.awt.Component c,
130: int w, int h);
131:
132: /**
133: * Get <code>Drawable</code> objects corresponding to the available screens.
134: * @return An array of <code>Drawable</code> objects.
135: */
136: public abstract Drawable[] getScreens();
137:
138: /**
139: * Get a <code>Drawable</code> object corresponding to the default screen.
140: * @return A <code>Drawable</code> object for the default screen.
141: */
142: public Drawable getScreen() {
143: Drawable scr[] = getScreens();
144: return (scr == null) ? null : scr[0];
145: }
146:
147: /**
148: * Get a new rectangular <code>Region</code>.
149: * @param x The upper left x coordinate of the region
150: * @param y The upper left y coordinate of the region
151: * @param w The width of the region
152: * @param h The height of the region
153: * @return The newly-created <code>Region</code> object.
154: */
155: public abstract Region makeRegion(int x, int y, int w, int h);
156:
157: /**
158: * Set the visibility of the cursor.
159: * @param visible true to make the cursor visible, false otherwise.
160: */
161: public abstract void setCursorVisibility(boolean visible);
162:
163: /**
164: * Query the visibility of the cursor.
165: * @return true if the cursor is currently visible.
166: */
167: public abstract boolean isCursorVisible();
168:
169: /**
170: * Get the cursor hotspot.
171: */
172: public abstract Point getCursorLocation();
173:
174: /**
175: * Create a new <code>CursorImage</code> object.
176: */
177: public abstract CursorImage makeCursorImage(Image img, int hotX,
178: int hotY);
179:
180: /**
181: * Get a <code>CursorImage</code> object that corresponds to a standard
182: * "system" cursor.
183: * @param c A Cursor object which specifies a standard system cursor.
184: * @return The corresponding CursorImage.
185: */
186: public abstract CursorImage getCursorImage(Cursor c);
187:
188: /**
189: * Set the cursor image to match the supplied <code>CursorImage</code> object.
190: * @param image The contents of the cursor image.
191: */
192: public abstract void setCursorImage(CursorImage image);
193:
194: /**
195: * Get the maximum supported size for a cursor.
196: * @return a <code>Dimension</code> object containing the maximum cursor size, or
197: * null if there is no maximum. While a return value of null implies that
198: * there is no maximum, it does not guarantee that all sizes are
199: * supported, because aspect ratio has not been taken into account.
200: */
201: public abstract Dimension getMaximumCursorSize();
202:
203: /**
204: * Find the nearest supported cursor size.
205: * @return true if the size is supported, false otherwise.
206: */
207: public abstract Dimension getBestCursorSize(int width, int height);
208:
209: /**
210: * Returns the maximum number of colors allowed in a cursor. "Transparent"
211: * is not to be counted as a color.
212: * @return the maximum number of colors supported in a cursor image.
213: */
214: public abstract int getMaximumCursorColors();
215:
216: /**
217: * Prepares an image for rendering.
218: * <p>
219: * If the values of the width and height arguments are both
220: * <code>-1</code>, this method prepares the image for rendering
221: * on the default screen; otherwise, this method prepares an image
222: * for rendering on the default screen at the specified width and height.
223: * <p>
224: * The image data is downloaded asynchronously in another thread,
225: * and an appropriately scaled screen representation of the image is
226: * generated.
227: * <p>
228: * This method is called by components <code>prepareImage</code>
229: * methods.
230: * <p>
231: * Information on the flags returned by this method can be found
232: * with the definition of the <code>ImageObserver</code> interface.
233:
234: * @param image the image for which to prepare a
235: * screen representation.
236: * @param width the width of the desired screen
237: * representation, or <code>-1</code>.
238: * @param height the height of the desired screen
239: * representation, or <code>-1</code>.
240: * @param observer the <code>ImageObserver</code>
241: * object to be notified as the
242: * image is being prepared.
243: * @return <code>true</code> if the image has already been
244: * fully prepared; <code>false</code> otherwise.
245: * @see java.awt.Component#prepareImage(java.awt.Image,
246: * java.awt.image.ImageObserver)
247: * @see java.awt.Component#prepareImage(java.awt.Image,
248: * int, int, java.awt.image.ImageObserver)
249: * @see java.awt.image.ImageObserver
250: */
251: public abstract boolean prepareScrImage(java.awt.Image image,
252: int width, int height, java.awt.image.ImageObserver observer);
253:
254: /**
255: * Indicates the construction status of a specified image that is
256: * being prepared for display.
257: * <p>
258: * If the values of the width and height arguments are both
259: * <code>-1</code>, this method returns the construction status of
260: * a screen representation of the specified image in this toolkit.
261: * Otherwise, this method returns the construction status of a
262: * scaled representation of the image at the specified width
263: * and height.
264: * <p>
265: * This method does not cause the image to begin loading.
266: * An application must call <code>prepareImage</code> to force
267: * the loading of an image.
268: * <p>
269: * This method is called by the component's <code>checkImage</code>
270: * methods.
271: * <p>
272: * Information on the flags returned by this method can be found
273: * with the definition of the <code>ImageObserver</code> interface.
274: * @param image the image whose status is being checked.
275: * @param width the width of the scaled version whose status is
276: * being checked, or <code>-1</code>.
277: * @param height the height of the scaled version whose status
278: * is being checked, or <code>-1</code>.
279: * @param observer the <code>ImageObserver</code> object to be
280: * notified as the image is being prepared.
281: * @return the bitwise inclusive <strong>OR</strong> of the
282: * <code>ImageObserver</code> flags for the
283: * image data that is currently available.
284: * @see java.awt.Toolkit#prepareImage(java.awt.Image,
285: * int, int, java.awt.image.ImageObserver)
286: * @see java.awt.Component#checkImage(java.awt.Image,
287: * java.awt.image.ImageObserver)
288: * @see java.awt.Component#checkImage(java.awt.Image,
289: * int, int, java.awt.image.ImageObserver)
290: * @see java.awt.image.ImageObserver
291: */
292: public abstract int checkScrImage(java.awt.Image image, int width,
293: int height, java.awt.image.ImageObserver observer);
294:
295: /**
296: * Return the resolution of the screen, in pixels per inch.
297: */
298: public abstract int getScreenResolution();
299:
300: /**
301: * Synchronizes the graphics state.
302: * Some systems may do buffering of graphics events;
303: * this method ensures that the display is up-to-date. It is useful
304: * for animation.
305: */
306: public abstract void sync();
307:
308: /**
309: * Emits an audio beep.
310: */
311: public abstract void beep();
312: }
|