6993784: Clarification to shaped/translucent windows specification is required

Reviewed-by: anthony, dcherepanov

src/share/classes/java/awt/Dialog.java

@@ -1248,14 +1248,31 @@ public class Dialog extends Window {
 
     /**
      * Disables or enables decorations for this dialog.
-     * This method can only be called while the dialog is not displayable.
-     * @param  undecorated <code>true</code> if no dialog decorations are
-     *         to be enabled;
-     *         <code>false</code> if dialog decorations are to be enabled.
-     * @throws <code>IllegalComponentStateException</code> if the dialog
-     *         is displayable.
+     * <p>
+     * This method can only be called while the dialog is not displayable. To
+     * make this dialog decorated, it must be opaque and have the default shape,
+     * otherwise the {@code IllegalComponentStateException} will be thrown.
+     * Refer to {@link Window#setShape}, {@link Window#setOpacity} and {@link
+     * Window#setBackground} for details
+     *
+     * @param  undecorated {@code true} if no dialog decorations are to be
+     *         enabled; {@code false} if dialog decorations are to be enabled
+     *
+     * @throws IllegalComponentStateException if the dialog is displayable
+     * @throws IllegalComponentStateException if {@code undecorated} is
+     *      {@code false}, and this dialog does not have the default shape
+     * @throws IllegalComponentStateException if {@code undecorated} is
+     *      {@code false}, and this dialog opacity is less than {@code 1.0f}
+     * @throws IllegalComponentStateException if {@code undecorated} is
+     *      {@code false}, and the alpha value of this dialog background
+     *      color is less than {@code 1.0f}
+     *
      * @see    #isUndecorated
      * @see    Component#isDisplayable
+     * @see    Window#getShape
+     * @see    Window#getOpacity
+     * @see    Window#getBackground
+     *
      * @since 1.4
      */
     public void setUndecorated(boolean undecorated) {
@@ -1264,6 +1281,18 @@ public class Dialog extends Window {
             if (isDisplayable()) {
                 throw new IllegalComponentStateException("The dialog is displayable.");
             }
+            if (!undecorated) {
+                if (getOpacity() < 1.0f) {
+                    throw new IllegalComponentStateException("The dialog is not opaque");
+                }
+                if (getShape() != null) {
+                    throw new IllegalComponentStateException("The dialog does not have a default shape");
+                }
+                Color bg = getBackground();
+                if ((bg != null) && (bg.getAlpha() < 255)) {
+                    throw new IllegalComponentStateException("The dialog background color is not opaque");
+                }
+            }
             this.undecorated = undecorated;
         }
     }
@@ -1280,6 +1309,45 @@ public class Dialog extends Window {
         return undecorated;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setOpacity(float opacity) {
+        synchronized (getTreeLock()) {
+            if ((opacity < 1.0f) && !isUndecorated()) {
+                throw new IllegalComponentStateException("The dialog is decorated");
+            }
+            super.setOpacity(opacity);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setShape(Shape shape) {
+        synchronized (getTreeLock()) {
+            if ((shape != null) && !isUndecorated()) {
+                throw new IllegalComponentStateException("The dialog is decorated");
+            }
+            super.setShape(shape);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setBackground(Color bgColor) {
+        synchronized (getTreeLock()) {
+            if ((bgColor != null) && (bgColor.getAlpha() < 255) && !isUndecorated()) {
+                throw new IllegalComponentStateException("The dialog is decorated");
+            }
+            super.setBackground(bgColor);
+        }
+    }
+
     /**
      * Returns a string representing the state of this dialog. This
      * method is intended to be used only for debugging purposes, and the

src/share/classes/java/awt/Frame.java

@@ -879,15 +879,32 @@ public class Frame extends Window implements MenuContainer {
 
     /**
      * Disables or enables decorations for this frame.
-     * This method can only be called while the frame is not displayable.
-     * @param  undecorated <code>true</code> if no frame decorations are
-     *         to be enabled;
-     *         <code>false</code> if frame decorations are to be enabled.
-     * @throws <code>IllegalComponentStateException</code> if the frame
-     *         is displayable.
+     * <p>
+     * This method can only be called while the frame is not displayable. To
+     * make this frame decorated, it must be opaque and have the default shape,
+     * otherwise the {@code IllegalComponentStateException} will be thrown.
+     * Refer to {@link Window#setShape}, {@link Window#setOpacity} and {@link
+     * Window#setBackground} for details
+     *
+     * @param  undecorated {@code true} if no frame decorations are to be
+     *         enabled; {@code false} if frame decorations are to be enabled
+     *
+     * @throws IllegalComponentStateException if the frame is displayable
+     * @throws IllegalComponentStateException if {@code undecorated} is
+     *      {@code false}, and this frame does not have the default shape
+     * @throws IllegalComponentStateException if {@code undecorated} is
+     *      {@code false}, and this frame opacity is less than {@code 1.0f}
+     * @throws IllegalComponentStateException if {@code undecorated} is
+     *      {@code false}, and the alpha value of this frame background
+     *      color is less than {@code 1.0f}
+     *
      * @see    #isUndecorated
      * @see    Component#isDisplayable
+     * @see    Window#getShape
+     * @see    Window#getOpacity
+     * @see    Window#getBackground
      * @see    javax.swing.JFrame#setDefaultLookAndFeelDecorated(boolean)
+     *
      * @since 1.4
      */
     public void setUndecorated(boolean undecorated) {
@@ -896,6 +913,18 @@ public class Frame extends Window implements MenuContainer {
             if (isDisplayable()) {
                 throw new IllegalComponentStateException("The frame is displayable.");
             }
+            if (!undecorated) {
+                if (getOpacity() < 1.0f) {
+                    throw new IllegalComponentStateException("The frame is not opaque");
+                }
+                if (getShape() != null) {
+                    throw new IllegalComponentStateException("The frame does not have a default shape");
+                }
+                Color bg = getBackground();
+                if ((bg != null) && (bg.getAlpha() < 255)) {
+                    throw new IllegalComponentStateException("The frame background color is not opaque");
+                }
+            }
             this.undecorated = undecorated;
         }
     }
@@ -912,6 +941,45 @@ public class Frame extends Window implements MenuContainer {
         return undecorated;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setOpacity(float opacity) {
+        synchronized (getTreeLock()) {
+            if ((opacity < 1.0f) && !isUndecorated()) {
+                throw new IllegalComponentStateException("The frame is decorated");
+            }
+            super.setOpacity(opacity);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setShape(Shape shape) {
+        synchronized (getTreeLock()) {
+            if ((shape != null) && !isUndecorated()) {
+                throw new IllegalComponentStateException("The frame is decorated");
+            }
+            super.setShape(shape);
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setBackground(Color bgColor) {
+        synchronized (getTreeLock()) {
+            if ((bgColor != null) && (bgColor.getAlpha() < 255) && !isUndecorated()) {
+                throw new IllegalComponentStateException("The frame is decorated");
+            }
+            super.setBackground(bgColor);
+        }
+    }
+
     /**
      * Removes the specified menu bar from this frame.
      * @param    m   the menu component to remove.

src/share/classes/java/awt/Window.java

@@ -3474,14 +3474,20 @@ public class Window extends Container implements Accessible {
      * 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 translucency effect, the {@link
-     * GraphicsDevice#isWindowTranslucencySupported(GraphicsDevice.WindowTranslucency)} method must indicate that
-     * the {@link GraphicsDevice.WindowTranslucency#TRANSLUCENT TRANSLUCENT}
-     * translucency is supported.
+     * The following conditions must be met in order to set the opacity value
+     * less than {@code 1.0f}:
+     * <ul>
+     * <li>The {@link GraphicsDevice.WindowTranslucency#TRANSLUCENT TRANSLUCENT}
+     * translucency must be supported by the underlying system
+     * <li>The window must be undecorated (see {@link Frame#setUndecorated}
+     * and {@link Dialog#setUndecorated})
+     * <li>The window must not be in full-screen mode (see {@link
+     * GraphicsDevice#setFullScreenWindow(Window)})
+     * </ul>
      * <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.
+     * If the requested opacity value is less than {@code 1.0f}, and any of the
+     * above conditions are not met, the window opacity will not change,
+     * and the {@code IllegalComponentStateException} will be thrown.
      * <p>
      * The translucency levels of individual pixels may also be effected by the
      * alpha component of their color (see {@link Window#setBackground(Color)}) and the
@@ -3491,15 +3497,20 @@ public class Window extends Container implements Accessible {
      *
      * @throws IllegalArgumentException if the opacity is out of the range
      *     [0..1]
+     * @throws IllegalComponentStateException if the window is decorated and
+     *     the opacity is less than {@code 1.0f}
      * @throws IllegalComponentStateException if the window is in full screen
-     *     mode, and the opacity is less than 1.0f
+     *     mode, and the opacity is less than {@code 1.0f}
      * @throws UnsupportedOperationException if the {@code
      *     GraphicsDevice.WindowTranslucency#TRANSLUCENT TRANSLUCENT}
-     *     translucency kind is not supported and the opacity is less than 1.0f
+     *     translucency is not supported and the opacity is less than
+     *     {@code 1.0f}
      *
      * @see Window#getOpacity
      * @see Window#setBackground(Color)
      * @see Window#setShape(Shape)
+     * @see Frame#isUndecorated
+     * @see Dialog#isUndecorated
      * @see GraphicsDevice.WindowTranslucency
      * @see GraphicsDevice#isWindowTranslucencySupported(GraphicsDevice.WindowTranslucency)
      *
@@ -3557,24 +3568,26 @@ public class Window extends Container implements Accessible {
     /**
      * 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.)
+     * Setting a shape cuts off some parts of the window. Only the parts that
+     * belong to the given {@link Shape} remain visible and clickable. If
+     * the shape argument is {@code null}, this method 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:
+     * The following conditions must be met to set a non-null shape:
      * <ul>
      * <li>The {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSPARENT
-     * PERPIXEL_TRANSPARENT} translucency kind must be supported by the
+     * PERPIXEL_TRANSPARENT} translucency must be supported by the
      * underlying system
-     * <i>and</i>
-     * <li>The window must not be in the full-screen mode (see
-     * {@link GraphicsDevice#setFullScreenWindow(Window)})
+     * <li>The window must be undecorated (see {@link Frame#setUndecorated}
+     * and {@link Dialog#setUndecorated})
+     * <li>The window must not be in full-screen mode (see {@link
+     * GraphicsDevice#setFullScreenWindow(Window)})
      * </ul>
-     * If a certain condition is not met, either the {@code
-     * UnsupportedOperationException} or {@code IllegalComponentStateException}
-     * is thrown.
+     * <p>
+     * If the requested shape is not {@code null}, and any of the above
+     * conditions are not met, the shape of this window will not change,
+     * and either the {@code UnsupportedOperationException} or {@code
+     * IllegalComponentStateException} will be thrown.
      * <p>
      * The tranlucency levels of individual pixels may also be effected by the
      * alpha component of their color (see {@link Window#setBackground(Color)}) and the
@@ -3584,6 +3597,8 @@ public class Window extends Container implements Accessible {
      * @param shape the shape to set to the window
      *
      * @throws IllegalComponentStateException if the shape is not {@code
+     *     null} and the window is decorated
+     * @throws IllegalComponentStateException if the shape is not {@code
      *     null} and the window is in full-screen mode
      * @throws UnsupportedOperationException if the shape is not {@code
      *     null} and {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSPARENT
@@ -3592,6 +3607,8 @@ public class Window extends Container implements Accessible {
      * @see Window#getShape()
      * @see Window#setBackground(Color)
      * @see Window#setOpacity(float)
+     * @see Frame#isUndecorated
+     * @see Dialog#isUndecorated
      * @see GraphicsDevice.WindowTranslucency
      * @see GraphicsDevice#isWindowTranslucencySupported(GraphicsDevice.WindowTranslucency)
      *
@@ -3645,37 +3662,46 @@ public class Window extends Container implements Accessible {
      * GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT PERPIXEL_TRANSLUCENT}
      * tranclucency, 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 translucent
-     * (alpha &lt; 1.0f).  All the following conditions must be met in order
-     * to be able to enable the per-pixel transparency mode for this window:
+     * this window must be opaque (alpha equals {@code 1.0f}) or per-pixel translucent
+     * (alpha is less than {@code 1.0f}). If the given background color is
+     * {@code null}, the window is considered completely opaque.
+     * <p>
+     * All the following conditions must be met to enable the per-pixel
+     * transparency mode for this window:
      * <ul>
      * <li>The {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT
-     * PERPIXEL_TRANSLUCENT} translucency 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
+     * PERPIXEL_TRANSLUCENT} translucency must be supported by the graphics
+     * device where this window is located
+     * <li>The window must be undecorated (see {@link Frame#setUndecorated}
+     * and {@link Dialog#setUndecorated})
+     * <li>The window must not be in full-screen mode (see {@link
      * GraphicsDevice#setFullScreenWindow(Window)})
      * </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>
+     * If the alpha component of the requested background color is less than
+     * {@code 1.0f}, and any of the above conditions are not met, the background
+     * color of this window will not change, the alpha component of the given
+     * background color will not affect the mode of operation for this window,
+     * and either the {@code UnsupportedOperationException} or {@code
+     * IllegalComponentStateException} will be thrown.
      * <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
+     * 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.)
+     * the pixel semi-transparent. In this mode, the background of the window
+     * gets painted with the alpha value of the given background color. If the
+     * alpha value of the argument of this method is equal to {@code 0}, the
+     * background is not painted at all.
      * <p>
      * The actual level of translucency of a given pixel also depends on window
      * opacity (see {@link #setOpacity(float)}), as well as the current shape of
      * this window (see {@link #setShape(Shape)}).
      * <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
+     * Note that painting a pixel with the alpha value of {@code 0} may or may
+     * not disable the mouse event handling on this pixel. This is a
+     * platform-dependent behavior. To make sure the mouse events do not get
      * dispatched to a particular pixel, the pixel must be excluded from the
      * shape of the window.
      * <p>
@@ -3685,17 +3711,21 @@ public class Window extends Container implements Accessible {
      * @param bgColor the color to become this window's background color.
      *
      * @throws IllegalComponentStateException if the alpha value of the given
-     *     background color is less than 1.0f and the window is in
+     *     background color is less than {@code 1.0f} and the window is decorated
+     * @throws IllegalComponentStateException if the alpha value of the given
+     *     background color is less than {@code 1.0f} and the window is in
      *     full-screen mode
      * @throws UnsupportedOperationException if the alpha value of the given
-     *     background color is less than 1.0f and
-     *     {@link GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT
+     *     background color is less than {@code 1.0f} and {@link
+     *     GraphicsDevice.WindowTranslucency#PERPIXEL_TRANSLUCENT
      *     PERPIXEL_TRANSLUCENT} translucency is not supported
      *
      * @see Window#getBackground
      * @see Window#isOpaque
      * @see Window#setOpacity(float)
      * @see Window#setShape(Shape)
+     * @see Frame#isUndecorated
+     * @see Dialog#isUndecorated
      * @see GraphicsDevice.WindowTranslucency
      * @see GraphicsDevice#isWindowTranslucencySupported(GraphicsDevice.WindowTranslucency)
      * @see GraphicsConfiguration#isTranslucencyCapable()
@@ -3739,7 +3769,7 @@ public class Window extends Container implements Accessible {
      * <p>
      * The method returns {@code false} if the background color of the window
      * is not {@code null} and the alpha component of the color is less than
-     * 1.0f. The method returns {@code true} otherwise.
+     * {@code 1.0f}. The method returns {@code true} otherwise.
      *
      * @return {@code true} if the window is opaque, {@code false} otherwise
      *