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

src/share/classes/java/awt/SplashScreen.java

@@ -33,27 +33,17 @@ import sun.util.logging.PlatformLogger;
 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 @@ import sun.awt.image.SunWritableRaster;
  * 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 @@ public final class SplashScreen {
 
     /**
      * 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 @@ public final class SplashScreen {
      * <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 @@ public final class SplashScreen {
      * <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 @@ public final class SplashScreen {
      * 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 @@ public final class SplashScreen {
      * 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