United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-6633275 Need to support shaped/translucent windows
JDK-6633275 : Need to support shaped/translucent windows

Details
Type:
Enhancement
Submit Date:
2007-11-22
Status:
Resolved
Updated Date:
2011-01-19
Project Name:
JDK
Resolved Date:
2008-02-14
Component:
client-libs
OS:
solaris_2.4,linux,generic,windows_xp,windows_95,windows_2000
Sub-Component:
java.awt
CPU:
x86,sparc,generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
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
Fixed Versions:
6u10 (b12)

Related Reports
Backport:
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:

Sub Tasks

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

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.
                                     
2007-11-22
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.
                                     
2007-11-23
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.
                                     
2008-01-23
EVALUATION

The feature and the API are described in details at:

http://java.sun.com/developer/technicalArticles/GUI/translucent_shaped_windows/
                                     
2009-09-22



Hardware and Software, Engineered to Work Together