8164899: Provide package access to setComponentMixingCutoutShape
authorprr
Tue, 06 Sep 2016 11:08:59 -0700
changeset 41004 01e8aabf5e7c
parent 41003 054df19db18c
child 41005 75033e345d45
8164899: Provide package access to setComponentMixingCutoutShape Reviewed-by: serb
jdk/src/java.desktop/share/classes/com/sun/awt/AWTUtilities.java
jdk/src/java.desktop/share/classes/java/awt/Component.java
--- a/jdk/src/java.desktop/share/classes/com/sun/awt/AWTUtilities.java	Tue Sep 06 08:32:50 2016 -0700
+++ b/jdk/src/java.desktop/share/classes/com/sun/awt/AWTUtilities.java	Tue Sep 06 11:08:59 2016 -0700
@@ -447,6 +447,7 @@
      * @param shape the new 'mixing-cutout' shape
      * @throws NullPointerException if the component argument is {@code null}
      */
+    @Deprecated(since = "9")
     public static void setComponentMixingCutoutShape(Component component,
             Shape shape)
     {
--- a/jdk/src/java.desktop/share/classes/java/awt/Component.java	Tue Sep 06 08:32:50 2016 -0700
+++ b/jdk/src/java.desktop/share/classes/java/awt/Component.java	Tue Sep 06 11:08:59 2016 -0700
@@ -843,32 +843,7 @@
                 return new Rectangle(comp.x, comp.y, comp.width, comp.height);
             }
             public void setMixingCutoutShape(Component comp, Shape shape) {
-                Region region = shape == null ?  null :
-                    Region.getInstance(shape, null);
-
-                synchronized (comp.getTreeLock()) {
-                    boolean needShowing = false;
-                    boolean needHiding = false;
-
-                    if (!comp.isNonOpaqueForMixing()) {
-                        needHiding = true;
-                    }
-
-                    comp.mixingCutoutRegion = region;
-
-                    if (!comp.isNonOpaqueForMixing()) {
-                        needShowing = true;
-                    }
-
-                    if (comp.isMixingNeeded()) {
-                        if (needHiding) {
-                            comp.mixOnHiding(comp.isLightweight());
-                        }
-                        if (needShowing) {
-                            comp.mixOnShowing();
-                        }
-                    }
-                }
+                comp.setMixingCutoutShape(shape);
             }
 
             public void setGraphicsConfiguration(Component comp,
@@ -10238,6 +10213,71 @@
         return true;
     }
 
+    /**
+     * 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.
+     * <p>
+     * The {@code shape} argument may have the following values:
+     * <ul>
+     * <li>{@code null} - reverts the default cutout shape (the rectangle equal
+     * to the component's {@code getBounds()})
+     * <li><i>empty-shape</i> - 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
+     * <i>empty-shape</i> is {@code new Rectangle()}.
+     * <li><i>non-empty-shape</i> - the given shape will be cut out from
+     * heavyweight components.
+     * </ul>
+     * <p>
+     * The most common example when the 'mixing-cutout' shape is needed is a
+     * glass pane component. The {@link JRootPane#setGlassPane()} method
+     * automatically sets the <i>empty-shape</i> 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.
+     * <p>
+     * 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.
+     *
+     * @param shape the new 'mixing-cutout' shape
+     * @since 9
+     */
+    void setMixingCutoutShape(Shape shape) {
+        Region region = shape == null ? null : Region.getInstance(shape, null);
+
+        synchronized (getTreeLock()) {
+            boolean needShowing = false;
+            boolean needHiding = false;
+
+            if (!isNonOpaqueForMixing()) {
+                needHiding = true;
+            }
+
+            mixingCutoutRegion = region;
+
+            if (!isNonOpaqueForMixing()) {
+                needShowing = true;
+            }
+
+            if (isMixingNeeded()) {
+                if (needHiding) {
+                    mixOnHiding(isLightweight());
+                }
+                if (needShowing) {
+                    mixOnShowing();
+                }
+            }
+        }
+    }
+
     // ****************** END OF MIXING CODE ********************************
 
     // Note that the method is overriden in the Window class,