Source for java.awt.GraphicsDevice

   1: /* GraphicsDevice.java -- information about a graphics device
   2:    Copyright (C) 2002, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.awt;
  40: 
  41: import java.awt.image.VolatileImage;
  42: 
  43: /**
  44:  * This describes a graphics device available to the given environment. This
  45:  * includes screen and printer devices, and the different configurations for
  46:  * each device. Also, this allows you to create virtual devices which operate
  47:  * over a multi-screen environment.
  48:  *
  49:  * @author Eric Blake (ebb9@email.byu.edu)
  50:  * @see GraphicsEnvironment
  51:  * @see GraphicsConfiguration
  52:  * @since 1.3
  53:  * @status updated to 1.4
  54:  */
  55: public abstract class GraphicsDevice
  56: {
  57:   /** Device is a raster screen. */
  58:   public static final int TYPE_RASTER_SCREEN = 0;
  59: 
  60:   /** Device is a printer. */
  61:   public static final int TYPE_PRINTER = 1;
  62: 
  63:   /** Device is an image buffer not visible to the user. */
  64:   public static final int TYPE_IMAGE_BUFFER = 2;
  65: 
  66:   /** The current full-screen window, or null if there is none. */
  67:   private Window full_screen;
  68: 
  69:   /**
  70:    * The bounds of the fullscreen window before it has been switched to full
  71:    * screen.
  72:    */
  73:   private Rectangle fullScreenOldBounds;
  74: 
  75:   /** The current display mode, or null if unknown. */
  76:   private DisplayMode mode;
  77: 
  78:   /**
  79:    * The default constructor.
  80:    *
  81:    * @see GraphicsEnvironment#getScreenDevices()
  82:    * @see GraphicsEnvironment#getDefaultScreenDevice()
  83:    * @see GraphicsConfiguration#getDevice()
  84:    */
  85:   protected GraphicsDevice()
  86:   {
  87:   }
  88: 
  89:   /**
  90:    * Returns the type of the device.
  91:    *
  92:    * @return the device type
  93:    * @see #TYPE_RASTER_SCREEN
  94:    * @see #TYPE_PRINTER
  95:    * @see #TYPE_IMAGE_BUFFER
  96:    */
  97:   public abstract int getType();
  98: 
  99:   /**
 100:    * Returns an identification string for the device. This can be
 101:    * vendor-specific, and may be useful for debugging.
 102:    *
 103:    * @return the identification
 104:    */
 105:   public abstract String getIDstring();
 106: 
 107:   /**
 108:    * Return all configurations valid for this device.
 109:    *
 110:    * @return an array of configurations
 111:    */
 112:   public abstract GraphicsConfiguration[] getConfigurations();
 113: 
 114:   /**
 115:    * Return the default configuration for this device.
 116:    *
 117:    * @return the default configuration
 118:    */
 119:   public abstract GraphicsConfiguration getDefaultConfiguration();
 120: 
 121:   /**
 122:    * Return the best configuration, according to the criteria in the given
 123:    * template.
 124:    *
 125:    * @param template the template to adjust by
 126:    * @return the best configuration
 127:    * @throws NullPointerException if template is null
 128:    */
 129:   public GraphicsConfiguration getBestConfiguration
 130:     (GraphicsConfigTemplate template)
 131:   {
 132:     return template.getBestConfiguration(getConfigurations());
 133:   }
 134: 
 135:   /**
 136:    * Returns true if the device supports full-screen exclusive mode. The
 137:    * default implementation returns true; subclass it if this is not the case.
 138:    *
 139:    * @return true if full screen support is available
 140:    * @since 1.4
 141:    */
 142:   public boolean isFullScreenSupported()
 143:   {
 144:     return true;
 145:   }
 146: 
 147:   /**
 148:    * Toggle the given window between full screen and normal mode. The previous
 149:    * full-screen window, if different, is restored; if the given window is
 150:    * null, no window will be full screen. If
 151:    * <code>isFullScreenSupported()</code> returns true, full screen mode is
 152:    * considered to be exclusive, which implies:<ul>
 153:    * <li>Windows cannot overlap the full-screen window. All other application
 154:    *     windows will always appear beneath the full-screen window in the
 155:    *     Z-order.</li>
 156:    * <li>Input method windows are disabled. It is advisable to call
 157:    *     <code>Component.enableInputMethods(false)</code> to make a component
 158:    *     a non-client of the input method framework.</li>
 159:    * </ul><br>
 160:    * If <code>isFullScreenSupported()</code> returns false, full-screen
 161:    * exclusive mode is simulated by resizing the window to the size of the
 162:    * screen and positioning it at (0,0). This is also what this method does.
 163:    * If a device supports real fullscreen mode then it should override this
 164:    * method as well as #isFullScreenSupported and #getFullScreenWindow.
 165:    *
 166:    * @param w the window to toggle
 167:    * @see #isFullScreenSupported()
 168:    * @see #getFullScreenWindow()
 169:    * @see #setDisplayMode(DisplayMode)
 170:    * @see Component#enableInputMethods(boolean)
 171:    * @since 1.4
 172:    */
 173:   public synchronized void setFullScreenWindow(Window w)
 174:   {
 175:     // Restore the previous window to normal mode and release the reference.
 176:     if (full_screen != null)
 177:       {
 178:     full_screen.setBounds(fullScreenOldBounds);
 179:       }
 180: 
 181:     full_screen = null;
 182: 
 183:     // If w != null, make it full-screen.
 184:     if (w != null)
 185:       {
 186:     fullScreenOldBounds = w.getBounds();
 187:     full_screen = w;
 188:     DisplayMode dMode = getDisplayMode();
 189:     full_screen.setBounds(0, 0, dMode.getWidth(), dMode.getHeight());
 190:     full_screen.requestFocus();
 191:     full_screen.setLocationRelativeTo(null);
 192:       }
 193:   }
 194: 
 195:   /**
 196:    * Returns the current full-screen window of the device, or null if no
 197:    * window is full-screen.
 198:    *
 199:    * @return the full-screen window
 200:    * @see #setFullScreenWindow(Window)
 201:    * @since 1.4
 202:    */
 203:   public Window getFullScreenWindow()
 204:   {
 205:     return full_screen;
 206:   }
 207: 
 208:   /**
 209:    * Returns whether this device supports low-level display changes. This may
 210:    * depend on whether full-screen exclusive mode is available.
 211:    *
 212:    * XXX The default implementation returns false for now.
 213:    *
 214:    * @return true if display changes are supported
 215:    * @see #setDisplayMode(DisplayMode)
 216:    * @since 1.4
 217:    */
 218:   public boolean isDisplayChangeSupported()
 219:   {
 220:     return false;
 221:   }
 222: 
 223:   /**
 224:    * Sets the display mode. This may be dependent on the availability of
 225:    * full-screen exclusive mode.
 226:    *
 227:    * @param mode the new mode
 228:    * @throws IllegalArgumentException if the new mode is not in getDisplayModes
 229:    * @throws UnsupportedOperationException if ! isDisplayChangeSupported()
 230:    * @see #getDisplayMode()
 231:    * @see #getDisplayModes()
 232:    * @see #isDisplayChangeSupported()
 233:    * @since 1.4
 234:    */
 235:   public void setDisplayMode(DisplayMode mode)
 236:   {
 237:     DisplayMode[] array = getDisplayModes();
 238:     if (! isDisplayChangeSupported())
 239:       throw new UnsupportedOperationException();
 240:     int i = array == null ? 0 : array.length;
 241:     while (--i >= 0)
 242:       if (array[i].equals(mode))
 243:         break;
 244:     if (i < 0)
 245:       throw new IllegalArgumentException();
 246:     this.mode = mode;
 247:   }
 248: 
 249:   /**
 250:    * Returns the current display mode of this device, or null if unknown.
 251:    *
 252:    * @return the current display mode
 253:    * @see #setDisplayMode(DisplayMode)
 254:    * @see #getDisplayModes()
 255:    * @since 1.4
 256:    */
 257:   public DisplayMode getDisplayMode()
 258:   {
 259:     return mode;
 260:   }
 261: 
 262:   /**
 263:    * Return an array of all available display modes. This implementation
 264:    * returns a 0-length array, so subclasses must override this.
 265:    *
 266:    * @return the array of available modes
 267:    * @since 1.4
 268:    */
 269:   public DisplayMode[] getDisplayModes()
 270:   {
 271:     return new DisplayMode[0];
 272:   }
 273: 
 274:   /**
 275:    * Return the number of bytes available in accelerated memory on this
 276:    * device. The device may support creation or caching on a first-come,
 277:    * first-served basis, depending on the operating system and driver.
 278:    * Memory may be a finite resource, and because of multi-threading, you
 279:    * are not guaranteed that the result of this method ensures your image
 280:    * will successfully be put in accelerated memory. A negative result means
 281:    * the memory is unlimited. The default implementation assumes no special
 282:    * memory is available, and returns 0.
 283:    *
 284:    * @return the size of accelerated memory available
 285:    * @see VolatileImage#flush()
 286:    * @see ImageCapabilities#isAccelerated()
 287:    */
 288:   public int getAvailableAcceleratedMemory()
 289:   {
 290:     return 0;
 291:   }
 292: } // class GraphicsDevice