1 /*
   2  * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.awt;
  27 
  28 import java.awt.Component;
  29 import java.awt.Shape;
  30 
  31 import com.sun.awt.AWTUtilities;
  32 
  33 /**
  34  * A class to allow access to JDK-specific utility methods.
  35  * Methods in this class are always deprecated since a caller
  36  * should be aware they may be removed and replaced in the future.
  37  * Access using reflection is highly recommended.
  38  * @since 9
  39  */
  40 public final class AWTUtils {
  41 
  42     /**
  43      * No-one should be creating instances of this class.
  44      */
  45     private AWTUtils() {
  46     }
  47 
  48     /**
  49      * Sets a 'mixing-cutout' shape for the given component.
  50      *
  51      * By default a lightweight component is treated as an opaque rectangle for
  52      * the purposes of the Heavyweight/Lightweight Components Mixing feature.
  53      * This method enables developers to set an arbitrary shape to be cut out
  54      * from heavyweight components positioned underneath the lightweight
  55      * component in the z-order.
  56      * <p>
  57      * The {@code shape} argument may have the following values:
  58      * <ul>
  59      * <li>{@code null} - reverts the default cutout shape (the rectangle equal
  60      * to the component's {@code getBounds()})
  61      * <li><i>empty-shape</i> - does not cut out anything from heavyweight
  62      * components. This makes the given lightweight component effectively
  63      * transparent. Note that descendants of the lightweight component still
  64      * affect the shapes of heavyweight components.  An example of an
  65      * <i>empty-shape</i> is {@code new Rectangle()}.
  66      * <li><i>non-empty-shape</i> - the given shape will be cut out from
  67      * heavyweight components.
  68      * </ul>
  69      * <p>
  70      * The most common example when the 'mixing-cutout' shape is needed is a
  71      * glass pane component. The {@link JRootPane#setGlassPane()} method
  72      * automatically sets the <i>empty-shape</i> as the 'mixing-cutout' shape
  73      * for the given glass pane component.  If a developer needs some other
  74      * 'mixing-cutout' shape for the glass pane (which is rare), this must be
  75      * changed manually after installing the glass pane to the root pane.
  76      * <p>
  77      * Note that the 'mixing-cutout' shape neither affects painting, nor the
  78      * mouse events handling for the given component. It is used exclusively
  79      * for the purposes of the Heavyweight/Lightweight Components Mixing
  80      * feature.
  81      *
  82      * @param component the component that needs non-default
  83      * 'mixing-cutout' shape
  84      * @param shape the new 'mixing-cutout' shape
  85      * @throws NullPointerException if the component argument is {@code null}
  86      * @deprecated This API may be removed or replaced.
  87      */
  88     @Deprecated
  89     @SuppressWarnings("deprecation")
  90     public static void setComponentMixingCutoutShape(Component component,
  91                                                      Shape shape) {
  92 
  93         AWTUtilities.setComponentMixingCutoutShape(component, shape);
  94     }
  95 }