Home » openjdk-7 » com.sun » awt » [javadoc | source]
com.sun.awt
public final class: AWTUtilities [javadoc | source]
java.lang.Object
   com.sun.awt.AWTUtilities
A collection of utility methods for AWT. The functionality provided by the static methods of the class includes:

A "top-level window" is an instance of the {@code Window} class (or its descendant, such as {@code 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 {@code isTranslucencySupported()} method of the class passing a desired translucency kind (a member of the {@code 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 {@code 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:
public static enum class  AWTUtilities.Translucency  Kinds of translucency supported by the underlying system. 
Method from com.sun.awt.AWTUtilities Summary:
getWindowOpacity,   getWindowShape,   isTranslucencyCapable,   isTranslucencySupported,   isWindowOpaque,   isWindowShapingSupported,   setComponentMixingCutoutShape,   setWindowOpacity,   setWindowOpaque,   setWindowShape
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from com.sun.awt.AWTUtilities Detail:
 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.
 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.
 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 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.

 public static boolean isTranslucencySupported(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).
 public static boolean isWindowOpaque(Window window) 
    Returns whether the window is opaque or translucent.
 public static boolean isWindowShapingSupported() 
    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  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 {@code shape} argument may have the following values:

    • {@code null} - reverts the default cutout shape (the rectangle equal to the component's {@code 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 {@code 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.

 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.

 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 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 {@code Frame} or a {@code 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 {@code setUndecorated()} method, the per-pixel translucency effect will be disabled and the opaque property reset to {@code 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.

 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 {@code 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.