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 }