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 import java.awt.geom.*; 30 31 import sun.awt.AWTAccessor; 32 33 34 /** 35 * Security Warning control interface. 36 * 37 * This class provides a couple of methods that help a developer relocate 38 * the AWT security warning to an appropriate position relative to the current 39 * window size. A "top-level window" is an instance of the {@code Window} 40 * class (or its descendant, such as {@code JFrame}). The security warning 41 * is applied to all windows created by an untrusted code. All such windows 42 * have a non-null "warning string" (see {@link Window#getWarningString()}). 43 * <p> 44 * <b>WARNING</b>: This class is an implementation detail and only meant 45 * for limited use outside of the core platform. This API may change 46 * drastically between update release, and it may even be 47 * removed or be moved to some other packages or classes. 48 */ 49 public final class SecurityWarning { 50 51 /** 52 * The SecurityWarning class should not be instantiated 53 */ 54 private SecurityWarning() { 55 } 56 57 /** 58 * Gets the size of the security warning. 59 * 60 * The returned value is not valid until the peer has been created. Before 61 * invoking this method a developer must call the {@link Window#pack()}, 62 * {@link Window#setVisible()}, or some other method that creates the peer. 63 * 64 * @param window the window to get the security warning size for 65 * 66 * @throws NullPointerException if the window argument is null 67 * @throws IllegalArgumentException if the window is trusted (i.e. 68 * the {@code getWarningString()} returns null) 69 */ 70 public static Dimension getSize(Window window) { 71 if (window == null) { 72 throw new NullPointerException( 73 "The window argument should not be null."); 74 } 75 if (window.getWarningString() == null) { 76 throw new IllegalArgumentException( 77 "The window must have a non-null warning string."); 78 } 79 // We don't check for a non-null peer since it may be destroyed 80 // after assigning a valid value to the security warning size. 81 82 return AWTAccessor.getWindowAccessor().getSecurityWarningSize(window); 83 } 84 85 /** 86 * Sets the position of the security warning. 87 * <p> 88 * The {@code alignmentX} and {@code alignmentY} arguments specify the 89 * origin of the coordinate system used to calculate the position of the 90 * security warning. The values must be in the range [0.0f...1.0f]. The 91 * {@code 0.0f} value represents the left (top) edge of the rectangular 92 * bounds of the window. The {@code 1.0f} value represents the right 93 * (bottom) edge of the bounds. Whenever the size of the window changes, 94 * the origin of the coordinate system gets relocated accordingly. For 95 * convenience a developer may use the {@code Component.*_ALIGNMENT} 96 * constants to pass predefined values for these arguments. 97 * <p> 98 * The {@code point} argument specifies the location of the security 99 * warning in the coordinate system described above. If both {@code x} and 100 * {@code y} coordinates of the point are equal to zero, the warning will 101 * be located right in the origin of the coordinate system. On the other 102 * hand, if both {@code alignmentX} and {@code alignmentY} are equal to 103 * zero (i.e. the origin of the coordinate system is placed at the top-left 104 * corner of the window), then the {@code point} argument represents the 105 * absolute location of the security warning relative to the location of 106 * the window. The "absolute" in this case means that the position of the 107 * security warning is not effected by resizing of the window. 108 * <p> 109 * Note that the security warning management code guarantees that: 110 * <ul> 111 * <li>The security warning cannot be located farther than two pixels from 112 * the rectangular bounds of the window (see {@link Window#getBounds}), and 113 * <li>The security warning is always visible on the screen. 114 * </ul> 115 * If either of the conditions is violated, the calculated position of the 116 * security warning is adjusted by the system to meet both these 117 * conditions. 118 * <p> 119 * The default position of the security warning is in the upper-right 120 * corner of the window, two pixels to the right from the right edge. This 121 * corresponds to the following arguments passed to this method: 122 * <ul> 123 * <li>{@code alignmentX = Component.RIGHT_ALIGNMENT} 124 * <li>{@code alignmentY = Component.TOP_ALIGNMENT} 125 * <li>{@code point = (2, 0)} 126 * </ul> 127 * 128 * @param window the window to set the position of the security warning for 129 * @param alignmentX the horizontal origin of the coordinate system 130 * @param alignmentY the vertical origin of the coordinate system 131 * @param point the position of the security warning in the specified 132 * coordinate system 133 * 134 * @throws NullPointerException if the window argument is null 135 * @throws NullPointerException if the point argument is null 136 * @throws IllegalArgumentException if the window is trusted (i.e. 137 * the {@code getWarningString()} returns null 138 * @throws IllegalArgumentException if the alignmentX or alignmentY 139 * arguments are not within the range [0.0f ... 1.0f] 140 */ 141 public static void setPosition(Window window, Point2D point, 142 float alignmentX, float alignmentY) 143 { 144 if (window == null) { 145 throw new NullPointerException( 146 "The window argument should not be null."); 147 } 148 if (window.getWarningString() == null) { 149 throw new IllegalArgumentException( 150 "The window must have a non-null warning string."); 151 } 152 if (point == null) { 153 throw new NullPointerException( 154 "The point argument must not be null"); 155 } 156 if (alignmentX < 0.0f || alignmentX > 1.0f) { 157 throw new IllegalArgumentException( 158 "alignmentX must be in the range [0.0f ... 1.0f]."); 159 } 160 if (alignmentY < 0.0f || alignmentY > 1.0f) { 161 throw new IllegalArgumentException( 162 "alignmentY must be in the range [0.0f ... 1.0f]."); 163 } 164 165 AWTAccessor.getWindowAccessor().setSecurityWarningPosition(window, 166 point, alignmentX, alignmentY); 167 } 168 } 169