platform-update-home/doc/eclipse_splash.html
Parent Directory
| 
Revision Log
Revision 1.2 -
(download)
(as text)
(annotate)
Sat Jun 1 20:40:42 2002 UTC (7 years, 5 months ago) by jeem
Branch: MAIN
Changes since 1.1: +4 -3 lines
Sat Jun 1 20:40:42 2002 UTC (7 years, 5 months ago) by jeem
Branch: MAIN
Changes since 1.1: +4 -3 lines
Clarify that splash screen must be 24-bit straight RGB
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Eclipse executable launcher</title>
</head>
<body>
<h1>Eclipse Splash Screens</h1>
<p>Last revised 16:45 Saturday June 1, 2002</p>
<p>This note describes how splash screens work.</p>
<h2>What product developers need to know</h2>
<p>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 "<code>splash.bmp</code>", 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 "<code>nl/fr/FR/EURO/splash.bmp</code>")
. For example,</p>
<p><code><<i>install</i>>/<br>
eclipse/<br>
plugins/<br>
<i>com.example.acme.acmefeature_1.0.0</i>/<br>
splash.bmp<br>
nl/<br>
fr/<br>
splash.bmp<br>
CA/<br>
splash.bmp<br>
FR/<br>
splash.bmp<br>
EURO/<br>
splash.bmp<br>
en/<br>
splash.bmp<br>
US/<br>
splash.bmp<br>
</code></p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>A splash image is shown each time the product is launched (unless the <code>-nosplash</code>
command line option is specified). The splash screen presented is the one for the
controlling primary feature version, translated for the desired locale.</p>
<h2>What product developers do not need to know</h2>
<p><b>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.</b></p>
<p>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.</p>
<p>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.</p>
<p>On each occasion of running <code>eclipse.exe</code>, the following factors
determine which splash screen to show:</p>
<ul>
<li>Primary feature id. Each primary features has its own splash screen. The
primary feature is given either by the <code>-feature</code>
command line option, or defaults to a choice recorded in the workspace (<code><<i>workspace</i>>/.metadata/.config/platform.cfg</code>),
or in <code><<i>install</i>>/eclipse/.config/platform.cfg</code> if this is
the first time for this workspace.</li>
<li>Primary feature version. Each primary features version has its own splash
screen. The version to be used is recorded in in the workspace (<code><<i>workspace</i>>/.metadata/.config/platform.cfg</code>),
or in <code><<i>install</i>>/eclipse/.config/platform.cfg</code> if this is
the first time for this workspace.</li>
<li>Locale. Each splash screen may exist in translation. The locale is given either by the <code>-nl</code> command line option,
or obtained directly from the operating system.</li>
</ul>
<p>Because of this complexity is determining which splash screen to show, the
responsibilities are divided as follows:</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>When the Eclipse platform formulates a configuration file (<code>platform.cfg</code>), 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 <code><<i>install</i>>/eclipse/plugins</code>/.
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.</p>
<p>The very first time the Eclipse platform is launched with a new workspace,
there is no <code>platform.cfg</code> (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 <code>platform.cfg</code> 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 <code>org.eclipse.core.boot</code>
plug-in (to simplify the implementation, we do <i>not</i> look in fragments).</p>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |