Copyright © 2004 International Business Machines Corporation. All rights reserved
Eclipse Corner Article

Branding Your Application

Summary
In this article we look at how to create branding for your Eclipse-based application. Branding is how you change the high level visual elements of your product. This includes items such as the splash screen, the about dialog, and the program executable.

By Andrew Eidsness and Pascal Rapicault, IBM OTI Labs
September 16, 2004


Intended Audience

You have completed the functionality of your RCP based application but are unhappy because it still looks too much like a default Eclipse application. It is time to "brand your product," which consists of changing aspects such as the icon used by the launcher, the splash screen, the window image, and more. This article will help you to accomplish these tasks and will point you to other documents of interest.

Reading this article

This article has been separated into three main sections:

As you work through the steps you may notice the occasional image. These indicate points at which you may want to test out the work you have done thus far.

The steps in this document assume that you have access to the SDK build but all of the changes we described can be applied to any RCP based application. In the remaining sections we assume that you have a working knowledge of Eclipse based development. In particular we assume that you know how to provide translatable strings for your plug-in (see Locale specific files).

Make sure that you have installed the RCP Runtime Binary before continuing. You should not consider branding or productization unless you are also including your own plug-ins. In this article we use the RCP Browser Example as the target product. To help follow along with examples, you should download this plug-in from the Eclipse repository.

NOTE: This article is intended to be a guide to help you produce a release. You need to ensure that you comply with any terms and conditions of the license under which you received the platform runtime.

Product branding

The branding changes we'll described are those aspects related to the appearance of your running application. These branding elements are supplied with the org.eclipse.core.runtime.product extension point. This controls (among other things) the application's title bar, the window image, and the default application. We will describe parts of this extension point here and will return to it in the optional branding section.

The product's title bar

The product's title bar is controlled by the name attribute of the product extension. Changing the browser's plugin.xml file as highlighted below will replace the initial window title bar with your own string.

<extension
      point="org.eclipse.core.runtime.products"
      id="product">
   <product
         name="Branded RCP Browser Example"
         application="org.eclipse.ui.examples.rcp.browser.app">
      <property ...  

The image the window system associates with the product

SWT allows a set of images to be associated with a shell with the expectation that all images in the set will have the same appearance but be rendered at different sizes. These images are provided to the SWT shell which is then able to select the most appropriate one for each specific use. For example, on Windows® the smaller image (16x16) will be used for the title and task bars while the larger image (32x32) will appear in the Alt-Tab application switcher.

The comma-separated list that is set in the windowImages property should have at least one image.

Making the highlighted change to the plugin.xml file will change the icons used by the product.
<extension ...
   <product ...
      <property
          name="windowImages" 
          value="icons/alt16.gif,icons/alt32.gif"/>
      <property ...  

The name the window system associates with the product

SWT allows an internal name to be associated with a shell. This name is different from the one that appears in the shell's title bar -- its exact use varies depending on the window system. For example, on X-Window based systems such as motif this value is used to refer to the application in the .XDefaults file.

The value of the appName property should be set to something that clearly identifies your product. Its also a good idea to test your branding on a platform (e.g., motif) that is known to use this value.

<extension ...
   <product ...
      <property
          name="appName" 
          value="BrandedRCPBrowserExample"/>
      <property ...  

Setting the product's default application

The products extension is used to apply branding to your application but you must also provide an applications extension point. Among other thing this supplies the "main" to be run. For example the Eclipse SDK has one brand but contains several applications (e.g., the IDE, the ant runner, etc.) and for this specific case the IDE is the default application.

You must designate a specific application as the default application to be run when some branding is selected. This is accomplished by the application attribute in your products extension.

<extension
      point="org.eclipse.core.runtime.products"
      id="product">
   <product
      application="org.eclipse.ui.examples.rcp.browser.app"
      ...

 Testing the branding while self-hosting

In the Eclipse IDE create a new runtime-workbench launch configuration, choose the "Run a product" option, and select org.eclipse.ui.examples.rcp.browser.product from the dropdown.

By default the launch configuration loads all workspace and enabled external plug-ins which may cause problems when running your application (since several unneeded plug-ins will be included). Create a minimal set of plug-ins by choosing the "Plug-ins" tab and selecting "Choose plug-ins and fragments to launch from the list". Click on "Deselect All" and then choose the org.eclipse.ui.examples.rcp.browser plug-in. Finally click on "Add Required Plug-ins" to compute the minimal set of plug-ins required for your application.

The images referenced in this example are already in the icons/ directory of the browser plug-in so after making the changes described in this section you are ready to click on "Run" to launch your application. Look for the new window images and title.

