This document describes the JavaFX applet and Web Start applications startup process. It explains the new default startup experience introduced in JavaFX 1.3.1, and how the startup process can be customized by developers.

Introduction

The user experience is important for any rich Internet application (RIA). You can enhance your application by providing a responsive and dynamic startup experience. The startup experience begins when the user initiates your application (such as navigating to a web page that includes your applet or clicking a button on a web page to launch a Web Start application), and continues until the first application panel is displayed.

A complex application, a large amount of data to be loaded from the network, or network speed sometimes do not allow an instant startup. You can improve the perceived performance and create a good user experience during startup by providing dynamic visual feedback such as animation or a progress indicator.

The JavaFX 1.3.1 release intoduces the following enhancements:

• More deterministic feedback to users for all JavaFX applications such as a progress indicator with a percentage completed or time remaining
• More developer control over the startup experience with a greater degree of customization

All JavaFX applications automatically benefit from runtime improvements without any additional changes to the code, however, users must have a recent version of JRE. See the Requirements section for details.

Startup Process

The startup process consists of the following three phases:

1. Initialization
   An initial examination identifies components that must be loaded and executed before starting the application.
2. Loading and preparation
   The required resources are loaded, including the JavaFX runtime and application code, from either the network or a disk cache, and validation procedures occur.
3. Application execution
   The application is displayed and is ready to use.

During startup, users encounter one of the following scenarios:

• Both the JavaFX runtime and the application are loaded.
• Only the application is loaded, because the JavaFX runtime is cached on the user's computer.
• Neither the JavaFX runtime nor the application is loaded, because both are cached.

Which scenario takes place depends on whether the correct version of the JavaFX runtime and your application have been loaded on a previous occasion.

Initialization takes about the same time whether resources are loaded from the network or a disk cache. Even with a low-bandwidth connection and high network latency, initialization lasts 2 or 3 seconds at the most.

The loading and preparation phase can take considerable time if the amount of data to be downloaded is large, or it can take very little time when all resources are cached.

Default Startup Experience

Feedback about application startup is provided in the following ways:

• A splash screen appears during the initialization phase.
• A loading progress indicator appears during the loading and preparation phase.

When a user initiates an application, the amount of required work is unknown and it is hard to get an estimate on when the application will be started. For this reason, a non-deterministic indicator such as a splash screen is displayed at the beginning. At the loading and preparation phase, it is already known what components must be loaded and an estimate for the amount of the remaining work can be provided. Based on this estimate, a deterministic progress indicator is displayed.

Table 1 summarizes the default applet startup experience for each of the three scenarios.

In the first scenario, a default progress indicator is downloaded after initialization completes. For this reason, the splash screen is displayed a bit longer than in other scenarios.

For an application that is loaded from the cache, the progress indicator is disabled. This avoids flickering effects, because the time between when the scope of remaining work becomes known and when the application is started, is very short.

Table 2 summarizes the JavaFX Web Start application startup experience for each of the three scenarios.

Because an initial phase is typically rather short, it is better not to show any feedback before displaying a deterministic progress indicator to avoid a flickering effect.

Figure 1 shows what procedures take place and which feedback is provided to the user at each phase of loading a JavaFX applet when both JavaFX runtime and application JAR files have to be loaded.

Figure 1: JavaFX Applet Startup Experience When the JavaFX Runtime and Application JAR Files Are Loaded

Figure 2 shows what procedures take place and which feedback is provided to the user at each phase of loading a JavaFX applet when only an application JAR file has to be loaded.

Figure 2: JavaFX Applet Startup Experience When Only the Application JAR File Is Loaded

Note that for JavaFX applets, both a splash screen and a progress bar are embedded into the page. For applets that are smaller than 100 pixels by 100 pixels, a different splash screen and progress indicator are used.

Figure 3 shows what procedures take place and which feedback is provided to users at each phase of loading a JavaFX Web Start application when both the JavaFX runtime and application JAR files have to be loaded.

Figure 3: JavaFX Web Start Application Startup Experience When JavaFX Runtime and Application JAR Files Are Loaded

Figure 4 shows what procedures take place and which feedback is provided to the user at each phase of loading a JavaFX Web Start application when only an application JAR file has to be loaded.

Figure 4: JavaFX Web Start Application Startup Experience When Only the Application JAR File Is Loaded

