4.1.1 Startup Process

Between the time an application is started and the time the user sees the main application, a sequence of events occurs on screen while operations are carried out in the background, as shown in Figure 4-1 and described in the following paragraphs. This startup sequence partially depends on the execution mode and on the speed with which the background operations complete. Figure 4-1 shows a series of boxes that depict the background operations over time, along with screenshots of what the user sees while these operations occur.

Figure 4-1 Background Operations and Screen Events During Application Startup

Description of "Figure 4-1 Background Operations and Screen Events During Application Startup"

There are four phases in the application startup process:

• Phase 1: Initialization

  Initialization of Java Runtime and an initial examination identifies components that must be loaded and executed before starting the application. The initialization phase is depicted in the first two boxes in the upper row in Figure 4-1.

• Phase 2: Loading and preparation

  The required resources are loaded from either the network or a disk cache, and validation procedures occur. All execution modes see the default or a custom preloader. This phase is depicted in the third box in the upper row in Figure 4-1.

• Phase 3: Application-specific initialization

  The application is started, but it may need to load additional resources or perform other lengthy preparations before it becomes fully functional. An example of this is checking whether elevated permissions are needed and displaying the appropriate request for permission to the user.

• Phase 4: Application execution

  The application is displayed and is ready to use. This occurs after the background operations shown in Figure 4-1 are finished.

4.1.2 Default User Experience

A properly packaged JavaFX application provides default visual feedback to the user for the first two phases for all execution modes. The actual behavior depends on the execution mode.

When launched in standalone mode most applications start quickly, and no visual feedback is required.

Table 4-1 summarizes the default behavior according to execution mode when the application is launched for the first time (in other words, is loaded from the network).

Table 4-1 Default Behavior During First-Time Launch

Startup Phase	Web Start Launch	Embedded into Web Page
Phase 1 Initialization	Splash screen: Description of the illustration java7_splash.gif	Splash screen: Description of the illustration html_splash_75.gif
Phase 2 Loading Code	Progress window: Description of the illustration ws_load.png	Progress window: Description of the illustration progress_dialog2_40.gif
Phase 3 Transition to Application	Hide progress window	Fade-out progress window

Table 4-2 summarizes the default behavior for subsequent launches, in which the JAR files are loaded from the cache. In this case, the process has fewer visual transitions because nothing needs to be loaded from the network during the Loading Code phase, so launch time is substantially shorter.

Table 4-2 Default Startup Behavior During Subsequent Launches

	Web Start Launch or Launch from Shortcut	Embedded into Web Page
Phase 1 Initialization	Splash screen: Description of the illustration java7_splash.gif	Splash screen: Description of the illustration html_splash_75.gif
Phase 2 Loading Code	Description of the illustration java7_splash.gif	Description of the illustration html_splash_75.gif
Phase 3 Transition to Application	Hide splash screen	Hide splash screen

4.1.3 Customization Options

The splash screen for embedded applications is displayed in the web page and can be easily customized by using an onGetSplash callback, as shown in Section 7.2.3, "onGetSplash."

The default preloader can be customized by using a CSS stylesheet, similar to other JavaFX components. Pass the customized style data using the javafx.default.preloader.stylesheet parameter for your application. The value of the parameter can be any of following:

• Absolute or relative URI of the CSS stylesheet, either as a text file with a .css extension or in binary form with a .bss extension. For more information about binary conversion, see Section 5.4, "Stylesheet Conversion."

• Actual CSS code.

To customize the preloader, use the .default-preloader class. In addition to standard CSS keys, the preloader has two special keys:

• -fx-preloader-status-text

  Status text to be shown in the preloader

• -fx-preloader-graphic

  Absolute or relative URI of the image to be used by the preloader

Example 4-1 shows an example of CSS file my.css:

.default-preloader { 
    -fx-background-color: yellow; 
    -fx-text-fill: red; 
    -fx-preloader-graphic: url("http://host.domain/duke.gif"); 
    -fx-preloader-text: "Loading, loading, LOADING!"; 
} 

Add the stylesheet to the <fx:deploy> Ant task as shown in Example 4-2:

<fx:deploy ...>
    <fx:application ...>
        <fx:htmlParam  name="javafx.default.preloader.stylesheet" 
                value="my.css"/>
    <fx:application>
</fx:deploy>

If your customizations are small, then it is more efficient to pass CSS code instead of a file name, because there is no need to download the file. Example 4-3 shows to change the background color to yellow.

<fx:deploy ...>
    <fx:application ...>
    <!-- Using fx:param here, so it will be applicable to all web
            execution environemnts -->
        <fx:param  name="javafx.default.preloader.stylesheet"
                value=".default-preloader { -fx-background-color: yellow; }"/>
    <fx:application>
</fx:deploy> 

If customizing the default preloader is not enough and you need a different visualization or behavior, see Chapter 9, "Preloaders" for information about how to implement your own preloader and see Chapter 5, "Packaging Basics" for information about how to add it to your package.

4.2.1 No JavaFX Runtime

If the user does not have JavaFX Runtime installed, then the application cannot start. The JavaFX application package includes several hooks to improve user experience if this is the case.

You can customize the default behavior described in the following sections. See Chapter 5, "Packaging Basics" for information about how to embed various fallback applications into the application package. See Chapter 7, "Deployment in the Browser" for information about how to customize prompts to install JavaFX Runtime and error handling for web applications.

4.2.2 Runtime Errors

An application can fail to launch due to various runtime errors or user mistakes, such as the absence of a network connection needed to load some of application JAR files.

One of the most common errors is when the user does not grant permissions to the application. In that case, the application fails, and the user has to restart the application and then grant permissions to get it to run. In a case like this, it is helpful to explain to the user why the application failed and what the user must do to restart it successfully. By default, an error message will display, either in a dialog box or inside the web page in the location where the application is embedded. In either case, the messaging can be customized.

If the Deployment Toolkit is used, then the onDeployError handler can be used to display an error message in the application area in the web page. You can also consider including some instructions to the splash screen to alert users about granting permissions. For more information, see Chapter 7, "Deployment in the Browser".

You can also include a custom preloader in your application to get notifications about errors, unless the error occurs while launching the preloader. For more information about preloaders and code examples, see Chapter 9, "Preloaders."