Branding the launcher

The next step in developing your overall product brand is to change the elements that appear while launching your application. This includes aspects such as using your own splash screen and changing the icon used by the Eclipse launcher.

These changes apply to the Eclipse launcher, which is not used in self-hosting mode. That means that in order to observe these changes you will need to have your RCP application installed on your system so that you can start it directly. It also means that we will be changing your RCP application's config.ini file (in the configuration area (eclipse/configuration)) rather than any of its extension points.

Make your product active

If you haven't already done so then now is the time to edit the config.ini file so that your branding is selected when your application is launched. This is accomplished by changing the value of the eclipse.product property as shown here.

eclipse.product = org.eclipse.ui.examples.rcp.browser.product  

As described in Product branding your products extension point should point to your applications extension point. Setting the value of this property will select your branding as well as your application.

Replacing the splash screen

The splash screen (shown while the program starts) is contained in one file that is usually found in the plug-in declaring the product. It must be called splash.bmp and must be a .BMP file. There are no constraints regarding the size but for reference the standard Eclipse splash screen image is 500x330 pixels.

The splash screen is selected based on the value of the osgi.splashPath property as shown here.

osgi.splashPath = platform:/base/plugins/org.eclipse.ui.examples.rcp.browser  

When using platform: style URLs make sure that the plug-in referenced is in the plug-ins folder and that it is a sibling of the startup.jar.

To use NL'ed splash screens the locale specific images should be placed in a nl directory within the plug-in's directory. For example, a splash screen for the fr_FR locale would be placed within the plug-in's directory as nl/fr/FR, e.g.,

org.eclipse.ui.examples.rcp.browser/
  nl/
    fr/
      FR/
        splash.bmp    

Replacing the launcher's icon

Changing the icon associated with the launcher requires modification to the executable. We will also need to convert the icons into a resource that can be used by the executable.

This process varies by platform, the following sections explain the procedure for the Windows and Linux platforms. In both cases you should start by extracting the file eclipse/plugins/org.eclipse.platform.source_3.0.0/src/org.eclipse.platform_3.0.0/launchersrc.zip found in the SDK. In the following sections, we will work with the library/ directory and once we are finished we will copy the resulting executable back to the Browser application.

Creating the graphic resources for our executable

 Windows executable programs can have an associated icon(s). To create our icon we first need to replace several .BMP graphics located in the library directory. These graphics represent 16x16, 32x32 and 48x48 pixel versions of both low color and high color graphics. In the library/ directory replace the following files:

Using an appropriate graphics tool (e.g. ICONPRO provided in the MSDN), combine these graphics into a single .ICO (icon) file called eclipse.ico and replace library/win32/eclipse.ico with your new eclipse.ico file. The eclipse.ico is referenced by the file library/win32/eclipse.rc which is automatically used when the build script is run. Once the build script has finished we will have a new program executable with an associated icon.

 Linux does not directly associate an icon with an executable program however we can include an icon that users can use when associating a shortcut with the program. Use your favorite graphics editor to create an xpm graphic representing your program icon and place it into library/icon.xpm. Once we have built the executable we will copy both the executable and the .xpm file to the eclipse/ root directory of the platform runtime build.

Building the executable

Executable icon in hand, it's time to make the executable. We will continue to work with the library/ directory and once we have created our executable we will copy it to the eclipse/ root directory of the runtime platform build. The process for creating the program executable is different and a build script is provided in each subfolder to help make the process easier.

Preparing the build script

 In the library/win32 directory you will find the build script build.bat. We will need to edit this build file to point it to the location of your C compiler. To do this, simply uncomment the following lines (by removing rem) and modify MSVC_HOME to point to the root directory of your compiler installation.

rem IF NOT "%MSVC_HOME%"=="" GOTO MAKE
rem set MSVC_HOME=k:\dev\products\msvc60\vc98
rem call %MSVC_HOME%\bin\vcvars32.bat  

This script has been tested with Microsoft® Visual C/C++ Compiler 6.0 however it is possible that you may need to make additional modifications for your compiler.

 The Linux build script (build.csh) has been tested against GNU C and C++ Compiler. You typically should not need to make any changes to the Linux build script.

Running the build script

The build script takes two arguments, the filename of the executable file to create (output) and the title (name) of your program. If the program name has spaces in it (as in the example below) you will need to put double-quotes around it.

In the example below the program name RCP Browser will be shown in the task bar while the program is starting.

 On Windows you can run the build script (build.bat) as shown below. Prior to running the build script you should run once using the clean target to remove any artifacts from previous builds. This example will create an executable file named rcp browser.exe with the icon we created above.