Note that for Web Start applications, the splash screen and the progress indicator are displayed as separate windows by default. The default progress indicator displays a progress bar and percentage completed.

If both the JavaFX runtime and application are in the cache, nothing is loaded. There is nothing to report in the deterministic progress indicator, so it is not displayed. Only the splash screen is shown for both applets and Web Start applications.

Customizing the Startup Experience

With JavaFX 1.3.1 release, you have more control over the startup experience with a greater degree of customization. You can provide specific parameters to create a progress indicator that closely matches the images of the web site or the application. Parameters enable you to leverage the default progress indicator with minimum effort.

You can customize the loading experience in the following ways:

• Tune the loading progress indicator.
• Replace a splash screen with your own splash image.
• Build your own implemention of a loading progress indicator.

How to Tune a Default Progress Indicator

Although the default progress indicator was designed to fit a variety of applications, one type does not fit all purposes. For example, the default background color might not fit the color theme of your applet in a web page. Rather than implementing your own progress indicator, you can adjust the appearance of the default progress indicator by passing specific parameters. If the JavaFX runtime is installed, then users do not need to download a default progress indicator, and the loading progress indicator will appear sooner.

The default progress indicator contains the following components:

• A background for the entire area of the progress indicator
• A progress bar that denotes the process within the range of 0 and 100
• An optional image, such as a logo
• A text caption that shows the percentage completed

You can customize the default progress indicator by using the following options:

• Specify the color or image to be used as the background.
• Add a graphical element such as a logo.
• Change sizes and locations of elements.

Table 3 contains a summary of parameters available for customizing components of the default progress indicator.

To customize progress indicator options for an applet, parameters can be passed to the applet by using the JavaScript, as shown in the following example.

<script src="http://dl.javafx.com/1.3/dtfx.js"></script>
<script>

    javafx(
       {
           archive: "Reversi.jar",
           width: 600,
           height: 400,
           code: "reversi.Main",
           draggable: true,
           name: "appl"
       },
       {
           "progress.icon.url" : "http://javafx.com/samples/Reversi/reversi-logo.jpg",
           "progress.icon.x" : 170,
           "progress.icon.y" : 20
       }
    ); 
</script>    

To pass parameters to a Web Start application, add property tags to the application JNLP file as shown in the following example.

<jnlp>
...
<resources>
<property name="jnlp.progress.background.color" value="#f5f5f5"/>
<property name="jnlp.progress.bar.x" value="300"/>
<property name="jnlp.progress.bar.y" value="203"/>
<property name="jnlp.progress.bar.width" value="300"/>
<property name="jnlp.progress.bar.height" value="100"/>
<property name="jnlp.progress.icon.url" value="boat.gif"/>
<property name="jnlp.progress.icon.x" value="50"/>
<property name="jnlp.progress.icon.y value="50"/>


</resources>
...            
</jnlp>    

Note that you need to add the jnlp. prefix to the property name.

Figure 5 shows an example of a customized progress indicator implemented in the Path Animation sample.

Figure 5: JavaFX Web Start Application Startup Experience When Only the Application JAR File Is Loaded

How to Replace a Splash Screen With Your Own Image

You can provide your own image to be used as a splash screen. For applets, you can use an image in any format that is supported by a target browser. For Web Start applications, GIF, JPEG, and PNG formats are acceptable. GIF and JPEG formats are recommended for better compatibility with different runtime versions. For an animated splash screen, use an animated GIF.

Note that you will not see the splash screen until the image is loaded. Therefore, when you select an image for your splash screen, ensure that the file is a reasonable size. To decrease the size of your image file, apply the same techniques that are used for optimization of visual assets for web sites. It is a best practice to pre-scale your images to specific dimensions by using a graphical editor.

The following code sample shows how to replace the splash screen.

<script src="http://dl.javafx.com/1.3/dtfx.js"></script>
<script>

    javafx({
        archive: "pathanimation.jar",
        width: 480,
        height: 640,
        name: "appl",
        loading_image_url: "boat.gif",
        loading_image_width: 135,
        loading_image_height: 112,
        loading_background: "green"
    });
</script>    

To see an example with a custom splash screen in action, run the Path Animation sample.

How to Add a Custom Progress Indicator to a JavaFX Application

If you want the startup experience to blend smoothly with your application, you can provide your own implementation of a custom progress indicator as part of your JavaFX application. However, note that the progress indicator will be displayed slightly later, because additional time is needed to load your implementation, while the default progress indicator is likely to be present on a user's computer as part of the JavaFX runtime.

