Mercurial > hg > release > icedtea7-forest-2.3 > jdk
changeset 3437:4a0970a420d5
6993803: Request to update SplashScreen specification
6984255: Request for java.awt.SplashScreen spec update: mention possibility of having custom "-splash" option
6992416: [Spec clarification request] Is color deviation for splash screen image allowed?
6992833: [Spec clarification request] point (0,0) in SplashScreen.createGraphics()
6993071: java.awt.SplashScreen should mention that no unnecessary distortions to the image are allowed
6993113: [Spec clarification request] getSplashScreen(): null or HeadlessException?
6996439: [Spec clarification request] Is any delay with splashscreen appearance allowed?
Summary: Update SplashScreen specification
Reviewed-by: art
author | anthony |
---|---|
date | Thu, 16 Dec 2010 21:48:30 +0300 |
parents | b9706aff91a3 |
children | 8dbb797793b0 |
files | src/share/classes/java/awt/SplashScreen.java |
diffstat | 1 files changed, 51 insertions(+), 25 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/awt/SplashScreen.java Wed Dec 15 11:49:36 2010 -0800 +++ b/src/share/classes/java/awt/SplashScreen.java Thu Dec 16 21:48:30 2010 +0300 @@ -33,27 +33,17 @@ import sun.awt.image.SunWritableRaster; /** - * The splash screen can be created at application startup, before the + * The splash screen can be displayed at application startup, before the * Java Virtual Machine (JVM) starts. The splash screen is displayed as an - * undecorated window containing an image. You can use GIF, JPEG, and PNG files - * for the image. Animation (for GIF) and transparency (for GIF, PNG) are - * supported. The window is positioned at the center of the screen (the - * position on multi-monitor systems is not specified - it is platform and - * implementation dependent). - * The window is closed automatically as soon as the first window is displayed by - * Swing/AWT (may be also closed manually using the Java API, see below). + * undecorated window containing an image. You can use GIF, JPEG, or PNG files + * for the image. Animation is supported for the GIF format, while transparency + * is supported both for GIF and PNG. The window is positioned at the center + * of the screen. The position on multi-monitor systems is not specified. It is + * platform and implementation dependent. The splash screen window is closed + * automatically as soon as the first window is displayed by Swing/AWT (may be + * also closed manually using the Java API, see below). * <P> - * There are two ways to show the native splash screen: - * <P> - * <UL> - * <LI>If your application is run from the command line or from a shortcut, - * use the "-splash:" Java application launcher option to show a splash screen. - * <BR> - * For example: - * <PRE> - * java -splash:filename.gif Test - * </PRE> - * <LI>If your application is packaged in a jar file, you can use the + * If your application is packaged in a jar file, you can use the * "SplashScreen-Image" option in a manifest file to show a splash screen. * Place the image in the jar archive and specify the path in the option. * The path should not have a leading slash. @@ -64,18 +54,39 @@ * Main-Class: Test * SplashScreen-Image: filename.gif * </PRE> + * <P> + * If the Java implementation provides the command-line interface and you run + * your application by using the command line or a shortcut, use the Java + * application launcher option to show a splash screen. The Oracle reference + * implementation allows you to specify the splash screen image location with + * the {@code -splash:} option. + * <BR> + * For example: + * <PRE> + * java -splash:filename.gif Test + * </PRE> * The command line interface has higher precedence over the manifest * setting. - * </UL> + * <p> + * The splash screen will be displayed as faithfully as possible to present the + * whole splash screen image given the limitations of the target platform and + * display. + * <p> + * It is implied that the specified image is presented on the screen "as is", + * i.e. preserving the exact color values as specified in the image file. Under + * certain circumstances, though, the presented image may differ, e.g. when + * applying color dithering to present a 32 bits per pixel (bpp) image on a 16 + * or 8 bpp screen. The native platform display configuration may also affect + * the colors of the displayed image (e.g. color profiles, etc.) * <p> * The {@code SplashScreen} class provides the API for controlling the splash * screen. This class may be used to close the splash screen, change the splash - * screen image, get the image position/size and paint in the splash screen. It - * cannot be used to create the splash screen; you should use the command line or manifest - * file option for that. + * screen image, get the splash screen native window position/size, and paint + * in the splash screen. It cannot be used to create the splash screen. You + * should use the options provided by the Java implementation for that. * <p> * This class cannot be instantiated. Only a single instance of this class - * can exist, and it may be obtained using the {@link #getSplashScreen()} + * can exist, and it may be obtained by using the {@link #getSplashScreen()} * static method. In case the splash screen has not been created at * application startup via the command line or manifest file option, * the <code>getSplashScreen</code> method returns <code>null</code>. @@ -91,7 +102,7 @@ /** * Returns the {@code SplashScreen} object used for - * Java startup splash screen control. + * Java startup splash screen control on systems that support display. * * @throws UnsupportedOperationException if the splash screen feature is not * supported by the current toolkit @@ -219,6 +230,9 @@ * <p> * You cannot control the size or position of the splash screen. * The splash screen size is adjusted automatically when the image changes. + * <p> + * The image may contain transparent areas, and thus the reported bounds may + * be larger than the visible splash screen image on the screen. * * @return a {@code Rectangle} containing the splash screen bounds * @throws IllegalStateException if the splash screen has already been closed @@ -237,6 +251,9 @@ * <p> * You cannot control the size or position of the splash screen. * The splash screen size is adjusted automatically when the image changes. + * <p> + * The image may contain transparent areas, and thus the reported size may + * be larger than the visible splash screen image on the screen. * * @return a {@link Dimension} object indicating the splash screen size * @throws IllegalStateException if the splash screen has already been closed @@ -254,6 +271,10 @@ * screen window. You should call {@code update()} on the * <code>SplashScreen</code> when you want the splash screen to be * updated immediately. + * <p> + * The pixel (0, 0) in the coordinate space of the graphics context + * corresponds to the origin of the splash screen native window bounds (see + * {@link #getBounds()}). * * @return graphics context for the splash screen overlay surface * @throws IllegalStateException if the splash screen has already been closed @@ -334,6 +355,11 @@ * Determines whether the splash screen is visible. The splash screen may * be hidden using {@link #close()}, it is also hidden automatically when * the first AWT/Swing window is made visible. + * <p> + * Note that the native platform may delay presenting the splash screen + * native window on the screen. The return value of {@code true} for this + * method only guarantees that the conditions to hide the splash screen + * window have not occurred yet. * * @return true if the splash screen is visible (has not been closed yet), * false otherwise