Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2009, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   
   27   package java.awt;
   28   
   29   import java.awt.image.ColorModel;
   30   
   31   import sun.awt.AWTAccessor;
   32   import sun.awt.AppContext;
   33   import sun.awt.SunToolkit;
   34   
   35   /**
   36    * The <code>GraphicsDevice</code> class describes the graphics devices
   37    * that might be available in a particular graphics environment.  These
   38    * include screen and printer devices. Note that there can be many screens
   39    * and many printers in an instance of {@link GraphicsEnvironment}. Each
   40    * graphics device has one or more {@link GraphicsConfiguration} objects
   41    * associated with it.  These objects specify the different configurations
   42    * in which the <code>GraphicsDevice</code> can be used.
   43    * <p>
   44    * In a multi-screen environment, the <code>GraphicsConfiguration</code>
   45    * objects can be used to render components on multiple screens.  The
   46    * following code sample demonstrates how to create a <code>JFrame</code>
   47    * object for each <code>GraphicsConfiguration</code> on each screen
   48    * device in the <code>GraphicsEnvironment</code>:
   49    * <pre>
   50    *   GraphicsEnvironment ge = GraphicsEnvironment.
   51    *   getLocalGraphicsEnvironment();
   52    *   GraphicsDevice[] gs = ge.getScreenDevices();
   53    *   for (int j = 0; j < gs.length; j++) {
   54    *      GraphicsDevice gd = gs[j];
   55    *      GraphicsConfiguration[] gc =
   56    *      gd.getConfigurations();
   57    *      for (int i=0; i < gc.length; i++) {
   58    *         JFrame f = new
   59    *         JFrame(gs[j].getDefaultConfiguration());
   60    *         Canvas c = new Canvas(gc[i]);
   61    *         Rectangle gcBounds = gc[i].getBounds();
   62    *         int xoffs = gcBounds.x;
   63    *         int yoffs = gcBounds.y;
   64    *         f.getContentPane().add(c);
   65    *         f.setLocation((i*50)+xoffs, (i*60)+yoffs);
   66    *         f.show();
   67    *      }
   68    *   }
   69    * </pre>
   70    * <p>
   71    * For more information on full-screen exclusive mode API, see the
   72    * <a href="http://java.sun.com/docs/books/tutorial/extra/fullscreen/index.html">
   73    * Full-Screen Exclusive Mode API Tutorial</a>.
   74    *
   75    * @see GraphicsEnvironment
   76    * @see GraphicsConfiguration
   77    */
   78   public abstract class GraphicsDevice {
   79   
   80       private Window fullScreenWindow;
   81       private AppContext fullScreenAppContext; // tracks which AppContext
   82                                                // created the FS window
   83       // this lock is used for making synchronous changes to the AppContext's
   84       // current full screen window
   85       private final Object fsAppContextLock = new Object();
   86   
   87       private Rectangle windowedModeBounds;
   88   
   89       /**
   90        * This is an abstract class that cannot be instantiated directly.
   91        * Instances must be obtained from a suitable factory or query method.
   92        * @see GraphicsEnvironment#getScreenDevices
   93        * @see GraphicsEnvironment#getDefaultScreenDevice
   94        * @see GraphicsConfiguration#getDevice
   95        */
   96       protected GraphicsDevice() {
   97       }
   98   
   99       /**
  100        * Device is a raster screen.
  101        */
  102       public final static int TYPE_RASTER_SCREEN          = 0;
  103   
  104       /**
  105        * Device is a printer.
  106        */
  107       public final static int TYPE_PRINTER                = 1;
  108   
  109       /**
  110        * Device is an image buffer.  This buffer can reside in device
  111        * or system memory but it is not physically viewable by the user.
  112        */
  113       public final static int TYPE_IMAGE_BUFFER           = 2;
  114   
  115       /**
  116        * Kinds of translucency supported by the underlying system.
  117        *
  118        * @see #isWindowTranslucencySupported
  119        *
  120        * @since 1.7
  121        */
  122       public static enum WindowTranslucency {
  123           /**
  124            * Represents support in the underlying system for windows each pixel
  125            * of which is guaranteed to be either completely opaque, with
  126            * an alpha value of 1.0, or completely transparent, with an alpha
  127            * value of 0.0.
  128            */
  129           PERPIXEL_TRANSPARENT,
  130           /**
  131            * Represents support in the underlying system for windows all of
  132            * the pixels of which have the same alpha value between or including
  133            * 0.0 and 1.0.
  134            */
  135           TRANSLUCENT,
  136           /**
  137            * Represents support in the underlying system for windows that
  138            * contain or might contain pixels with arbitrary alpha values
  139            * between and including 0.0 and 1.0.
  140            */
  141           PERPIXEL_TRANSLUCENT;
  142       }
  143   
  144       /**
  145        * Returns the type of this <code>GraphicsDevice</code>.
  146        * @return the type of this <code>GraphicsDevice</code>, which can
  147        * either be TYPE_RASTER_SCREEN, TYPE_PRINTER or TYPE_IMAGE_BUFFER.
  148        * @see #TYPE_RASTER_SCREEN
  149        * @see #TYPE_PRINTER
  150        * @see #TYPE_IMAGE_BUFFER
  151        */
  152       public abstract int getType();
  153   
  154       /**
  155        * Returns the identification string associated with this
  156        * <code>GraphicsDevice</code>.
  157        * <p>
  158        * A particular program might use more than one
  159        * <code>GraphicsDevice</code> in a <code>GraphicsEnvironment</code>.
  160        * This method returns a <code>String</code> identifying a
  161        * particular <code>GraphicsDevice</code> in the local
  162        * <code>GraphicsEnvironment</code>.  Although there is
  163        * no public method to set this <code>String</code>, a programmer can
  164        * use the <code>String</code> for debugging purposes.  Vendors of
  165        * the Java<sup><font size=-2>TM</font></sup> Runtime Environment can
  166        * format the return value of the <code>String</code>.  To determine
  167        * how to interpret the value of the <code>String</code>, contact the
  168        * vendor of your Java Runtime.  To find out who the vendor is, from
  169        * your program, call the
  170        * {@link System#getProperty(String) getProperty} method of the
  171        * System class with "java.vendor".
  172        * @return a <code>String</code> that is the identification
  173        * of this <code>GraphicsDevice</code>.
  174        */
  175       public abstract String getIDstring();
  176   
  177       /**
  178        * Returns all of the <code>GraphicsConfiguration</code>
  179        * objects associated with this <code>GraphicsDevice</code>.
  180        * @return an array of <code>GraphicsConfiguration</code>
  181        * objects that are associated with this
  182        * <code>GraphicsDevice</code>.
  183        */
  184       public abstract GraphicsConfiguration[] getConfigurations();
  185   
  186       /**
  187        * Returns the default <code>GraphicsConfiguration</code>
  188        * associated with this <code>GraphicsDevice</code>.
  189        * @return the default <code>GraphicsConfiguration</code>
  190        * of this <code>GraphicsDevice</code>.
  191        */
  192       public abstract GraphicsConfiguration getDefaultConfiguration();
  193   
  194       /**
  195        * Returns the "best" configuration possible that passes the
  196        * criteria defined in the {@link GraphicsConfigTemplate}.
  197        * @param gct the <code>GraphicsConfigTemplate</code> object
  198        * used to obtain a valid <code>GraphicsConfiguration</code>
  199        * @return a <code>GraphicsConfiguration</code> that passes
  200        * the criteria defined in the specified
  201        * <code>GraphicsConfigTemplate</code>.
  202        * @see GraphicsConfigTemplate
  203        */
  204       public GraphicsConfiguration
  205              getBestConfiguration(GraphicsConfigTemplate gct) {
  206           GraphicsConfiguration[] configs = getConfigurations();
  207           return gct.getBestConfiguration(configs);
  208       }
  209   
  210       /**
  211        * Returns <code>true</code> if this <code>GraphicsDevice</code>
  212        * supports full-screen exclusive mode.
  213        * If a SecurityManager is installed, its
  214        * <code>checkPermission</code> method will be called
  215        * with <code>AWTPermission("fullScreenExclusive")</code>.
  216        * <code>isFullScreenSupported</code> returns true only if
  217        * that permission is granted.
  218        * @return whether full-screen exclusive mode is available for
  219        * this graphics device
  220        * @see java.awt.AWTPermission
  221        * @since 1.4
  222        */
  223       public boolean isFullScreenSupported() {
  224           return false;
  225       }
  226   
  227       /**
  228        * Enter full-screen mode, or return to windowed mode.  The entered
  229        * full-screen mode may be either exclusive or simulated.  Exclusive
  230        * mode is only available if <code>isFullScreenSupported</code>
  231        * returns <code>true</code>.
  232        * <p>
  233        * Exclusive mode implies:
  234        * <ul>
  235        * <li>Windows cannot overlap the full-screen window.  All other application
  236        * windows will always appear beneath the full-screen window in the Z-order.
  237        * <li>There can be only one full-screen window on a device at any time,
  238        * so calling this method while there is an existing full-screen Window
  239        * will cause the existing full-screen window to
  240        * return to windowed mode.
  241        * <li>Input method windows are disabled.  It is advisable to call
  242        * <code>Component.enableInputMethods(false)</code> to make a component
  243        * a non-client of the input method framework.
  244        * </ul>
  245        * <p>
  246        * The simulated full-screen mode places and resizes the window to the maximum
  247        * possible visible area of the screen. However, the native windowing system
  248        * may modify the requested geometry-related data, so that the {@code Window} object
  249        * is placed and sized in a way that corresponds closely to the desktop settings.
  250        * <p>
  251        * When entering full-screen mode, if the window to be used as a
  252        * full-screen window is not visible, this method will make it visible.
  253        * It will remain visible when returning to windowed mode.
  254        * <p>
  255        * When entering full-screen mode, all the translucency effects are reset for
  256        * the window. Its shape is set to {@code null}, the opacity value is set to
  257        * 1.0f, and the background color alpha is set to 255 (completely opaque).
  258        * These values are not restored when returning to windowed mode.
  259        * <p>
  260        * It is unspecified and platform-dependent how decorated windows operate
  261        * in full-screen mode. For this reason, it is recommended to turn off
  262        * the decorations in a {@code Frame} or {@code Dialog} object by using the
  263        * {@code setUndecorated} method.
  264        * <p>
  265        * When returning to windowed mode from an exclusive full-screen window,
  266        * any display changes made by calling {@code setDisplayMode} are
  267        * automatically restored to their original state.
  268        *
  269        * @param w a window to use as the full-screen window; {@code null}
  270        * if returning to windowed mode.  Some platforms expect the
  271        * fullscreen window to be a top-level component (i.e., a {@code Frame});
  272        * therefore it is preferable to use a {@code Frame} here rather than a
  273        * {@code Window}.
  274        *
  275        * @see #isFullScreenSupported
  276        * @see #getFullScreenWindow
  277        * @see #setDisplayMode
  278        * @see Component#enableInputMethods
  279        * @see Component#setVisible
  280        * @see Frame#setUndecorated
  281        * @see Dialog#setUndecorated
  282        *
  283        * @since 1.4
  284        */
  285       public void setFullScreenWindow(Window w) {
  286           if (w != null) {
  287               if (w.getShape() != null) {
  288                   w.setShape(null);
  289               }
  290               if (w.getOpacity() < 1.0f) {
  291                   w.setOpacity(1.0f);
  292               }
  293               if (!w.isOpaque()) {
  294                   Color bgColor = w.getBackground();
  295                   bgColor = new Color(bgColor.getRed(), bgColor.getGreen(),
  296                                       bgColor.getBlue(), 255);
  297                   w.setBackground(bgColor);
  298               }
  299           }
  300           if (fullScreenWindow != null && windowedModeBounds != null) {
  301               // if the window went into fs mode before it was realized it may
  302               // have (0,0) dimensions
  303               if (windowedModeBounds.width  == 0) windowedModeBounds.width  = 1;
  304               if (windowedModeBounds.height == 0) windowedModeBounds.height = 1;
  305               fullScreenWindow.setBounds(windowedModeBounds);
  306           }
  307           // Set the full screen window
  308           synchronized (fsAppContextLock) {
  309               // Associate fullscreen window with current AppContext
  310               if (w == null) {
  311                   fullScreenAppContext = null;
  312               } else {
  313                   fullScreenAppContext = AppContext.getAppContext();
  314               }
  315               fullScreenWindow = w;
  316           }
  317           if (fullScreenWindow != null) {
  318               windowedModeBounds = fullScreenWindow.getBounds();
  319               // Note that we use the graphics configuration of the device,
  320               // not the window's, because we're setting the fs window for
  321               // this device.
  322               Rectangle screenBounds = getDefaultConfiguration().getBounds();
  323               fullScreenWindow.setBounds(screenBounds.x, screenBounds.y,
  324                                          screenBounds.width, screenBounds.height);
  325               fullScreenWindow.setVisible(true);
  326               fullScreenWindow.toFront();
  327           }
  328       }
  329   
  330       /**
  331        * Returns the <code>Window</code> object representing the
  332        * full-screen window if the device is in full-screen mode.
  333        *
  334        * @return the full-screen window, or <code>null</code> if the device is
  335        * not in full-screen mode.
  336        * @see #setFullScreenWindow(Window)
  337        * @since 1.4
  338        */
  339       public Window getFullScreenWindow() {
  340           Window returnWindow = null;
  341           synchronized (fsAppContextLock) {
  342               // Only return a handle to the current fs window if we are in the
  343               // same AppContext that set the fs window
  344               if (fullScreenAppContext == AppContext.getAppContext()) {
  345                   returnWindow = fullScreenWindow;
  346               }
  347           }
  348           return returnWindow;
  349       }
  350   
  351       /**
  352        * Returns <code>true</code> if this <code>GraphicsDevice</code>
  353        * supports low-level display changes.
  354        * On some platforms low-level display changes may only be allowed in
  355        * full-screen exclusive mode (i.e., if {@link #isFullScreenSupported()}
  356        * returns {@code true} and the application has already entered
  357        * full-screen mode using {@link #setFullScreenWindow}).
  358        * @return whether low-level display changes are supported for this
  359        * graphics device.
  360        * @see #isFullScreenSupported
  361        * @see #setDisplayMode
  362        * @see #setFullScreenWindow
  363        * @since 1.4
  364        */
  365       public boolean isDisplayChangeSupported() {
  366           return false;
  367       }
  368   
  369       /**
  370        * Sets the display mode of this graphics device. This is only allowed
  371        * if {@link #isDisplayChangeSupported()} returns {@code true} and may
  372        * require first entering full-screen exclusive mode using
  373        * {@link #setFullScreenWindow} providing that full-screen exclusive mode is
  374        * supported (i.e., {@link #isFullScreenSupported()} returns
  375        * {@code true}).
  376        * <p>
  377        *
  378        * The display mode must be one of the display modes returned by
  379        * {@link #getDisplayModes()}, with one exception: passing a display mode
  380        * with {@link DisplayMode#REFRESH_RATE_UNKNOWN} refresh rate will result in
  381        * selecting a display mode from the list of available display modes with
  382        * matching width, height and bit depth.
  383        * However, passing a display mode with {@link DisplayMode#BIT_DEPTH_MULTI}
  384        * for bit depth is only allowed if such mode exists in the list returned by
  385        * {@link #getDisplayModes()}.
  386        * <p>
  387        * Example code:
  388        * <pre><code>
  389        * Frame frame;
  390        * DisplayMode newDisplayMode;
  391        * GraphicsDevice gd;
  392        * // create a Frame, select desired DisplayMode from the list of modes
  393        * // returned by gd.getDisplayModes() ...
  394        *
  395        * if (gd.isFullScreenSupported()) {
  396        *     gd.setFullScreenWindow(frame);
  397        * } else {
  398        *    // proceed in non-full-screen mode
  399        *    frame.setSize(...);
  400        *    frame.setLocation(...);
  401        *    frame.setVisible(true);
  402        * }
  403        *
  404        * if (gd.isDisplayChangeSupported()) {
  405        *     gd.setDisplayMode(newDisplayMode);
  406        * }
  407        * </code></pre>
  408        *
  409        * @param dm The new display mode of this graphics device.
  410        * @exception IllegalArgumentException if the <code>DisplayMode</code>
  411        * supplied is <code>null</code>, or is not available in the array returned
  412        * by <code>getDisplayModes</code>
  413        * @exception UnsupportedOperationException if
  414        * <code>isDisplayChangeSupported</code> returns <code>false</code>
  415        * @see #getDisplayMode
  416        * @see #getDisplayModes
  417        * @see #isDisplayChangeSupported
  418        * @since 1.4
  419        */
  420       public void setDisplayMode(DisplayMode dm) {
  421           throw new UnsupportedOperationException("Cannot change display mode");
  422       }
  423   
  424       /**
  425        * Returns the current display mode of this
  426        * <code>GraphicsDevice</code>.
  427        * The returned display mode is allowed to have a refresh rate
  428        * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
  429        * Likewise, the returned display mode is allowed to have a bit depth
  430        * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
  431        * bit depths are supported.
  432        * @return the current display mode of this graphics device.
  433        * @see #setDisplayMode(DisplayMode)
  434        * @since 1.4
  435        */
  436       public DisplayMode getDisplayMode() {
  437           GraphicsConfiguration gc = getDefaultConfiguration();
  438           Rectangle r = gc.getBounds();
  439           ColorModel cm = gc.getColorModel();
  440           return new DisplayMode(r.width, r.height, cm.getPixelSize(), 0);
  441       }
  442   
  443       /**
  444        * Returns all display modes available for this
  445        * <code>GraphicsDevice</code>.
  446        * The returned display modes are allowed to have a refresh rate
  447        * {@link DisplayMode#REFRESH_RATE_UNKNOWN} if it is indeterminate.
  448        * Likewise, the returned display modes are allowed to have a bit depth
  449        * {@link DisplayMode#BIT_DEPTH_MULTI} if it is indeterminate or if multiple
  450        * bit depths are supported.
  451        * @return all of the display modes available for this graphics device.
  452        * @since 1.4
  453        */
  454       public DisplayMode[] getDisplayModes() {
  455           return new DisplayMode[] { getDisplayMode() };
  456       }
  457   
  458       /**
  459        * This method returns the number of bytes available in
  460        * accelerated memory on this device.
  461        * Some images are created or cached
  462        * in accelerated memory on a first-come,
  463        * first-served basis.  On some operating systems,
  464        * this memory is a finite resource.  Calling this method
  465        * and scheduling the creation and flushing of images carefully may
  466        * enable applications to make the most efficient use of
  467        * that finite resource.
  468        * <br>
  469        * Note that the number returned is a snapshot of how much
  470        * memory is available; some images may still have problems
  471        * being allocated into that memory.  For example, depending
  472        * on operating system, driver, memory configuration, and
  473        * thread situations, the full extent of the size reported
  474        * may not be available for a given image.  There are further
  475        * inquiry methods on the {@link ImageCapabilities} object
  476        * associated with a VolatileImage that can be used to determine
  477        * whether a particular VolatileImage has been created in accelerated
  478        * memory.
  479        * @return number of bytes available in accelerated memory.
  480        * A negative return value indicates that the amount of accelerated memory
  481        * on this GraphicsDevice is indeterminate.
  482        * @see java.awt.image.VolatileImage#flush
  483        * @see ImageCapabilities#isAccelerated
  484        * @since 1.4
  485        */
  486       public int getAvailableAcceleratedMemory() {
  487           return -1;
  488       }
  489   
  490       /**
  491        * Returns whether the given level of translucency is supported by
  492        * this graphics device.
  493        *
  494        * @param translucencyKind a kind of translucency support
  495        * @return whether the given translucency kind is supported
  496        *
  497        * @since 1.7
  498        */
  499       public boolean isWindowTranslucencySupported(WindowTranslucency translucencyKind) {
  500           switch (translucencyKind) {
  501               case PERPIXEL_TRANSPARENT:
  502                   return isWindowShapingSupported();
  503               case TRANSLUCENT:
  504                   return isWindowOpacitySupported();
  505               case PERPIXEL_TRANSLUCENT:
  506                   return isWindowPerpixelTranslucencySupported();
  507           }
  508           return false;
  509       }
  510   
  511       /**
  512        * Returns whether the windowing system supports changing the shape
  513        * of top-level windows.
  514        * Note that this method may sometimes return true, but the native
  515        * windowing system may still not support the concept of
  516        * shaping (due to the bugs in the windowing system).
  517        */
  518       static boolean isWindowShapingSupported() {
  519           Toolkit curToolkit = Toolkit.getDefaultToolkit();
  520           if (!(curToolkit instanceof SunToolkit)) {
  521               return false;
  522           }
  523           return ((SunToolkit)curToolkit).isWindowShapingSupported();
  524       }
  525   
  526       /**
  527        * Returns whether the windowing system supports changing the opacity
  528        * value of top-level windows.
  529        * Note that this method may sometimes return true, but the native
  530        * windowing system may still not support the concept of
  531        * translucency (due to the bugs in the windowing system).
  532        */
  533       static boolean isWindowOpacitySupported() {
  534           Toolkit curToolkit = Toolkit.getDefaultToolkit();
  535           if (!(curToolkit instanceof SunToolkit)) {
  536               return false;
  537           }
  538           return ((SunToolkit)curToolkit).isWindowOpacitySupported();
  539       }
  540   
  541       boolean isWindowPerpixelTranslucencySupported() {
  542           /*
  543            * Per-pixel alpha is supported if all the conditions are TRUE:
  544            *    1. The toolkit is a sort of SunToolkit
  545            *    2. The toolkit supports translucency in general
  546            *        (isWindowTranslucencySupported())
  547            *    3. There's at least one translucency-capable
  548            *        GraphicsConfiguration
  549            */
  550           Toolkit curToolkit = Toolkit.getDefaultToolkit();
  551           if (!(curToolkit instanceof SunToolkit)) {
  552               return false;
  553           }
  554           if (!((SunToolkit)curToolkit).isWindowTranslucencySupported()) {
  555               return false;
  556           }
  557   
  558           // TODO: cache translucency capable GC
  559           return getTranslucencyCapableGC() != null;
  560       }
  561   
  562       GraphicsConfiguration getTranslucencyCapableGC() {
  563           // If the default GC supports translucency return true.
  564           // It is important to optimize the verification this way,
  565           // see CR 6661196 for more details.
  566           GraphicsConfiguration defaultGC = getDefaultConfiguration();
  567           if (defaultGC.isTranslucencyCapable()) {
  568               return defaultGC;
  569           }
  570   
  571           // ... otherwise iterate through all the GCs.
  572           GraphicsConfiguration[] configs = getConfigurations();
  573           for (int j = 0; j < configs.length; j++) {
  574               if (configs[j].isTranslucencyCapable()) {
  575                   return configs[j];
  576               }
  577           }
  578   
  579           return null;
  580       }
  581   }

Home » openjdk-7 » java » awt » [javadoc | source]