GraphicsDevice


1   /*
2    * @(#)GraphicsDevice.java  1.30 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   
9   package java.awt;
10  
11  import java.awt.image.ColorModel  ;
12  
13  /**
14   * The <code>GraphicsDevice</code> class describes the graphics devices
15   * that might be available in a particular graphics environment.  These
16   * include screen and printer devices. Note that there can be many screens
17   * and many printers in an instance of {@link GraphicsEnvironment}. Each
18   * graphics device has one or more {@link GraphicsConfiguration} objects
19   * associated with it.  These objects specify the different configurations
20   * in which the <code>GraphicsDevice</code> can be used.
21   * <p>  
22   * In a multi-screen environment, the <code>GraphicsConfiguration</code>
23   * objects can be used to render components on multiple screens.  The 
24   * following code sample demonstrates how to create a <code>JFrame</code>
25   * object for each <code>GraphicsConfiguration</code> on each screen
26   * device in the <code>GraphicsEnvironment</code>:
27   * <pre>
28   *   GraphicsEnvironment ge = GraphicsEnvironment.
29   *   getLocalGraphicsEnvironment();
30   *   GraphicsDevice[] gs = ge.getScreenDevices();
31   *   for (int j = 0; j < gs.length; j++) { 
32   *      GraphicsDevice gd = gs[j];
33   *      GraphicsConfiguration[] gc =
34   *  gd.getConfigurations();
35   *      for (int i=0; i < gc.length; i++) {
36   *         JFrame f = new
37   *         JFrame(gs[j].getDefaultConfiguration());
38   *         Canvas c = new Canvas(gc[i]); 
39   *         Rectangle gcBounds = gc[i].getBounds();
40   *         int xoffs = gcBounds.x;
41   *         int yoffs = gcBounds.y;
42   *     f.getContentPane().add(c);
43   *     f.setLocation((i*50)+xoffs, (i*60)+yoffs);
44   *         f.show();
45   *      }
46   *   }
47   * </pre>                           
48   * @see GraphicsEnvironment
49   * @see GraphicsConfiguration
50   * @version 1.30, 12/19/03
51   */
52  public abstract class GraphicsDevice {
53  
54      private Window   fullScreenWindow;
55      private Rectangle   windowedModeBounds;
56      
57      /**
58       * This is an abstract class that cannot be instantiated directly.
59       * Instances must be obtained from a suitable factory or query method.
60       * @see GraphicsEnvironment#getScreenDevices
61       * @see GraphicsEnvironment#getDefaultScreenDevice
62       * @see GraphicsConfiguration#getDevice
63       */
64      protected GraphicsDevice() {
65      }
66  
67      /**
68       * Device is a raster screen.
69       */
70      public final static int TYPE_RASTER_SCREEN      = 0;
71  
72      /**
73       * Device is a printer.
74       */
75      public final static int TYPE_PRINTER        = 1;
76  
77      /**
78       * Device is an image buffer.  This buffer can reside in device
79       * or system memory but it is not physically viewable by the user.
80       */
81      public final static int TYPE_IMAGE_BUFFER           = 2;
82      
83      /**
84       * Returns the type of this <code>GraphicsDevice</code>.
85       * @return the type of this <code>GraphicsDevice</code>, which can
86       * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER.
87       * @see #TYPE_RASTER_SCREEN
88       * @see #TYPE_PRINTER
89       * @see #TYPE_IMAGE_BUFFER
90       */
91      public abstract int getType();
92  
93      /**
94       * Returns the identification string associated with this 
95       * <code>GraphicsDevice</code>.
96       * <p>
97       * A particular program might use more than one 
98       * <code>GraphicsDevice</code> in a <code>GraphicsEnvironment</code>.
99       * This method returns a <code>String</code> identifying a
100      * particular <code>GraphicsDevice</code> in the local
101      * <code>GraphicsEnvironment</code>.  Although there is
102      * no public method to set this <code>String</code>, a programmer can
103      * use the <code>String</code> for debugging purposes.  Vendors of 
104      * the Java<sup><font size=-2>TM</font></sup> Runtime Environment can
105      * format the return value of the <code>String</code>.  To determine 
106      * how to interpret the value of the <code>String</code>, contact the
107      * vendor of your Java Runtime.  To find out who the vendor is, from
108      * your program, call the 
109      * {@link System#getProperty(String) getProperty} method of the
110      * System class with "java.vendor".
111      * @return a <code>String</code> that is the identification
112      * of this <code>GraphicsDevice</code>.
113      */
114     public abstract String   getIDstring();
115     
116     /**
117      * Returns all of the <code>GraphicsConfiguration</code>
118      * objects associated with this <code>GraphicsDevice</code>.
119      * @return an array of <code>GraphicsConfiguration</code>
120      * objects that are associated with this 
121      * <code>GraphicsDevice</code>.
122      */
123     public abstract GraphicsConfiguration  [] getConfigurations();
124 
125     /**
126      * Returns the default <code>GraphicsConfiguration</code>
127      * associated with this <code>GraphicsDevice</code>.
128      * @return the default <code>GraphicsConfiguration</code>
129      * of this <code>GraphicsDevice</code>.
130      */
131     public abstract GraphicsConfiguration   getDefaultConfiguration();
132 
133     /**
134      * Returns the "best" configuration possible that passes the
135      * criteria defined in the {@link GraphicsConfigTemplate}.
136      * @param gct the <code>GraphicsConfigTemplate</code> object
137      * used to obtain a valid <code>GraphicsConfiguration</code>
138      * @return a <code>GraphicsConfiguration</code> that passes
139      * the criteria defined in the specified
140      * <code>GraphicsConfigTemplate</code>.
141      * @see GraphicsConfigTemplate
142      */
143     public GraphicsConfiguration  
144            getBestConfiguration(GraphicsConfigTemplate   gct) {
145         GraphicsConfiguration  [] configs = getConfigurations();
146         return gct.getBestConfiguration(configs);
147     }
148  
149     /**
150      * Returns <code>true</code> if this <code>GraphicsDevice</code>
151      * supports full-screen exclusive mode.
152      * @return whether full-screen exclusive mode is available for
153      * this graphics device
154      * @since 1.4
155      */
156     public boolean isFullScreenSupported() {
157         return false;
158     }
159     
160     /**
161      * Enter full-screen mode, or return to windowed mode.
162      * <p>
163      * If <code>isFullScreenSupported</code> returns <code>true</code>, full
164      * screen mode is considered to be <i>exclusive</i>, which implies:
165      * <ul>
166      * <li>Windows cannot overlap the full-screen window.  All other application
167      * windows will always appear beneath the full-screen window in the Z-order.
168      * <li>Input method windows are disabled.  It is advisable to call
169      * <code>Component.enableInputMethods(false)</code> to make a component
170      * a non-client of the input method framework.
171      * </ul>
172      * <p>
173      * If <code>isFullScreenSupported</code> returns
174      * <code>false</code>, full-screen exclusive mode is simulated by resizing
175      * the window to the size of the screen and positioning it at (0,0).
176      * <p>
177      * When entering full-screen exclusive mode, if the window to be used as the 
178      * full-screen window is not visible, this method will make it visible. 
179      * It will remain visible when returning to windowed mode.  
180      * <p>
181      * When returning to windowed mode from an exclusive full-screen window, any
182      * display changes made by calling <code>setDisplayMode</code> are
183      * automatically restored to their original state.
184      *
185      * @param w a window to use as the full-screen window; <code>null</code>
186      * if returning to windowed mode.  Some platforms expect the
187      * fullscreen window to be a top-level component (i.e., a Frame);
188      * therefore it is preferable to use a Frame here rather than a
189      * Window. 
190      * @see #isFullScreenSupported
191      * @see #getFullScreenWindow
192      * @see #setDisplayMode
193      * @see Component#enableInputMethods
194      * @see Component#setVisible
195      * @since 1.4
196      */
197     public void setFullScreenWindow(Window   w) {
198         // Get display mode before changing the full screen window
199         DisplayMode   dm;
200         if (w == null) {
201             dm = null;
202         } else {
203             dm = getDisplayMode();
204         }
205         if (fullScreenWindow != null && windowedModeBounds != null) {
206             fullScreenWindow.setBounds(windowedModeBounds);
207     }
208         // Set the full screen window
209         fullScreenWindow = w;
210         if (fullScreenWindow != null) {
211             windowedModeBounds = fullScreenWindow.getBounds();
212             fullScreenWindow.setBounds(0, 0, dm.getWidth(), dm.getHeight());
213             fullScreenWindow.setVisible(true);
214             fullScreenWindow.toFront();
215         }
216     }
217     
218     /**
219      * Returns the <code>Window</code> object representing the 
220      * full-screen window if the device is in full-screen mode.
221      * 
222      * @return the full-screen window, or <code>null</code> if the device is
223      * not in full-screen mode.
224      * @see #setFullScreenWindow(Window)
225      * @since 1.4
226      */
227     public Window   getFullScreenWindow() {
228         return fullScreenWindow;
229     }
230     
231     /**
232      * Returns <code>true</code> if this <code>GraphicsDevice</code>
233      * supports low-level display changes.
234      * @return whether low-level display changes are supported for this
235      * graphics device.  Note that this may or may not be dependent on
236      * full-screen exclusive mode.
237      * @see #setDisplayMode
238      * @since 1.4
239      */
240     public boolean isDisplayChangeSupported() {
241         return false;
242     }
243     
244     /**
245      * Sets the display mode of this graphics device.  This may only be allowed
246      * in full-screen, exclusive mode.
247      * @param dm the new display mode of this graphics device
248      * @exception IllegalArgumentException if the <code>DisplayMode</code>
249      * supplied is <code>null</code>, or is not available in the array returned
250      * by <code>getDisplayModes</code>
251      * @exception UnsupportedOperationException if
252      * <code>isDisplayChangeSupported</code> returns <code>false</code>
253      * @see #getDisplayMode
254      * @see #getDisplayModes
255      * @see #isDisplayChangeSupported
256      * @since 1.4
257      */
258     public void setDisplayMode(DisplayMode   dm) {
259         throw new UnsupportedOperationException  ("Cannot change display mode");
260     }
261     
262     /**
263      * Returns the current display mode of this 
264      * <code>GraphicsDevice</code>.
265      * @return the current display mode of this graphics device.
266      * @see #setDisplayMode(DisplayMode)
267      * @since 1.4
268      */
269     public DisplayMode   getDisplayMode() {
270         GraphicsConfiguration   gc = getDefaultConfiguration();
271         Rectangle   r = gc.getBounds();
272         ColorModel   cm = gc.getColorModel();
273         return new DisplayMode  (r.width, r.height, cm.getPixelSize(), 0);
274     }
275     
276     /**
277      * Returns all display modes available for this      
278      * <code>GraphicsDevice</code>.
279      * @return all of the display modes available for this graphics device.
280      * @since 1.4
281      */
282     public DisplayMode  [] getDisplayModes() {
283         return new DisplayMode  [] { getDisplayMode() };
284     }
285 
286     /**
287      * This method returns the number of bytes available in
288      * accelerated memory on this device.
289      * Some images are created or cached
290      * in accelerated memory on a first-come,
291      * first-served basis.  On some operating systems,
292      * this memory is a finite resource.  Calling this method
293      * and scheduling the creation and flushing of images carefully may
294      * enable applications to make the most efficient use of
295      * that finite resource.
296      * <br>
297      * Note that the number returned is a snapshot of how much
298      * memory is available; some images may still have problems
299      * being allocated into that memory.  For example, depending
300      * on operating system, driver, memory configuration, and
301      * thread situations, the full extent of the size reported
302      * may not be available for a given image.  There are further
303      * inquiry methods on the {@link ImageCapabilities} object
304      * associated with a VolatileImage that can be used to determine
305      * whether a particular VolatileImage has been created in accelerated
306      * memory.
307      * @return number of bytes available in accelerated memory.
308      * A negative return value indicates that accelerated memory
309      * is unlimited.
310      * @see java.awt.image.VolatileImage#flush
311      * @see ImageCapabilities#isAccelerated
312      */
313     public int getAvailableAcceleratedMemory() {
314     return -1;
315     }
316 }
317
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags