com.sun.awt

Class AWTUtilities [ source ]

java.lang.Object

com.sun.awt.AWTUtilities

public final class AWTUtilities
extends Object

A collection of utility methods for AWT. The functionality provided by the static methods of the class includes:

• Setting shapes on top-level windows
• Setting a constant alpha value for each pixel of a top-level window
• Making a window non-opaque, after that it paints only explicitly painted pixels on the screen, with arbitrary alpha values for every pixel.
• Setting a 'mixing-cutout' shape for a component.

A "top-level window" is an instance of the Window class (or its descendant, such as JFrame).

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 isTranslucencySupported() method of the class passing a desired translucency kind (a member of the Translucency enum) as an argument.

The per-pixel alpha feature also requires the user to create her/his windows using a translucency-capable graphics configuration. The isTranslucencyCapable() method must be used to verify whether any given GraphicsConfiguration supports the trasnlcency effects.

WARNING: 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).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AWTUtilities.Translucency Kinds of translucency supported by the underlying system.

Method Summary

Methods

Modifier and Type	Method and Description
static float	getWindowOpacity(Window window) Get the opacity of the window.
static Shape	getWindowShape(Window window) Returns an object that implements the Shape interface and represents the shape previously set with the call to the setWindowShape() method.
static boolean	isTranslucencyCapable(GraphicsConfiguration gc) Verifies whether a given GraphicsConfiguration supports the PERPIXEL_TRANSLUCENT kind of translucency.
static boolean	isTranslucencySupported(AWTUtilities.Translucency translucencyKind) Returns whether the given level of translucency is supported by the underlying system.
static boolean	isWindowOpaque(Window window) Returns whether the window is opaque or translucent.
static void	setComponentMixingCutoutShape(Component component, Shape shape) Sets a 'mixing-cutout' shape for the given component.
static void	setWindowOpacity(Window window, float opacity) Set the opacity of the window.
static void	setWindowOpaque(Window window, boolean isOpaque) Enables the per-pixel alpha support for the given window.
static void	setWindowShape(Window window, Shape shape) Sets a shape for the given window.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isTranslucencySupported

public static boolean isTranslucencySupported(AWTUtilities.Translucency translucencyKind)

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).

Parameters:

translucencyKind - a kind of translucency support (either PERPIXEL_TRANSPARENT, TRANSLUCENT, or PERPIXEL_TRANSLUCENT)

Returns:

whether the given translucency kind is supported

setWindowOpacity

public static void setWindowOpacity(Window window,
                    float opacity)

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.

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.

Parameters:

window - the window to set the opacity level to

opacity - the opacity level to set to the window

Throws:

NullPointerException - if the window argument is null

IllegalArgumentException - if the opacity is out of the range [0..1]

IllegalArgumentException - if the window is in full screen mode, and the opacity is less than 1.0f

UnsupportedOperationException - if the TRANSLUCENT translucency kind is not supported

getWindowOpacity

public static float getWindowOpacity(Window window)

Get the opacity of the window. If the opacity has not yet being set, this method returns 1.0.

Parameters:

window - the window to get the opacity level from

Throws:

NullPointerException - if the window argument is null

getWindowShape

public static Shape getWindowShape(Window window)

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.

Parameters:

window - the window to get the shape from

Returns:

the current shape of the window

Throws:

NullPointerException - if the window argument is null

setWindowShape

public static void setWindowShape(Window window,
                  Shape shape)

Sets a shape for the given window. If the shape argument is null, this methods restores the default shape making the window rectangular.

Note that in order to set a shape, the window must be undecorated. If the window is decorated, this method ignores the shape argument and resets the shape to null.

Also note that the window must not be in the full-screen mode when setting a non-null shape. Otherwise the IllegalArgumentException is thrown.

Depending on the platform, the method may return without effecting the shape of the window if the window has a non-null warning string (Window.getWarningString()). In this case the passed shape object is ignored.

Parameters:

window - the window to set the shape to

shape - the shape to set to the window

Throws:

NullPointerException - if the window argument is null

IllegalArgumentException - if the window is in full screen mode, and the shape is not null

UnsupportedOperationException - if the PERPIXEL_TRANSPARENT translucency kind is not supported

setWindowOpaque

public static void setWindowOpaque(Window window,
                   boolean isOpaque)

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).

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 isTranslucencyCapable(java.awt.GraphicsConfiguration) method returns true.

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.

Also note that the window must not be in the full-screen mode when making it non-opaque. Otherwise the IllegalArgumentException is thrown.

If the window is a Frame or a Dialog, the window must be undecorated prior to enabling the per-pixel translucency effect (see Frame#setUndecorated() and/or Dialog#setUndecorated()). If the window becomes decorated through a subsequent call to the corresponding setUndecorated() method, the per-pixel translucency effect will be disabled and the opaque property reset to true.

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 (Window.getWarningString()). In this case the passed 'isOpaque' value is ignored.

Parameters:

window - the window to set the shape to

isOpaque - whether the window must be opaque (true), or translucent (false)

Throws:

NullPointerException - if the window argument is null

IllegalArgumentException - if the window uses a GraphicsConfiguration for which the isTranslucencyCapable() method returns false

IllegalArgumentException - if the window is in full screen mode, and the isOpaque is false

IllegalArgumentException - if the window is decorated and the isOpaque argument is false.

UnsupportedOperationException - if the PERPIXEL_TRANSLUCENT translucency kind is not supported

isWindowOpaque

public static boolean isWindowOpaque(Window window)

Returns whether the window is opaque or translucent.

Parameters:

window - the window to set the shape to

Returns:

whether the window is currently opaque (true) or translucent (false)

Throws:

NullPointerException - if the window argument is null

isTranslucencyCapable

public static boolean isTranslucencyCapable(GraphicsConfiguration gc)

Verifies whether a given GraphicsConfiguration supports the PERPIXEL_TRANSLUCENT kind of translucency. All windows that are intended to be used with the setWindowOpaque(java.awt.Window, boolean) method must be created using a GraphicsConfiguration for which this method returns true.

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.

Parameters:

gc - GraphicsConfiguration

Returns:

whether the given GraphicsConfiguration supports the translucency effects.

Throws:

NullPointerException - if the gc argument is null

setComponentMixingCutoutShape

public static void setComponentMixingCutoutShape(Component component,
                                 Shape shape)

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.

The shape argument may have the following values:

• null - reverts the default cutout shape (the rectangle equal to the component's getBounds())
• empty-shape - 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 empty-shape is new Rectangle().
• non-empty-shape - the given shape will be cut out from heavyweight components.

The most common example when the 'mixing-cutout' shape is needed is a glass pane component. The JRootPane#setGlassPane() method automatically sets the empty-shape 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.

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.

Parameters:

component - the component that needs non-default 'mixing-cutout' shape

shape - the new 'mixing-cutout' shape

Throws:

NullPointerException - if the component argument is null