Eclipse Splash Screens

Last revised 16:45 Saturday June 1, 2002

This note describes how splash screens work.

What product developers need to know

From the product developer's standpoint, the product owner supplies a product splash screen containing a color image roughly 500x330 pixels in size. This file, named "splash.bmp", lives in the plug-in for the product's primary feature. The file is in 24-bit color BMP format on all operating environments (note: it must be a simple RGB with 8 bits per channel, not an indexed color BMP). For internationalized applications, translated splash screens live in locale-specific subdirectories of the plug-in (e.g., the splash screen for locale code "fr_FR_EURO" is in "nl/fr/FR/EURO/splash.bmp") . For example,

<install>/
  eclipse/
    plugins/
      com.example.acme.acmefeature_1.0.0/
        splash.bmp
        nl/
          fr/
            splash.bmp
            CA/
              splash.bmp
            FR/
              splash.bmp
              EURO/
                splash.bmp
          en/
            splash.bmp
            US/
              splash.bmp


Any of the translated splash screens can live in a fragment of the product's primary feature plug-in; they do not need to live in the plug-in itself. This allows another feature (or features) to supply translated splash screens; e.g., a special feature that provides a product's Asian language translations.

Each version of a primary feature supplies a version of the splash screen file. This means that it is possible to update a product's splash screen like any other file in a plug-in.

A product can have multiple primary features, although only one primary feature is in control on a given occasion of use. Each of the different primary features in a product has its own splash screen.

A splash image is shown each time the product is launched (unless the -nosplash command line option is specified). The splash screen presented is the one for the controlling primary feature version, translated for the desired locale.

What product developers do not need to know

N.B. The details in this section are not Eclipse platform API, and may change over time. Things are described here only to provide a sense of what goes on in the wings. Product developers must not rely on anything described in this section.

The product splash screen is shown to the user upon launching the program from a desktop item, menu item, or shortcut key. If there is more than a brief delay, the user will think the product sluggish or malfunctioning. Time is of the essence when getting the splash screen on the screen.

In a naive implementation, the Eclipse platform would determine the right splash screen for the product being launched and locale, and show the splash screen to the user in a window created with SWT. Unfortunately, the complexity of starting up the Eclipse platform makes this approach unacceptably slow in getting the splash screen up. Thus we need a somewhat more sophisticated approach.

On each occasion of running eclipse.exe, the following factors determine which splash screen to show:

• Primary feature id. Each primary features has its own splash screen. The primary feature is given either by the -feature command line option, or defaults to a choice recorded in the workspace (<workspace>/.metadata/.config/platform.cfg), or in <install>/eclipse/.config/platform.cfg if this is the first time for this workspace.
• Primary feature version. Each primary features version has its own splash screen. The version to be used is recorded in in the workspace (<workspace>/.metadata/.config/platform.cfg), or in <install>/eclipse/.config/platform.cfg if this is the first time for this workspace.
• Locale. Each splash screen may exist in translation. The locale is given either by the -nl command line option, or obtained directly from the operating system.

Because of this complexity is determining which splash screen to show, the responsibilities are divided as follows:

• Eclipse itself (BootLoader) is responsible for determining the full path of the splash screen file and requesting the Eclipse executable launcher to show it. This is done by analyzing command line arguments and reading the configuration files in the install or the workspace.
• The Eclipse executable launcher is responsible for displaying the specified splash screen to the user. The Eclipse executable launcher passes a "show" command to Main; Main calls it with the path of the appropriate splash file and and holds onto the process object reference. The process puts up a window with the splash image in it. Since the full path of the splash screen file is passed as a parameter, the Eclipse executable launcher can remain completely ignorant of the existence of a splash screen cache and of locale-specific concerns. If the Eclipse executable launcher is unable to find or read the requested splash screen file, the launch simply proceeds without showing any splash screen.
• Eclipse itself (Main, Workbench, and BootLoader) is responsible for deciding when to stop showing the splash screen. As soon as the workbench window has been displayed to the user, the workbench tells Main to take down the splash screen, which it does by destroying the process it spawned. If there are any problems with taking down the splash screen, the launch simply proceeds as if no splash screen had been shown.

When the Eclipse platform formulates a configuration file (platform.cfg), it computes and stores the mapping from primary feature version and known locale to splash file path. Splash file paths are stored in install-relative form to ensure they are usable by any user that locates the install. The absolute file path of the correct splash screen must be determined quickly so that the splash screen can be displayed to the user without further delay. The ability to properly resolve arbitrary plug-in relative paths only becomes available once the plug-in registry has been built; however, by that time the Eclipse platform is almost up and running, and the splash screen is already too late. For splash screen purposes, splash file paths are resolved by prefixing them with <install>/eclipse/plugins/. This works for all splash screens within plug-ins and fragments located within the product's install directory, which is most of the time. However, it fails to find splash screens located in another local site, such as an extension.

The very first time the Eclipse platform is launched with a new workspace, there is no platform.cfg (unless there is a pre-computed default one stored with the install), and it will take several seconds to compute one. Until it does, it won't know the correct splash screen. So it immediately displays an interim splash screen (a plain canned image that reads "Completing the install. Please wait...") and goes about its business. When it is done, it takes down the splash screen and does an exit-with-relaunch; the product now starts with the newly-computed platform.cfg telling it exactly where to find the correct splash screen. The same holds true for subsequent launches. This special splash screen and all its  translations are in the org.eclipse.core.boot plug-in (to simplify the implementation, we do not look in fragments).