JDK-6802853 : API: shaped & translucent windows
  • Type: Enhancement
  • Component: client-libs
  • Sub-Component: java.awt
  • Affected Version: 7
  • Priority: P4
  • Status: Closed
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2009-02-09
  • Updated: 2017-05-16
  • Resolved: 2011-03-07
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 7
7 b57Fixed
Related Reports
Relates :  
JDK-6837004 - java.awt.GraphicsDevice.setFullScreenWindow throws NPE for windows with background color not set
Relates :  
JDK-6812298 - Dynamic GraphicsConfig changes don't work on X11 platforms
Relates :  
JDK-6633275 - Need to support shaped/translucent windows
Relates :  
JDK-6877122 - Many javadoc warnings from java.awt.Window, other awt classes
Relates :  
JDK-5062995 - AWT needs to support Shaped windows and components.
Relates :  
JDK-4479178 - RFE: Support for Transparent windows required
Relates :  
JDK-2172125 - Need to support shaped/translucent windows
Description
CR 6633275 is a technical side of the new client Java feature: shaped & translucent windows. In 6u10 this feature was accessible via com.sun.awt.AWTUtilities class, however in JDK7 we need some public java.awt API for it.
Comments
EVALUATION Here are some related issues to be covered by this CR: 1. All the references to AWTUtilities in java.awt package must be converted to public analogues. 2. JavaDoc for GraphicsDevice.setFullScreenWindow() must be extended to iclude shaped/translucent windows. If a window has some effects applied on it, they are reset when making this window fullscreen. 3. Some of the effects for embedded frames are not applicable, so the corresponding public methods should be overridden to be no-op. 4. Mark 'opacity' and 'shape' fields in Window class with @serial. 5. Remove all 'setDoubleBuffered(isOpaque)' from Window.setLayersOpaque() as it is no longer required after recent changes in Swing. 6. Add a note to JavaDoc about possible changes to Window's GraphicsConfiguration (e.g. when it is moved to another screen or made translucent).
09-02-2009
SUGGESTED FIX /** * Kinds of window translucency supported by the underlying system. * <p> * If more than one kind of translucency is supported by the system then * several translucency mechanisms may be applied to a single window at * once. In this case the actual alpha value of each individual pixel will * be the product of the alpha values of all the applied mechanisms. * * @see #isWindowTranslucencySupported * @since 1.7 */ public static enum java.awt.GraphicsDevice.WindowTranslucency { /** * Represents support in the underlying system for windows where each * individual pixel in the window may be either completely transparent, * or completely opaque. */ PERPIXEL_TRANSPARENT, /** * Represents support in the underlying system for windows where all * pixels have the same alpha value, which may be any of the legal * range of alpha values from fully transparent, to fully opaque. */ TRANSLUCENT, /** * Represents support in the underlying system for windows that may * contain pixels with any of the legal range of alpha values from * fully transparent, to fully opaque. */ PERPIXEL_TRANSLUCENT; } /** * Returns whether the given level of translucency is supported * this graphics device. * * @param translucencyKind a kind of translucency support * @return whether the given translucency kind is supported * * @since 1.7 */ public boolean java.awt.GraphicsDevice.isWindowTranslucencySupported( WindowTranslucency kind); /** * Verifies whether this GraphicsConfiguration supports * the {@link GraphicsDevive.WindowTranslucency#PERPIXEL_TRANSLUCENT * PERPIXEL_TRANSLUCENT} kind of translucency. * * @return whether this graphics configuration supports the * translucency effects. * * @see GraphicsDevice.WindowTranslucency * @see Window#setBackground * * @since 1.7 */ public boolean java.awt.GraphicsConfiguration.isTranslucentCapable(); /** * Sets the background color of this window. * <p> * If the windowing system supports the {@link * GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSPARENT PERPIXEL_TRANSPARENT} * find of transparency the alpha component of the given background color * may effect the mode of operation for this window: it indicates whether * this window must be opaque (alpha == 1.0f) or per-pixel transparent * (alpha &lt; 1.0f). All the following conditions must be met at once in * order to be able to enable the per-pixel transparency mode for this window: * <ul> * <li>The {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT * PERPIXEL_TRANSLUCENT} translucency kind must be supported * by the graphics device where this window is located <i>and</i> * <li>The window must not be in the full-screen mode (see {@link * GraphicsDevice#setFullScreenWindow()}) * </ul> * If a certain condition is not met at the time of calling this method, * the alpha component of the given background color will not effect the * mode of operation for this window. * <p> * When the window is per-pixel translucent, the drawing sub-system * respects the alpha value of each individual pixel. If a pixel gets * painted with the alpha color component equal to zero, it becomes * visually transparent, if the alpha of the pixel is equal to 1.0f, the * pixel is fully opaque. Interim values of the alpha color component make * the pixel semi-transparent. In this mode the background of the window * gets painted with the alpha value of the given background color (meaning * that it is not painted at all if the alpha value of the argument of this * method is equal to zero.) * <p> * The actual level of translucency of a given pixel also depends on the * value set via the {@link setOpacity()} method, as well as the current * shape of this window set via the {@link setShape()} method. See {@link * GraphicsDevice#WindowTranslucency} for more details. * <p> * Note that painting a pixel with the alpha value of 0 may or may not * disable the mouse event handling on this pixel. This is a * platform-dependent behavior. To make sure the mouse clicks do not get * dispatched to a particular pixel, the pixel must be excluded from the * shape of the window (see {@link setShape()}). * <p> * Enabling the per-pixel translucency mode may change the graphics * configuration of this window due to the native platform requirements * (see {@link getGraphicsConfiguration()}.) * * @param c the color to become the background color of this window; * if this parameter is <code>null</code>, then this * component will inherit the background color of its parent * * @see #getBackground * @see GraphicsDevice.WindowTranslucency * @see GraphicsDevice#isWindowTranslucencySupported() * @see GraphicsConfiguration#isTranslucencyCapable() */ public void java.awt.Window.setBackground(Color c); /** * Gets the background color of this window. * <p> * Note that the alpha component of the returned color indicates whether * the window is in the non-opaque (per-pixel translucent) mode. See {@link * #setBackground()} for more details. * * @return this component's background color * * @see #setBackground * @see GraphicsDevice.WindowTranslucency */ public Color java.awt.Window.getBackground(); /** * Sets the opacity of the window. * <p> * The opacity value is in 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. * <p> * In order for this method to enable the transparency effect, the {@link * GraphicsDevice#isWindowTranslucencySupported()} method must indicate that * the {@link GraphicsDevice.WindowTranslucency#TRANSLUCENT TRANSLUCENT} * level of transparency is supported. * <p> * Also note that the window must not be in the full-screen mode when * setting the opacity value &lt; 1.0f. Otherwise the {@code * IllegalComponentStateException} is thrown. * <p> * The translucency levels of individual pixels may also be effected by the * alpha component of their color (see {@link setBackground()}) and the * current shape of this window set via the {@link setShape()} method. See * {@link GraphicsDevice#WindowTranslucency} for more details. * * @param opacity the opacity level to set to the window * * @throws IllegalArgumentException if the opacity is out of the range * [0..1] * @throws IllegalComponentStateException if the window is in full screen * mode, and the opacity is less than 1.0f * @throws UnsupportedOperationException if the {@code * GraphicsDevice.WindowTranslucency#TRANSLUCENT TRANSLUCENT} * translucency kind is not supported and the opacity is less than 1.0f * * @see #getOpacity * @see GraphicsDevice.WindowTranslucency * @since 1.7 */ public void java.awt.Window.setOpacity(float opacity); /** * Gets the opacity of the window. * <p> * If the opacity has not been set yet, this method returns 1.0f. * * @return the opacity of the window * * @see #setOpacity * @see GraphicsDevice.WindowTranslucency * @since 1.7 */ public float java.awt.Window.getOpacity(); /** * Sets the shape of the window. * <p> * Setting a shape enables cutting off some parts of the window, leaving * visible and clickable only those parts belonging to the given shape * (see {@link Shape}). If the shape argument is null, this methods * restores the default shape (making the window rectangular on most * platforms.) * <p> * The following conditions must be met in order to set a non-null shape: * <ul> * <li>The {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSPARENT * PERPIXEL_TRANSPARENT} translucency kind must be supported by the * underlying system (see {@link GraphicsDevice#isWindowTranslucencySupported()}) * <i>and</i> * <li>The window must not be in the full-screen mode (see * {@link GraphicsDevice#setFullScreenWindow()}) * </ul> * If a certain condition is not met, either the {@code * UnsupportedOperationException} or {@code IllegalComponentStateException} * is thrown. * <p> * The tranlucency levels of individual pixels may also be effected by the * alpha component of their color (see {@link setBackground()}) and the * opacity value set via the {@link setOpacity()} method. See {@link * GraphicsDevice#WindowTranslucency} for more details. * * @param shape the shape to set to the window * * @throws UnsupportedOperationException if the {@link * GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSPARENT PERPIXEL_TRANSPARENT} * translucency kind is not supported and the shape is not null * @throws IllegalComponentStateException if the window is in full-screen mode * * @see #getShape * @see GraphicsDevice.WindowTranslucency * @since 1.7 */ public void java.awt.Window.setShape(Shape shape); /** * Gets the shape of the window. * <p> * If no shape has been set yet, or the shape has been * reset to null, this method returns null. * * @return the shape of the window or null * * @see #setShape * @see GraphicsDevice.WindowTranslucency * @since 1.7 */ public Shape java.awt.Window.getShape();
09-02-2009