JDK-6633275 : Need to support shaped/translucent windows
  • Type: Enhancement
  • Component: client-libs
  • Sub-Component: java.awt
  • Affected Version:
    1.0,1.1,1.1.3,1.2.0,1.3.0,1.3.1,1.4.0,1.4.1,5.0,6,6u4,6u10 1.0,1.1,1.1.3,1.2.0,1.3.0,1.3.1,1.4.0,1.4.1,5.0,6,6u4,6u10
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS:
    generic,linux,solaris_2.4,windows_95,windows_2000,windows_xp generic,linux,solaris_2.4,windows_95,windows_2000,windows_xp
  • CPU: generic,x86,sparc
  • Submitted: 2007-11-22
  • Updated: 2017-05-16
  • Resolved: 2008-02-14
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 6 JDK 7
6u10 b12Fixed 7Fixed
Related Reports
Duplicate :  
Duplicate :  
Duplicate :  
Duplicate :  
Duplicate :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Description
The Consumer JRE should support shaped/translucent windows. The following API is proposed for this:

package com.sun.awt;

/**
 * <b>WARNING</b>: This class is an implementation detail and only meant
 * for use within the core platform. You should NOT depend upon it! This
 * API may change drastically between dot dot release, and it may even be
 * removed.
 */
public final class AWTUtilities {

    /** 
     * The AWTUtilities class should not be instantiated
     */
    private AWTUtilities() {
    }

    public static enum Translucency {
        /** 
         * Represents image data that is guaranteed to be completely opaque,
         * meaning that all pixels have an alpha value of 1.0.
         */
        OPAQUE,

        /**
         * Represents image data 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_OPAQUE,

        /**
         * Represents image data all of the pixels of which have the same alpha value
         * between or including 0.0 and 1.0.
         */
        TRANSLUCENT,

        /**
         * Represents image data that contains 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 current configuration.
     *
     * The translucencyKind argument is one of the OPAQUE, PERPIXEL_OPAQUE, 
     * TRANSLUCENT, or PERPIXEL_TRANSLUCENT constants. Passing any other value
     * (or any bitwise combination of the constants) results in
     * return value of false.
     *
     * The level of support depends on the capabilities of the native 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 OPAQUE, PERPIXEL_OPAQUE, 
     *                         TRANSLUCENT, or PERPIXEL_TRANSLUCENT)
     * @return whether the given translucency kind is supported
     * @throws IllegalArgumentException if the translucencyKind argument is not one of the defined constants.
     */
    public static boolean isTranslucencySupported(Translucency translucencyKind);


    /**
     * 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.
     *
     * @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 UnsupportedOperationException if the TRANSLUCENT translucency kind is not supported
     */
    public static void setWindowOpacity(Window window, float 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);

    /**
     * Returns the object implementing the Shape interface previously
     * set with the call to the setWindowShape() method.
     * If no shape has been set yet, this method returns null.
     * @param window the window to get the shape from
     * @throws NullPointerException if the window argument is null
     */
    public static Shape getWindowShape(Window window);

    /**
     * Sets a shape object 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.
     * @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 UnsupportedOperationException if the PERPIXEL_OPAQUE translucency kind is not supported
     */
    public static void setWindowShape(Window window, Shape shape);

    /**
     * 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
     * obtained with the {@link getTranslucencyCompatibleGraphicsConfiguration}
     * method. 
     * <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.
     * 
     * @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 other than returned by the getTranslucencyCompatibleGraphicsConfiguration() method.
     * @throws UnsupportedOperationException if the PERPIXEL_TRANSLUCENT translucency kind is not supported
     */
    public static void setWindowOpaque(Window window, boolean 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);

    /**
     * Returns a GraphicsConfigurations that are capable of displaying translucent windows.
     * All windows that are intended to be used with setWindowOpaque() method
     * must be created using one of the GraphicsConfiguration returned with this method.
     * <p>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.
     *
     * @return a GraphicsConfiguration capable of displaying translucent windows.
     */
    public static Set<GraphicsConfiguration> getTranslucencyCompatibleGraphicsConfigurations();
}

Comments
EVALUATION The feature and the API are described in details at: http://java.sun.com/developer/technicalArticles/GUI/translucent_shaped_windows/
22-09-2009

SUGGESTED FIX http://sa.sfbay.sun.com/projects/awt_data/6u10/6633275/ Also see the attached webrev.zip file. Note that this fix has a bug with File and Print system dialogs under MS Windows. This bug is fixed as CR 6648996.
23-01-2008

EVALUATION This also includes back porting of a number of Java2D fixes from the JDK7 source tree, notably: 6589865 and 6504874. It is decided to keep the whole fix under this CR, so these back ports are combined together.
23-11-2007

EVALUATION Native platform support: Shaped windows: * MS Windows: since Win95 * X11: since 1989 (the XSHAPE extenstion) Translucency: * MS Windows: since Window 2000 * X11: if running a composite (or compositing window-) manager (like Compiz) which supports (and reports as supported) the desired effects.
22-11-2007