| /* |
| * Copyright (c) 2008, 2009, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.awt; |
| |
| import java.awt.*; |
| |
| import sun.awt.AWTAccessor; |
| import sun.awt.SunToolkit; |
| |
| /** |
| * A collection of utility methods for AWT. |
| * |
| * The functionality provided by the static methods of the class includes: |
| * <ul> |
| * <li>Setting shapes on top-level windows |
| * <li>Setting a constant alpha value for each pixel of a top-level window |
| * <li>Making a window non-opaque, after that it paints only explicitly |
| * painted pixels on the screen, with arbitrary alpha values for every pixel. |
| * <li>Setting a 'mixing-cutout' shape for a component. |
| * </ul> |
| * <p> |
| * A "top-level window" is an instance of the {@code Window} class (or its |
| * descendant, such as {@code JFrame}). |
| * <p> |
| * Some of the mentioned features may not be supported by the native platform. |
| * To determine whether a particular feature is supported, the user must use |
| * the {@code isTranslucencySupported()} method of the class passing a desired |
| * translucency kind (a member of the {@code Translucency} enum) as an |
| * argument. |
| * <p> |
| * The per-pixel alpha feature also requires the user to create her/his |
| * windows using a translucency-capable graphics configuration. |
| * The {@code isTranslucencyCapable()} method must |
| * be used to verify whether any given GraphicsConfiguration supports |
| * the trasnlcency effects. |
| * <p> |
| * <b>WARNING</b>: This class is an implementation detail and only meant |
| * for limited use outside of the core platform. This API may change |
| * drastically between update release, and it may even be |
| * removed or be moved in some other package(s)/class(es). |
| */ |
| public final class AWTUtilities { |
| |
| /** |
| * The AWTUtilities class should not be instantiated |
| */ |
| private AWTUtilities() { |
| } |
| |
| /** Kinds of translucency supported by the underlying system. |
| * @see #isTranslucencySupported |
| */ |
| public static enum Translucency { |
| /** |
| * Represents support in the underlying system for windows each pixel |
| * of which is guaranteed to be either completely opaque, with |
| * an alpha value of 1.0, or completely transparent, with an alpha |
| * value of 0.0. |
| */ |
| PERPIXEL_TRANSPARENT, |
| |
| /** |
| * Represents support in the underlying system for windows all of |
| * the pixels of which have the same alpha value between or including |
| * 0.0 and 1.0. |
| */ |
| TRANSLUCENT, |
| |
| /** |
| * Represents support in the underlying system for windows that |
| * contain or might contain pixels with arbitrary alpha values |
| * between and including 0.0 and 1.0. |
| */ |
| PERPIXEL_TRANSLUCENT; |
| } |
| |
| |
| /** |
| * Returns whether the given level of translucency is supported by |
| * the underlying system. |
| * |
| * Note that this method may sometimes return the value |
| * indicating that the particular level is supported, but |
| * the native windowing system may still not support the |
| * given level of translucency (due to the bugs in |
| * the windowing system). |
| * |
| * @param translucencyKind a kind of translucency support |
| * (either PERPIXEL_TRANSPARENT, |
| * TRANSLUCENT, or PERPIXEL_TRANSLUCENT) |
| * @return whether the given translucency kind is supported |
| */ |
| public static boolean isTranslucencySupported(Translucency translucencyKind) { |
| switch (translucencyKind) { |
| case PERPIXEL_TRANSPARENT: |
| return isWindowShapingSupported(); |
| case TRANSLUCENT: |
| return isWindowOpacitySupported(); |
| case PERPIXEL_TRANSLUCENT: |
| return isWindowTranslucencySupported(); |
| } |
| return false; |
| } |
| |
| |
| /** |
| * Returns whether the windowing system supports changing the opacity |
| * value of top-level windows. |
| * Note that this method may sometimes return true, but the native |
| * windowing system may still not support the concept of |
| * translucency (due to the bugs in the windowing system). |
| */ |
| private static boolean isWindowOpacitySupported() { |
| Toolkit curToolkit = Toolkit.getDefaultToolkit(); |
| if (!(curToolkit instanceof SunToolkit)) { |
| return false; |
| } |
| return ((SunToolkit)curToolkit).isWindowOpacitySupported(); |
| } |
| |
| /** |
| * Set the opacity of the window. The opacity is at the range [0..1]. |
| * Note that setting the opacity level of 0 may or may not disable |
| * the mouse event handling on this window. This is |
| * a platform-dependent behavior. |
| * |
| * In order for this method to enable the translucency effect, |
| * the isTranslucencySupported() method should indicate that the |
| * TRANSLUCENT level of translucency is supported. |
| * |
| * <p>Also note that the window must not be in the full-screen mode |
| * when setting the opacity value < 1.0f. Otherwise |
| * the IllegalArgumentException is thrown. |
| * |
| * @param window the window to set the opacity level to |
| * @param opacity the opacity level to set to the window |
| * @throws NullPointerException if the window argument is null |
| * @throws IllegalArgumentException if the opacity is out of |
| * the range [0..1] |
| * @throws IllegalArgumentException if the window is in full screen mode, |
| * and the opacity is less than 1.0f |
| * @throws UnsupportedOperationException if the TRANSLUCENT translucency |
| * kind is not supported |
| */ |
| public static void setWindowOpacity(Window window, float opacity) { |
| if (window == null) { |
| throw new NullPointerException( |
| "The window argument should not be null."); |
| } |
| |
| AWTAccessor.getWindowAccessor().setOpacity(window, opacity); |
| } |
| |
| /** |
| * Get the opacity of the window. If the opacity has not |
| * yet being set, this method returns 1.0. |
| * |
| * @param window the window to get the opacity level from |
| * @throws NullPointerException if the window argument is null |
| */ |
| public static float getWindowOpacity(Window window) { |
| if (window == null) { |
| throw new NullPointerException( |
| "The window argument should not be null."); |
| } |
| |
| return AWTAccessor.getWindowAccessor().getOpacity(window); |
| } |
| |
| /** |
| * Returns whether the windowing system supports changing the shape |
| * of top-level windows. |
| * Note that this method may sometimes return true, but the native |
| * windowing system may still not support the concept of |
| * shaping (due to the bugs in the windowing system). |
| */ |
| public static boolean isWindowShapingSupported() { |
| Toolkit curToolkit = Toolkit.getDefaultToolkit(); |
| if (!(curToolkit instanceof SunToolkit)) { |
| return false; |
| } |
| return ((SunToolkit)curToolkit).isWindowShapingSupported(); |
| } |
| |
| /** |
| * Returns an object that implements the Shape interface and represents |
| * the shape previously set with the call to the setWindowShape() method. |
| * If no shape has been set yet, or the shape has been reset to null, |
| * this method returns null. |
| * |
| * @param window the window to get the shape from |
| * @return the current shape of the window |
| * @throws NullPointerException if the window argument is null |
| */ |
| public static Shape getWindowShape(Window window) { |
| if (window == null) { |
| throw new NullPointerException( |
| "The window argument should not be null."); |
| } |
| return AWTAccessor.getWindowAccessor().getShape(window); |
| } |
| |
| /** |
| * Sets a shape for the given window. |
| * If the shape argument is null, this methods restores |
| * the default shape making the window rectangular. |
| * <p>Note that in order to set a shape, the window must be undecorated. |
| * If the window is decorated, this method ignores the {@code shape} |
| * argument and resets the shape to null. |
| * <p>Also note that the window must not be in the full-screen mode |
| * when setting a non-null shape. Otherwise the IllegalArgumentException |
| * is thrown. |
| * <p>Depending on the platform, the method may return without |
| * effecting the shape of the window if the window has a non-null warning |
| * string ({@link Window#getWarningString()}). In this case the passed |
| * shape object is ignored. |
| * |
| * @param window the window to set the shape to |
| * @param shape the shape to set to the window |
| * @throws NullPointerException if the window argument is null |
| * @throws IllegalArgumentException if the window is in full screen mode, |
| * and the shape is not null |
| * @throws UnsupportedOperationException if the PERPIXEL_TRANSPARENT |
| * translucency kind is not supported |
| */ |
| public static void setWindowShape(Window window, Shape shape) { |
| if (window == null) { |
| throw new NullPointerException( |
| "The window argument should not be null."); |
| } |
| AWTAccessor.getWindowAccessor().setShape(window, shape); |
| } |
| |
| private static boolean isWindowTranslucencySupported() { |
| /* |
| * Per-pixel alpha is supported if all the conditions are TRUE: |
| * 1. The toolkit is a sort of SunToolkit |
| * 2. The toolkit supports translucency in general |
| * (isWindowTranslucencySupported()) |
| * 3. There's at least one translucency-capable |
| * GraphicsConfiguration |
| */ |
| |
| Toolkit curToolkit = Toolkit.getDefaultToolkit(); |
| if (!(curToolkit instanceof SunToolkit)) { |
| return false; |
| } |
| |
| if (!((SunToolkit)curToolkit).isWindowTranslucencySupported()) { |
| return false; |
| } |
| |
| GraphicsEnvironment env = |
| GraphicsEnvironment.getLocalGraphicsEnvironment(); |
| |
| // If the default GC supports translucency return true. |
| // It is important to optimize the verification this way, |
| // see CR 6661196 for more details. |
| if (isTranslucencyCapable(env.getDefaultScreenDevice() |
| .getDefaultConfiguration())) |
| { |
| return true; |
| } |
| |
| // ... otherwise iterate through all the GCs. |
| GraphicsDevice[] devices = env.getScreenDevices(); |
| |
| for (int i = 0; i < devices.length; i++) { |
| GraphicsConfiguration[] configs = devices[i].getConfigurations(); |
| for (int j = 0; j < configs.length; j++) { |
| if (isTranslucencyCapable(configs[j])) { |
| return true; |
| } |
| } |
| } |
| |
| return false; |
| } |
| |
| /** |
| * Enables the per-pixel alpha support for the given window. |
| * Once the window becomes non-opaque (the isOpaque is set to false), |
| * the drawing sub-system is starting to respect the alpha value of each |
| * separate pixel. If a pixel gets painted with alpha color component |
| * equal to zero, it becomes visually transparent, if the alpha of the |
| * pixel is equal to 255, the pixel is fully opaque. Interim values |
| * of the alpha color component make the pixel semi-transparent (i.e. |
| * translucent). |
| * <p>Note that in order for the window to support the per-pixel alpha |
| * mode, the window must be created using the GraphicsConfiguration |
| * for which the {@link #isTranslucencyCapable} |
| * method returns true. |
| * <p>Also note that some native systems enable the per-pixel translucency |
| * mode for any window created using the translucency-compatible |
| * graphics configuration. However, it is highly recommended to always |
| * invoke the setWindowOpaque() method for these windows, at least for |
| * the sake of cross-platform compatibility reasons. |
| * <p>Also note that the window must not be in the full-screen mode |
| * when making it non-opaque. Otherwise the IllegalArgumentException |
| * is thrown. |
| * <p>If the window is a {@code Frame} or a {@code Dialog}, the window must |
| * be undecorated prior to enabling the per-pixel translucency effect (see |
| * {@link Frame#setUndecorated()} and/or {@link Dialog#setUndecorated()}). |
| * If the window becomes decorated through a subsequent call to the |
| * corresponding {@code setUndecorated()} method, the per-pixel |
| * translucency effect will be disabled and the opaque property reset to |
| * {@code true}. |
| * <p>Depending on the platform, the method may return without |
| * effecting the opaque property of the window if the window has a non-null |
| * warning string ({@link Window#getWarningString()}). In this case |
| * the passed 'isOpaque' value is ignored. |
| * |
| * @param window the window to set the shape to |
| * @param isOpaque whether the window must be opaque (true), |
| * or translucent (false) |
| * @throws NullPointerException if the window argument is null |
| * @throws IllegalArgumentException if the window uses |
| * a GraphicsConfiguration for which the |
| * {@code isTranslucencyCapable()} |
| * method returns false |
| * @throws IllegalArgumentException if the window is in full screen mode, |
| * and the isOpaque is false |
| * @throws IllegalArgumentException if the window is decorated and the |
| * isOpaque argument is {@code false}. |
| * @throws UnsupportedOperationException if the PERPIXEL_TRANSLUCENT |
| * translucency kind is not supported |
| */ |
| public static void setWindowOpaque(Window window, boolean isOpaque) { |
| if (window == null) { |
| throw new NullPointerException( |
| "The window argument should not be null."); |
| } |
| if (!isOpaque && !isTranslucencySupported(Translucency.PERPIXEL_TRANSLUCENT)) { |
| throw new UnsupportedOperationException( |
| "The PERPIXEL_TRANSLUCENT translucency kind is not supported"); |
| } |
| AWTAccessor.getWindowAccessor().setOpaque(window, isOpaque); |
| } |
| |
| /** |
| * Returns whether the window is opaque or translucent. |
| * |
| * @param window the window to set the shape to |
| * @return whether the window is currently opaque (true) |
| * or translucent (false) |
| * @throws NullPointerException if the window argument is null |
| */ |
| public static boolean isWindowOpaque(Window window) { |
| if (window == null) { |
| throw new NullPointerException( |
| "The window argument should not be null."); |
| } |
| |
| return window.isOpaque(); |
| } |
| |
| /** |
| * Verifies whether a given GraphicsConfiguration supports |
| * the PERPIXEL_TRANSLUCENT kind of translucency. |
| * All windows that are intended to be used with the {@link #setWindowOpaque} |
| * method must be created using a GraphicsConfiguration for which this method |
| * returns true. |
| * <p>Note that some native systems enable the per-pixel translucency |
| * mode for any window created using a translucency-capable |
| * graphics configuration. However, it is highly recommended to always |
| * invoke the setWindowOpaque() method for these windows, at least |
| * for the sake of cross-platform compatibility reasons. |
| * |
| * @param gc GraphicsConfiguration |
| * @throws NullPointerException if the gc argument is null |
| * @return whether the given GraphicsConfiguration supports |
| * the translucency effects. |
| */ |
| public static boolean isTranslucencyCapable(GraphicsConfiguration gc) { |
| if (gc == null) { |
| throw new NullPointerException("The gc argument should not be null"); |
| } |
| /* |
| return gc.isTranslucencyCapable(); |
| */ |
| Toolkit curToolkit = Toolkit.getDefaultToolkit(); |
| if (!(curToolkit instanceof SunToolkit)) { |
| return false; |
| } |
| return ((SunToolkit)curToolkit).isTranslucencyCapable(gc); |
| } |
| |
| /** |
| * Sets a 'mixing-cutout' shape for the given component. |
| * |
| * By default a lightweight component is treated as an opaque rectangle for |
| * the purposes of the Heavyweight/Lightweight Components Mixing feature. |
| * This method enables developers to set an arbitrary shape to be cut out |
| * from heavyweight components positioned underneath the lightweight |
| * component in the z-order. |
| * <p> |
| * The {@code shape} argument may have the following values: |
| * <ul> |
| * <li>{@code null} - reverts the default cutout shape (the rectangle equal |
| * to the component's {@code getBounds()}) |
| * <li><i>empty-shape</i> - does not cut out anything from heavyweight |
| * components. This makes the given lightweight component effectively |
| * transparent. Note that descendants of the lightweight component still |
| * affect the shapes of heavyweight components. An example of an |
| * <i>empty-shape</i> is {@code new Rectangle()}. |
| * <li><i>non-empty-shape</i> - the given shape will be cut out from |
| * heavyweight components. |
| * </ul> |
| * <p> |
| * The most common example when the 'mixing-cutout' shape is needed is a |
| * glass pane component. The {@link JRootPane#setGlassPane()} method |
| * automatically sets the <i>empty-shape</i> as the 'mixing-cutout' shape |
| * for the given glass pane component. If a developer needs some other |
| * 'mixing-cutout' shape for the glass pane (which is rare), this must be |
| * changed manually after installing the glass pane to the root pane. |
| * <p> |
| * Note that the 'mixing-cutout' shape neither affects painting, nor the |
| * mouse events handling for the given component. It is used exclusively |
| * for the purposes of the Heavyweight/Lightweight Components Mixing |
| * feature. |
| * |
| * @param component the component that needs non-default |
| * 'mixing-cutout' shape |
| * @param shape the new 'mixing-cutout' shape |
| * @throws NullPointerException if the component argument is {@code null} |
| */ |
| public static void setComponentMixingCutoutShape(Component component, |
| Shape shape) |
| { |
| if (component == null) { |
| throw new NullPointerException( |
| "The component argument should not be null."); |
| } |
| |
| AWTAccessor.getComponentAccessor().setMixingCutoutShape(component, |
| shape); |
| } |
| } |
| |
