1 /*
2 * Copyright (c) 2008, 2009, 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 com.sun.awt;
27
28 import java.awt.*;
29
30 import sun.awt.AWTAccessor;
31 import sun.awt.SunToolkit;
32
33 /**
34 * A collection of utility methods for AWT.
35 *
36 * The functionality provided by the static methods of the class includes:
37 * <ul>
38 * <li>Setting shapes on top-level windows
39 * <li>Setting a constant alpha value for each pixel of a top-level window
40 * <li>Making a window non-opaque, after that it paints only explicitly
41 * painted pixels on the screen, with arbitrary alpha values for every pixel.
42 * <li>Setting a 'mixing-cutout' shape for a component.
43 * </ul>
44 * <p>
45 * A "top-level window" is an instance of the {@code Window} class (or its
46 * descendant, such as {@code JFrame}).
47 * <p>
48 * Some of the mentioned features may not be supported by the native platform.
49 * To determine whether a particular feature is supported, the user must use
306 * the drawing sub-system is starting to respect the alpha value of each
307 * separate pixel. If a pixel gets painted with alpha color component
308 * equal to zero, it becomes visually transparent, if the alpha of the
309 * pixel is equal to 255, the pixel is fully opaque. Interim values
310 * of the alpha color component make the pixel semi-transparent (i.e.
311 * translucent).
312 * <p>Note that in order for the window to support the per-pixel alpha
313 * mode, the window must be created using the GraphicsConfiguration
314 * for which the {@link #isTranslucencyCapable}
315 * method returns true.
316 * <p>Also note that some native systems enable the per-pixel translucency
317 * mode for any window created using the translucency-compatible
318 * graphics configuration. However, it is highly recommended to always
319 * invoke the setWindowOpaque() method for these windows, at least for
320 * the sake of cross-platform compatibility reasons.
321 * <p>Also note that the window must not be in the full-screen mode
322 * when making it non-opaque. Otherwise the IllegalArgumentException
323 * is thrown.
324 * <p>If the window is a {@code Frame} or a {@code Dialog}, the window must
325 * be undecorated prior to enabling the per-pixel translucency effect (see
326 * {@link Frame#setUndecorated()} and/or {@link Dialog#setUndecorated()}).
327 * If the window becomes decorated through a subsequent call to the
328 * corresponding {@code setUndecorated()} method, the per-pixel
329 * translucency effect will be disabled and the opaque property reset to
330 * {@code true}.
331 * <p>Depending on the platform, the method may return without
332 * effecting the opaque property of the window if the window has a non-null
333 * warning string ({@link Window#getWarningString()}). In this case
334 * the passed 'isOpaque' value is ignored.
335 *
336 * @param window the window to set the shape to
337 * @param isOpaque whether the window must be opaque (true),
338 * or translucent (false)
339 * @throws NullPointerException if the window argument is null
340 * @throws IllegalArgumentException if the window uses
341 * a GraphicsConfiguration for which the
342 * {@code isTranslucencyCapable()}
343 * method returns false
344 * @throws IllegalArgumentException if the window is in full screen mode,
345 * and the isOpaque is false
346 * @throws IllegalArgumentException if the window is decorated and the
414 * By default a lightweight component is treated as an opaque rectangle for
415 * the purposes of the Heavyweight/Lightweight Components Mixing feature.
416 * This method enables developers to set an arbitrary shape to be cut out
417 * from heavyweight components positioned underneath the lightweight
418 * component in the z-order.
419 * <p>
420 * The {@code shape} argument may have the following values:
421 * <ul>
422 * <li>{@code null} - reverts the default cutout shape (the rectangle equal
423 * to the component's {@code getBounds()})
424 * <li><i>empty-shape</i> - does not cut out anything from heavyweight
425 * components. This makes the given lightweight component effectively
426 * transparent. Note that descendants of the lightweight component still
427 * affect the shapes of heavyweight components. An example of an
428 * <i>empty-shape</i> is {@code new Rectangle()}.
429 * <li><i>non-empty-shape</i> - the given shape will be cut out from
430 * heavyweight components.
431 * </ul>
432 * <p>
433 * The most common example when the 'mixing-cutout' shape is needed is a
434 * glass pane component. The {@link JRootPane#setGlassPane()} method
435 * automatically sets the <i>empty-shape</i> as the 'mixing-cutout' shape
436 * for the given glass pane component. If a developer needs some other
437 * 'mixing-cutout' shape for the glass pane (which is rare), this must be
438 * changed manually after installing the glass pane to the root pane.
439 * <p>
440 * Note that the 'mixing-cutout' shape neither affects painting, nor the
441 * mouse events handling for the given component. It is used exclusively
442 * for the purposes of the Heavyweight/Lightweight Components Mixing
443 * feature.
444 *
445 * @param component the component that needs non-default
446 * 'mixing-cutout' shape
447 * @param shape the new 'mixing-cutout' shape
448 * @throws NullPointerException if the component argument is {@code null}
449 */
450 @Deprecated(since = "9")
451 public static void setComponentMixingCutoutShape(Component component,
452 Shape shape)
453 {
454 if (component == null) {
|
1 /*
2 * Copyright (c) 2008, 2017, 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 com.sun.awt;
27
28 import java.awt.*;
29
30 import javax.swing.JRootPane;
31
32 import sun.awt.AWTAccessor;
33 import sun.awt.SunToolkit;
34
35 /**
36 * A collection of utility methods for AWT.
37 *
38 * The functionality provided by the static methods of the class includes:
39 * <ul>
40 * <li>Setting shapes on top-level windows
41 * <li>Setting a constant alpha value for each pixel of a top-level window
42 * <li>Making a window non-opaque, after that it paints only explicitly
43 * painted pixels on the screen, with arbitrary alpha values for every pixel.
44 * <li>Setting a 'mixing-cutout' shape for a component.
45 * </ul>
46 * <p>
47 * A "top-level window" is an instance of the {@code Window} class (or its
48 * descendant, such as {@code JFrame}).
49 * <p>
50 * Some of the mentioned features may not be supported by the native platform.
51 * To determine whether a particular feature is supported, the user must use
308 * the drawing sub-system is starting to respect the alpha value of each
309 * separate pixel. If a pixel gets painted with alpha color component
310 * equal to zero, it becomes visually transparent, if the alpha of the
311 * pixel is equal to 255, the pixel is fully opaque. Interim values
312 * of the alpha color component make the pixel semi-transparent (i.e.
313 * translucent).
314 * <p>Note that in order for the window to support the per-pixel alpha
315 * mode, the window must be created using the GraphicsConfiguration
316 * for which the {@link #isTranslucencyCapable}
317 * method returns true.
318 * <p>Also note that some native systems enable the per-pixel translucency
319 * mode for any window created using the translucency-compatible
320 * graphics configuration. However, it is highly recommended to always
321 * invoke the setWindowOpaque() method for these windows, at least for
322 * the sake of cross-platform compatibility reasons.
323 * <p>Also note that the window must not be in the full-screen mode
324 * when making it non-opaque. Otherwise the IllegalArgumentException
325 * is thrown.
326 * <p>If the window is a {@code Frame} or a {@code Dialog}, the window must
327 * be undecorated prior to enabling the per-pixel translucency effect (see
328 * {@link Frame#setUndecorated} and/or {@link Dialog#setUndecorated}).
329 * If the window becomes decorated through a subsequent call to the
330 * corresponding {@code setUndecorated()} method, the per-pixel
331 * translucency effect will be disabled and the opaque property reset to
332 * {@code true}.
333 * <p>Depending on the platform, the method may return without
334 * effecting the opaque property of the window if the window has a non-null
335 * warning string ({@link Window#getWarningString()}). In this case
336 * the passed 'isOpaque' value is ignored.
337 *
338 * @param window the window to set the shape to
339 * @param isOpaque whether the window must be opaque (true),
340 * or translucent (false)
341 * @throws NullPointerException if the window argument is null
342 * @throws IllegalArgumentException if the window uses
343 * a GraphicsConfiguration for which the
344 * {@code isTranslucencyCapable()}
345 * method returns false
346 * @throws IllegalArgumentException if the window is in full screen mode,
347 * and the isOpaque is false
348 * @throws IllegalArgumentException if the window is decorated and the
416 * By default a lightweight component is treated as an opaque rectangle for
417 * the purposes of the Heavyweight/Lightweight Components Mixing feature.
418 * This method enables developers to set an arbitrary shape to be cut out
419 * from heavyweight components positioned underneath the lightweight
420 * component in the z-order.
421 * <p>
422 * The {@code shape} argument may have the following values:
423 * <ul>
424 * <li>{@code null} - reverts the default cutout shape (the rectangle equal
425 * to the component's {@code getBounds()})
426 * <li><i>empty-shape</i> - does not cut out anything from heavyweight
427 * components. This makes the given lightweight component effectively
428 * transparent. Note that descendants of the lightweight component still
429 * affect the shapes of heavyweight components. An example of an
430 * <i>empty-shape</i> is {@code new Rectangle()}.
431 * <li><i>non-empty-shape</i> - the given shape will be cut out from
432 * heavyweight components.
433 * </ul>
434 * <p>
435 * The most common example when the 'mixing-cutout' shape is needed is a
436 * glass pane component. The {@link JRootPane#setGlassPane} method
437 * automatically sets the <i>empty-shape</i> as the 'mixing-cutout' shape
438 * for the given glass pane component. If a developer needs some other
439 * 'mixing-cutout' shape for the glass pane (which is rare), this must be
440 * changed manually after installing the glass pane to the root pane.
441 * <p>
442 * Note that the 'mixing-cutout' shape neither affects painting, nor the
443 * mouse events handling for the given component. It is used exclusively
444 * for the purposes of the Heavyweight/Lightweight Components Mixing
445 * feature.
446 *
447 * @param component the component that needs non-default
448 * 'mixing-cutout' shape
449 * @param shape the new 'mixing-cutout' shape
450 * @throws NullPointerException if the component argument is {@code null}
451 */
452 @Deprecated(since = "9")
453 public static void setComponentMixingCutoutShape(Component component,
454 Shape shape)
455 {
456 if (component == null) {
|