platform-update-home/doc/eclipse_splash.html
Parent Directory
| 
Revision Log
Revision 1.3 - (view) (download) (as text)
| 1 : | droberts | 1.3 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | jeem | 1.1 | <html> |
| 3 : | |||
| 4 : | <head> | ||
| 5 : | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | ||
| 6 : | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| 7 : | <meta name="ProgId" content="FrontPage.Editor.Document"> | ||
| 8 : | <title>Eclipse executable launcher</title> | ||
| 9 : | </head> | ||
| 10 : | |||
| 11 : | <body> | ||
| 12 : | |||
| 13 : | <h1>Eclipse Splash Screens</h1> | ||
| 14 : | jeem | 1.2 | <p>Last revised 16:45 Saturday June 1, 2002</p> |
| 15 : | jeem | 1.1 | <p>This note describes how splash screens work.</p> |
| 16 : | <h2>What product developers need to know</h2> | ||
| 17 : | <p>From the product developer's standpoint, the product owner supplies a product | ||
| 18 : | splash screen containing a color image roughly 500x330 pixels in size. This | ||
| 19 : | file, named "<code>splash.bmp</code>", lives in the plug-in for the | ||
| 20 : | jeem | 1.2 | product's primary feature. The file is in 24-bit color BMP format on all operating |
| 21 : | environments (note: it must be a simple RGB with 8 bits per channel, not an | ||
| 22 : | indexed color BMP). For internationalized applications, translated splash | ||
| 23 : | jeem | 1.1 | screens live in locale-specific subdirectories of the plug-in (e.g., the splash |
| 24 : | screen for locale code "fr_FR_EURO" is in "<code>nl/fr/FR/EURO/splash.bmp</code>") | ||
| 25 : | . For example,</p> | ||
| 26 : | <p><code><<i>install</i>>/<br> | ||
| 27 : | eclipse/<br> | ||
| 28 : | plugins/<br> | ||
| 29 : | <i>com.example.acme.acmefeature_1.0.0</i>/<br> | ||
| 30 : | splash.bmp<br> | ||
| 31 : | nl/<br> | ||
| 32 : | fr/<br> | ||
| 33 : | splash.bmp<br> | ||
| 34 : | CA/<br> | ||
| 35 : | splash.bmp<br> | ||
| 36 : | FR/<br> | ||
| 37 : | splash.bmp<br> | ||
| 38 : | EURO/<br> | ||
| 39 : | | ||
| 40 : | splash.bmp<br> | ||
| 41 : | en/<br> | ||
| 42 : | splash.bmp<br> | ||
| 43 : | US/<br> | ||
| 44 : | | ||
| 45 : | splash.bmp<br> | ||
| 46 : | </code></p> | ||
| 47 : | <p>Any of the translated splash screens can live in a fragment of the product's | ||
| 48 : | primary feature plug-in; they do not need to live in the plug-in itself. This | ||
| 49 : | allows another feature (or features) to supply translated splash screens; e.g., | ||
| 50 : | a special feature that provides a product's Asian language translations.</p> | ||
| 51 : | <p>Each version of a primary feature supplies a version of the splash screen | ||
| 52 : | file. This means that it is possible to update a product's splash screen like | ||
| 53 : | any other file in a plug-in.</p> | ||
| 54 : | <p>A product can have multiple primary features, although only one primary | ||
| 55 : | feature is in control on a given occasion of use. Each of the different primary | ||
| 56 : | features in a product has its own splash screen.</p> | ||
| 57 : | <p>A splash image is shown each time the product is launched (unless the <code>-nosplash</code> | ||
| 58 : | command line option is specified). The splash screen presented is the one for the | ||
| 59 : | controlling primary feature version, translated for the desired locale.</p> | ||
| 60 : | <h2>What product developers do not need to know</h2> | ||
| 61 : | <p><b>N.B. The details in this section are not Eclipse platform API, and may | ||
| 62 : | change over time. Things are described here only to provide a sense of what goes | ||
| 63 : | on in the wings. Product developers must not rely on anything described in this | ||
| 64 : | section.</b></p> | ||
| 65 : | <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 | ||
| 66 : | is more than a brief delay, the user will think the product sluggish or | ||
| 67 : | malfunctioning. Time is of the essence when getting the splash screen on the | ||
| 68 : | screen.</p> | ||
| 69 : | <p>In a naive implementation, the Eclipse platform would determine the right splash | ||
| 70 : | screen for the product being launched and locale, and show the splash | ||
| 71 : | screen to the user in a window created with SWT. Unfortunately, the complexity | ||
| 72 : | of starting up the Eclipse platform makes this approach unacceptably slow in | ||
| 73 : | getting the splash screen up. Thus we need a somewhat more sophisticated | ||
| 74 : | approach.</p> | ||
| 75 : | <p>On each occasion of running <code>eclipse.exe</code>, the following factors | ||
| 76 : | determine which splash screen to show:</p> | ||
| 77 : | <ul> | ||
| 78 : | <li>Primary feature id. Each primary features has its own splash screen. The | ||
| 79 : | primary feature is given either by the <code>-feature</code> | ||
| 80 : | command line option, or defaults to a choice recorded in the workspace (<code><<i>workspace</i>>/.metadata/.config/platform.cfg</code>), | ||
| 81 : | or in <code><<i>install</i>>/eclipse/.config/platform.cfg</code> if this is | ||
| 82 : | the first time for this workspace.</li> | ||
| 83 : | <li>Primary feature version. Each primary features version has its own splash | ||
| 84 : | screen. The version to be used is recorded in in the workspace (<code><<i>workspace</i>>/.metadata/.config/platform.cfg</code>), | ||
| 85 : | or in <code><<i>install</i>>/eclipse/.config/platform.cfg</code> if this is | ||
| 86 : | the first time for this workspace.</li> | ||
| 87 : | <li>Locale. Each splash screen may exist in translation. The locale is given either by the <code>-nl</code> command line option, | ||
| 88 : | or obtained directly from the operating system.</li> | ||
| 89 : | </ul> | ||
| 90 : | <p>Because of this complexity is determining which splash screen to show, the | ||
| 91 : | responsibilities are divided as follows:</p> | ||
| 92 : | <ul> | ||
| 93 : | <li>Eclipse itself (BootLoader) is responsible for | ||
| 94 : | determining the full path of the splash screen file and requesting the Eclipse executable launcher | ||
| 95 : | to show it. This is done by analyzing command line arguments and reading the | ||
| 96 : | configuration files in the install or the workspace.</li> | ||
| 97 : | <li>The Eclipse executable launcher is responsible for displaying the | ||
| 98 : | specified splash screen to the user. The Eclipse executable launcher passes | ||
| 99 : | a "show" command to Main; Main calls it with the path of the | ||
| 100 : | appropriate splash file and and holds onto the process object reference. The | ||
| 101 : | process puts up a window with the splash image in it. Since the full path of the splash screen file is | ||
| 102 : | passed as a parameter, the Eclipse executable launcher can remain completely | ||
| 103 : | ignorant of the existence of a splash screen cache and of locale-specific | ||
| 104 : | concerns. If the Eclipse executable launcher is unable to find or read the | ||
| 105 : | requested splash screen file, the launch simply proceeds without showing any | ||
| 106 : | splash screen.</li> | ||
| 107 : | <li>Eclipse itself (Main, Workbench, and BootLoader) is responsible for | ||
| 108 : | deciding when to stop showing the splash screen. As soon as the workbench window has been displayed to the | ||
| 109 : | user, the workbench tells Main to take down the splash screen, which it does | ||
| 110 : | by destroying the process it spawned. If there are any problems with taking | ||
| 111 : | down the splash screen, the launch simply proceeds as if no splash screen | ||
| 112 : | had been shown.</li> | ||
| 113 : | </ul> | ||
| 114 : | <p>When the Eclipse platform formulates a configuration file (<code>platform.cfg</code>), it computes and stores the mapping | ||
| 115 : | from primary feature version and known locale to splash file path. Splash file | ||
| 116 : | paths are stored in install-relative form to ensure they are usable by any user | ||
| 117 : | that locates the install. The absolute file path of the correct splash screen | ||
| 118 : | must be determined quickly so that the splash screen can be displayed to the | ||
| 119 : | user without further delay. The ability to properly resolve arbitrary plug-in | ||
| 120 : | relative paths only becomes available once the plug-in registry has been built; | ||
| 121 : | however, by that time the Eclipse platform is almost up and running, and the | ||
| 122 : | splash screen is already too late. For splash screen purposes, splash file paths | ||
| 123 : | are resolved by prefixing them with <code><<i>install</i>>/eclipse/plugins</code>/. | ||
| 124 : | This works for all splash screens within plug-ins and fragments located within | ||
| 125 : | the product's install directory, which is most of the time. However, it fails to | ||
| 126 : | find splash screens located in another local site, such as an extension.</p> | ||
| 127 : | |||
| 128 : | <p>The very first time the Eclipse platform is launched with a new workspace, | ||
| 129 : | there is no <code>platform.cfg</code> (unless there is a pre-computed default | ||
| 130 : | one stored with the install), and it will take several seconds to compute one. | ||
| 131 : | Until it does, it won't know the correct splash screen. So it immediately | ||
| 132 : | displays an interim splash screen (a plain canned image that reads | ||
| 133 : | "Completing the install. Please wait...") and goes about its business. | ||
| 134 : | When it is done, it takes down the splash screen and does an exit-with-relaunch; | ||
| 135 : | the product now starts with the newly-computed <code>platform.cfg</code> telling it exactly where | ||
| 136 : | to find the correct splash screen. The same holds true for subsequent launches. | ||
| 137 : | This special splash screen and all its translations are in the <code>org.eclipse.core.boot</code> | ||
| 138 : | plug-in (to simplify the implementation, we do <i>not</i> look in fragments).</p> | ||
| 139 : | |||
| 140 : | </body> | ||
| 141 : | |||
| 142 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |