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
26package com.sun.awt;
27
28import java.awt.*;
29import java.awt.geom.*;
30
31import 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 */
49public 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
170