build -output "rcp browser.exe" -name "RCP Browser"  

 On Linux you can run the build script (build.csh) as shown below. This example will create an executable file named rcp browser. On Linux an icon is not automatically associated with the executable.

csh build.csh -output "rcp browser" -name "RCP Browser"  

Replacing the existing executable

Now that you have your own executable, you can copy it to the code>eclipse/ root directory of the browser example. It is a good idea to remove the previous executable so that the user won't be confused on which to run.

 On Linux we also need to copy the icon.xpm (we created above) to the eclipse/ root replacing the one already found there.

 Start your application by running the executable you just built. Confirm that it starts properly and that your icons, splash screen, and program name are shown during the application launch process.

Optional branding

Previous sections have discussed changes that all applications will want to make in order to present a customized brand. In this section we discuss some optional aspects of branding such as customizing the about dialog, applying your own default preferences, and selecting a special presentation.

The about dialog

Both the image and the text in the main about dialog are subject to product level branding.

These values are set from properties in your products extension point as shown here

<extension ...
   <product ...
      <property
          name="aboutImage" 
          value="icons/alt_about.gif"/>
      <property
          name="aboutText" 
          value="The about dialog text can contain links such as http://www.eclipse.org."/>
      <property ...  

The absolute maximum size for an the about image is 500x330 pixels. However, the value of the about text property will only be displayed if the about image is no larger than 250x300 pixels.

Special preferences settings used by the product

Although not shown in this example it is also possible to specify a set of defaults that should be used with the product. For example, the preference settings might be used to specify an alternate presentation factory. The preferences should be stored in a file which is pointed to by the preferenceCustomization property. See Eclipse Rich Client Platform for an example.

The .eclipseproduct marker file

The branding of the application would not be complete without updating eclipse/.eclipseproduct. This marker file is a java.io.Properties format file that indicates the name, id, and version of the product. It also controls things like the default configuration area inside the user home folder, which ensure a separation of the configuration information among products.

Ensure the file exists in you eclipse/ directory and contains:

name=Branded RCP Browser Example
id=org.eclipse.ui.examples.rcp.browser.product
version=3.0.0  

Presentations

A very powerful way to supply branding to your application is to create your own presentation. Supplying your own presentationFactory allows you to change all aspects of your application's UI. You can find an example of using the R21 presentation on the Eclipse RCP page.

Intro page

Eclipse allows you to supply an extension point to provide a customized intro experience to users of your application. Explore the Eclipse help system for more information on how to use the org.eclipse.ui.intro extension.

Troubleshooting

Application "..." could not be found in the registry. The applications available are: <NONE>

Use the error log to check that all pre-requisite plug-ins were successfully resolved. The osgi.bundles property lists the plug-ins that eclipse installs and runs.

Typically only org.eclipse.core.runtime and org.eclipse.update.configurator are listed. The update configurator will discover and install all plug-ins in the plugins directory. If you aren't using org.eclipse.update.configurator then list all necessary plug-ins in the osgi.bundles property.

A typical RCP list might look like:

osgi.bundles = org.eclipse.core.runtime@2:start, org.eclipse.core.expressions, \
               org.eclipse.help, org.eclipse.jface, org.eclipse.osgi.services, \
               org.eclipse.osgi, org.eclipse.swt, org.eclipse.ui.workbench, \
               org.eclipse.ui, org.eclipse.swt.win32, org.eclipse.swt.gtk, \
               org.eclipse.swt.gtk64, org.eclipse.swt.carbon, \
               org.eclipse.swt.motif

No application id has been found.

This happens when eclipse cannot find the application to run. This could happen if the product cannot be found or the default application specified in the product extension is not found. Check for typos in both these ids.

Application "..." could not be found in the registry. The applications available are: ...

This is most likely caused by a typo in the application id. If you are using your product's default application then check the application attribute in the product extension. Otherwise check the eclipse.application property in the config.ini file. The value must match the id defined in some application extension.

No branding in application

This happens when the product cannot be found check the config.ini file for typos in the value of eclipse.product.

Changes ignored

If changes to plugin.xml or plugin.properties are not recognized then try running once with the -clean command line option. This will remove stale cache files to ensure they are regenerated from the newest information. This option is only required during development when the plug-in manifest is changing it will not be needed when your product is deployed.

Conclusion

We have shown how to replace the basic units of branding to make your product look like your own. This included such items as the splash screen, about dialog and the icon and name associated with the launcher.

Other Resources

From the Eclipse Help System

From the "Official Eclipse FAQs" book

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.