A progress indicator is an object that implements the DownloadServiceListener interface, which gets notifications on loading progress from 0 to 100. Typically, the progress indicator must be implemented in Java and not in JavaFX Script, because the JavaFX runtime might be not available on user systems at the time the progress indicator must be shown. Most of the implementation details are not specific to JavaFX applications. See the Java tutorial Customizing the Loading Experience.

Custom progress indicators may take virtually any shape or form and may not include a traditional progress bar at all. Instead the download progress may be visualized by an animation closely matching the design of the application. See the MyTVSchedule sample application for an example of such a solution. What makes custom-built progress indicators special is that their logic is based on notifications received using a specified interface and that they must implement special constructors

Figure 6 shows an example of a customized loading progress indicator. Instead of a typical progress bar, black game pieces rotate and turn white as the loading process progresses.

Figure 6: A Customized Loading Progress Indicator

There is one important implementation detail for custom progress indicators to be used with JavaFX applets. Unlike Java applets, JavaFX applets have a splash screen by default, which must be explicitly hidden when it is time to show the progress indicator. To hide the splash screen, call the fxAppletHideSplash function in JavaScript and pass the applet ID as a parameter. The following example shows how to hide the splash screen for applets.

boolean needToHideSplash = true;
private synchronized void hideSplash() {
    if (needToHideSplash) {
        try {
            //If a current applet has a splash screen, then
            //"deployJavaAppletID" parameter contains an applet identifier
            //in the context of the current web page.
            String appletid = this.stub.getParameter("deployJavaAppletID");

                if (appletid != null && !appletid.isEmpty()) {
                    JSObject js = JSObject.getWindow(null);
                    //May return null in case of older versions of JRE
                    if (js != null){
                        //Call the fxAppletHideSplash function 
                        //with the applet ID as a parameter
                        js.call("fxAppletHideSplash", new Object[]{appletid});
                        needToHideSplash = false;
                    }
                } 
        } catch (Exception e) {
              println ("Failed to hide FX Splash! " + e);
        }
    }
}  

To add a custom progress indicator to a JavaFX application, package the progress indicator implementation as a JAR file by calling the JavaFX Packager utility from the command line, as shown in the following example.

javafxpackager
    -XXcustomProgressJar <pr.jar>
    -XXcustomProgressClass <name> 
    -XXnoCPinManifest
    

Notes:

• This is a one-line command. Parameters are listed on new lines for better readability.
• <pr.jar> stands for the JAR file of your custom progress indicator.
• <name> is the name of the main class from the progress indicator JAR file.
• The XXnoCPinManifest  parameter specifies that there is no classpath entry in the JAR manifests for both custom progress indicator and application JAR files.

Besides a JAR file, the javafxpackager command generates a JNLP file and a file with an HTML code for your application.

The following are tips for developing the custom progress indicator:

• To ensure your progress indicator displays promptly, keep its implementation small. Ordinarily, the progress JAR file must be at least a few times smaller than the size of your application JAR file. For instance, the default progress indicator implemented in the JavaFX 1.3.1 release is about 20K of uncompressed bytecode only.
• Application loading process consists of multiple steps, and steps may differ for different loading scenarios (see the tables in the Default Startup Experience section). For a good user experience, it is important to provide smooth transitions between the steps for all scenarios.
• The progress indicator works only for applets on systems with JNLP support enabled. For example, it cannot be used on Mac systems, where JNLP applet support is disabled by default.
• If your JavaFX application is signed, then the progress indicator JAR file must be signed with the same certificate.

Note that you do not need to introduce any changes to your application to enable the improved loading experience if your application uses JavaFX 1.3.1. However, users of your application must have a recent runtime version (see the Requirements section) to observe the new startup experience.

Requirements

The new startup application experience is provided under the following assumptions on the user's computer:

• Java Runtime Environment (JRE) update 18 or later for Web Start applications
• JRE update 21 or later with Java Plug-In 2 enabled for applets

Currently, the new startup experience is not available for applets on the Mac OS X platform.

On platforms where the new startup experience is not available, users will see a standard splash screen with animation throughout the entire startup process for applets, and a standard (non-customizable) progress download dialog box for Web Start applications.

Related Information

• Getting Started with JavaFX Technology
• JavaFX 1.3.1 SDK Release Notes
• JavaFX.com