Back to index...

	/*
	* 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);
	}
	}

Back to index...