1 /*

     2  * Copyright 2008-2009 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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 managment 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