Brand your Eclipse RCP applications

How to understand and use Eclipse Production Configuration

This article provides step-by-step guidelines on how to package and manage a Rich Client Platform (RCP) application as a product with your own branding by using Eclipse's Production Configuration and PDE. Besides common concepts such as splash screen and an icon file's color and size, this article also introduces advanced branding aspects of production configuration: the RCP executable file and its configuration file, progress bar and message, RCP window image, About dialog and welcome page (i.e., introduction). With this article, you can grasp the main skills on encapsulating your RCP application as a distributable product, independent of Eclipse platform.

Xing Xing Li (lixx@cn.ibm.com), Software Engineer, IBM

Xing Xing LiXing Xing Li joined the IBM China Software Development Lab in Beijing China in 2004 as a software engineer for IBM Lotus. He focuses on software development and testing on Eclipse platform and Java technologies. He is also interested in user interface design, design pattern and algorithmic research. He received his master's degree in computer science from Chongqing University.



Ying Xi Zhao (lois_alert@sohu.com), Software Engineer, MichaelDKelly.com

Ying Xi ZhaoYing Xi Zhao has contributed to IBM Lotus products since 2006. She is a software engineer at Wistron Information Technology and Services Corp., China. She specializes in Java and Eclipse-based software development and testing, as well as other open source technologies. She comes from JiLin province of China, and likes to read books, climb hills, take photos, and maintain collections in her spare time.



08 May 2007

Also available in Chinese Japanese

Before Production Configuration was introduced in Eclipse V3.1, RCP developers confronted the problem of how to effectively and efficiently package, and deliver their RCP projects with the required plug-ins. This problem, in fact, is a consumption issue because it essentially determines the distribution and usability of their software. Thanks to Eclipse V3.1's new Production Configuration feature, you can now wrap their applications with dependencies and branding elements easily. This article details how to leverage Eclipse Product Configuration with a sample RCP application: a game called Frog Across River.

To get the most out of this article, you need an Eclipse development environment and the sample code. If you don't have Eclipse already, download the following:

  1. JRE V1.5.0 or later; Eclipse requires the Java Runtime Environment to operate
  2. Eclipse Platform or IBM Rational Software Development Platform V7.X
  3. The sample code in the Download section

Prerequisite: An RCP application

The prerequisite of Eclipse Product Configuration is an existing RCP application. You will need it as the bootstrap entry of your product. In this section, you will develop a game of Frog Across River as an RCP application using the following instructions. This RCP application is a plug-in project that will extend the org.eclipse.core.runtime.applications extension and play the entry role of your product. Alternately, you can skip through this section by importing the whole project by downloading the attached (see Download) to get a sample RCP application for later scenarios.

Create a sample RCP plug-in

First, we generate a plug-in project following these steps. Launch Eclipse, shift to the plug-in development perspective by selecting Window > Open Perspective > Other... > Plug-in Development.

  1. From the Eclipse menu, select File > New > Project... > Plug-in Development > Plug-in Project and click Next.
  2. In the Plug-in Project wizard page, input com.example.zyx as project name and click Next.
  3. In the Plug-in Content wizard page, accept all default settings and click Yes for the "Would you like to create a rich client application?" option, then click Next.
  4. In the Templates wizard page, select Hello RCP template and click Finish. Afterward, you will find a project named com.example.zyx in the workspace.

Import the RCP game source code

Copy all Java source files (.java files) from com.example.zyx.zip to the workspace, replacing the existing ones:

  • Application.java
  • ApplicationActionBarAdvisor.java
  • ApplicationworkbenchAdvisor.java
  • ApplicationWorkbenchWindowAdvisor.java
  • Perspective.java
  • GameView.java

This RCP project will create the Frog Across River game in a GUI view that enables mouse and keyboard input on the menu bar and canvas. Its design architecture is shown in Figure 1.

Figure 1. Class diagram of RCP application
Class diagram of RCP application

Among them, Application.java must implement the IPlatformRunnable interface because the plugin.xml file has extended the extension point of org.eclipse.core.runtime.applications. That means you should implement the run() method of IPlatformRunnable, which is responsible for creating the SWT display and starting up a workbench.

Listing 1. Application.java
public class Application implements IPlatformRunnable {
    public Object run(Object args) throws Exception {
        ...
        int returnCode = PlatformUI.createAndRunWorkbench(display, 
                         new ApplicationWorkbenchAdvisor());
        ...
    }
}

ApplicationActionBarAdvisor.java is used to create and display menu bar.

Listing 2. ApplicationActionBarAdvisor.java
public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
    ...
    private IWorkbenchAction exitAction;
    private IAction gameAction;
    ...
    protected void fillMenuBar(IMenuManager menuBar) {
	IMenuManager viewMenu = new MenuManager("&Game","Game");
	menuBar.add(viewMenu);
         viewMenu.add(gameAction);
         viewMenu.add(exitAction);
    }
}

GameView.java is the core of this RCP game. It loads images, renders the display, responds to user actions (mouse and keyboard events), and controls the whole process of the game.

Double-buffer technology is applied to avert screen flicker and flash during animation. Why? When you instruct JVM to display an animation, JVM will clear the screen, show the window, paint the screen, and show it again. That degrades your application's appearance. Double-buffering boosts performance by painting an off-screen image, then dumping it to the display.

Listing 3. GameView.java
public class GameView extends ViewPart {
    ...
    public void createPartControl(final Composite parent) {
    ...
    canvas.addMouseListener(new MouseAdapter() {
        public void mouseDoubleClick(MouseEvent e) {
	
	}
    });
    canvas.addKeyListener(new KeyAdapter() {
	public void keyPressed(KeyEvent e) {
	...
    }
    canvas.addPaintListener(new PaintListener() {
	public void paintControl(PaintEvent event) {
            final Image image = new Image(parent.getDisplay(), canvas.getBounds());
            final GC gcImage = new GC(image);
            ...
            event.gc.drawImage(image, 0, 0);
            ...
}

Copy the code list below into plugin.xml file because your RCP game will show up a view as the GUI to interact with users.

Listing 4. plugin.xml
<extension point="org.eclipse.ui.views">
      <category id="com.example.zyx.browser"
                name="Browser Example"/>
      <view id="com.example.zyx.GameView"
            name="Browser"
            icon="icons/window16x16.gif"
            class="com.example.zyx.GameView"
            category="com.example.zyx.browser"/>
</extension>

Launch the RCP game in Eclipse

To execute the RCP game application in Eclipse, switch to the Overview tab of plugin.xml and click Launch an Eclipse application. A new Eclipse application launch configuration will be created for you, and you will find the execution result of your RCP game, as shown in Figure 2.

Figure 2. Execution of the sample RCP application
Execution of the sample RCP application

Create your product configuration

You will create a Product Configuration file (.product) to wrap up the Frog Across River RCP application as a product. You can locate it in any project or folder.

To generate a Product Configuration file, select File > New > Other > Plug-in Development > Product Configuration, then click Next. When the Product Configuration wizard page appears, select com.example.zyx plug-in project as its parent folder, input myProduct.product as its file name, select "Create a configuration file with basic settings" and click Finish (see Figure 3).

Figure 3. Wizard to create new Product Configuration
Wizard to create new Product Configuration

Configure

In this section, we introduce how to define and customize the product published with your RCP application after you create your .product file. You need to import some files and folders into your plug-in project from com.example.zyx.zip before you set up the Product Configuration. They are listed in Figure 4.

Figure 4. Imported resources
Imported resources

The following table provides the description of these resources.

Table 1. Resource description
File/folder nameFunction
splash.bmpComes up when product is launching
plugin_customization.iniDefines default preference values
plugin_customization.propertiesContains externalized strings for plugin_customization.ini file
plugin.propertiesContains translating values from plugin.xml file
intoContent.xmlConfigures welcome page
contentContains welcome page resources
iconContains useful icons, etc.
imageContains useful images resources, such as window images, etc.
about.htmlProvides information about host plug-in; a plug-in must contribute this file

Overview tab

First, click the Overview tab (see Figure 5). You will set up the Product Definition here. The product definition consists of Product Name, Product ID, and an Application associate with the Product ID. What's more, it is specified whether the product configuration unit is based on plug-in or feature.

Figure 5. Overview tab
Overview tab

Product Name defines the name of the product, which will be shown in the title bar. Input %productName in the Product Name text field, which will automatically refer to the values in plugin.properties file according to the locale. Product ID defines the product ID and it associates with the Application ID. Click New... to the right of Product ID. When the Product Definition window pops up, choose com.example.zyx as the Defining Plug-in, then select com.example.zyx.application as its associated application, and use product as its product ID. Click Finish to return to the Overview tab. Select plug-ins radio button in the "The product configuration is based on" section.

You can see the product name in the title bar when you launch the product, as shown below.

Figure 6. Product name in title bar of my product
Product name in title bar of my product

Configuration tab

Click the Configuration tab. You will define the elements in you product and the configuration file. The "Plug-ins and Fragments section" lists all plug-ins and fragments that will be packaged in your product.

Figure 7. Configuration tab
Configuration tab

Click Add... to the right of the Plug-ins and Fragments list, then select the com.example.zyx plug-in, and click OK. Click the Add Required Plug-ins button, then all required plug-ins and fragments are added. The "Configuration File" section is used to set up the product runtime information. This file must be named config.ini. You can accept its default setting, which will generate a default config.ini file in configuration folder when the product is exported. The following gives a sample of the file's content.

Listing 5. Content of config.ini
#Product Runtime Configuration File
osgi.splashPath=platform:/base/plugins/com.example.zyx
eclipse.product=com.example.zyx.product
osgi.bundles=org.eclipse.equinox.common@2:start,org.eclipse.update.configurator@3:start,
org.eclipse.core.runtime@start
osgi.bundles.defaultStartLevel=4

The first line determines the location of splash screen, which will be displayed when product launches. The second line defines the product name.

In the last two lines, StartLevel is used by the product to launch plug-ins after they have been successfully installed and resolved. In other words, StartLevel defines the startup sequence of these core plug-ins. A start level is defined as a non-negative integer. The products will launch plug-ins with Start Level 0. Afterward, it's the turn of all plug-ins with start level 1. This progress won't end until it reaches its designated start level: the defaultStartLevel or the osgi.startLevel. In this sample config.ini file, the defaultStartLevel is 4. The default value for the osgi.startLevel property is 6.

Launcher tab

Click the Launcher tab, where you will set the Program Launcher and Launching Arguments.

Figure 8. Launcher tab
Launcher tab

Program Launcher is used to specify launcher name and launcher icons, in the form of an .exe file for Windows® to launch your product after you have exported it. Input FrogAcrossRiver in the Launcher Name text field. Click the radio button Use a single ICO file containing 7 images as specified above, then click Browse... and navigate to select the 7Images.ico file in the icons folder. You can generate and use your own icon file or just leverage BMP images by clicking Specify separate BMP images.

An .ico file is a container that includes required image files with different size and color modes for its host application. Windows selects the image it needs to use, based on the user's display settings. If the icon does not contain the appropriate size or color mode, Windows will take the closest size and resolution, and render the icon to suit.

Table 2. Icon properties
Icon propertyValueUsage
Size16x16 pixelsWhen the view is Detail or Small Icons mode, it's used on the top left-hand corner of the program window, the Windows Task Bar, the Start, and in the Windows Explorer or My Computer.
24x24 pixelsThis is used on the left side of the Start menu in Windows XP.
32x32 pixelsWhen the view is Icon view mode, this is used for Windows desktop and Windows Explorer.
48x48 pixelsWhen the view is Large Icons mode, this is used.
Color depth4-bit (16 colors)Low quality, used in safe mode.
8-bit (256 colors)Medium quality, used with display color depth of 16-bit or higher.
32-bit (24-bit full colors with 8-bit alpha)High quality with smooth anti-aliased edges and optional translucent drop shadows; supported in Windows XP.

Launching arguments provides the product with the default program arguments and VM arguments. In its way, an .ini file with the same name as the launcher mame will be generated in the root of the exported folder to record these arguments. Input -console in the Program Arguments text field, which will open a console window when your product is launched. After you export the product, go to the exported folder, you can find the .exe and .ini files as shown below.

Figure 9. Executable file and config file
Executable file and config file

Splash screen

A splash screen will appear when the product launches. This file must be located in the root folder and be named splash.bmp. Otherwise, the product will not find it at runtime.

Figure 10. Splash screen configuration in Branding tab
Splash screen configuration in Branding tab

Click Browse... on the right of Plug-in test field and select the plug-in project where the splash file resides. Progress bar and Progress message are used to indicate the process status on the splash screen. Add the following value into the plugin_customization.ini file.

org.eclipse.ui/SHOW_PROGRESS_ON_STARTUP=true

Next, add the following property to the product extension section of the plugin.xml file.

<property name="preferenceCustomization" value="plugin_customization.ini">   
</property>

Then select Add a progress bar. Input 0 and 280 for x-offset and y-offset, and input 455 and 15 for width and height. Then select Add a progress message. Input 7 and 220 for x-offset and y-offset, and input 441 and 20 for width and height. Select your favorite color in Text Color for the progress message. When you launch the product, you can see the splash screen come up, and the progress bar and progress message appear.

Figure 11. Progress bar and progress message at the product's start up
Progress bar and progress message at the product's start up

Window images

Images for your application window are configured in this section (see Figure 12). These images must be in GIF format. An image with a size of 16x16 appears in the upper-left corner of the window and task bar. A 32x32 image appears in the Alt+Tab application switcher.

Figure 12. Window image configuration in Branding tab
Window image configuration in Branding tab

With the Browse... button, define the 16x16 and 32x32 images you want from your project's icon folder. Then go to the plugin.xml file to verify your configuration with following declaration:

<property name="windowImages" value="icons/alt_window_16.gif,icons/alt_window_32.gif">
</property>

After you launch the product, you will see the images is displayed in Figure 13.

Figure 13. 32x32 image in Alt+Tab application switcher
32x32 image in Alt+Tab application switcher

About dialog

The About dialog consists of the about image rendered on the left and the about text briefly introducing your product. You will manage these two items in this section.

Figure 14. About dialog configuration in Branding tab
About dialog configuration in Branding tab

Click Browse... to the right of Image text field and select a GIF file from the icon folder.

There are two ways to define the about text. One is to directly input the text in the Text field; the other is to define a key and value pair in the plugin.properties file and refer to the key in the Text field. As you will leverage the second one, just input %productBlurb in the Text field as shown in Figure 14. productBlurb is the key defined in the plugin.properties file, as shown below.

Listing 6. plugin.properties
pluginName=Frog Across River
providerName=Xing Xing Li and Ying Xi Zhao
productName=My Product
productBlurb=My Product based on Eclipse Platform\n\
\n\
Version: 1.0.0\n\
Build id: M20061124-1422 \n\
\n\
Welcome to my Product based on Eclipse Product Configuration. \n\
A RCP game is encapsulated in it with customized branding elements.\n\
\n\
This product is developed by Xing Xing Li and Ying Xi Zhao \n\
(c) Copyright by authors. All rights reserved\n\

You need to add an action so that the menu item for the About dialog will appear in the menu bar of your product, such as Help > About. Open the ApplicationActionBarAdvisor.java file and remove the comment tags to activate the following code.

Listing 7. ApplicationActionBarAdvisor.java
public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
    ...
    private IWorkbenchAction aboutAction;
    protected void makeActions(final IWorkbenchWindow window) {
        ...
	aboutAction = ActionFactory.ABOUT.create(window);
	register(aboutAction);
        ...
    }
    protected void fillMenuBar(IMenuManager menuBar) {
	//Help
	MenuManager helpMenu = new MenuManager("&Help",IWorkbenchActionConstants.M_HELP);
	menuBar.add(helpMenu);
	// About > Help
	helpMenu.add(new Separator());
	helpMenu.add(aboutAction);
        ...
    }
}

After you launch your product and select Help > About, the About dialog will appear.

Figure 15. About dialog sample
About dialog sample

Welcome page

A welcome page is used to introduce the product information, which is especially helpful for new users. You can depict all features, usage, and tips of your product via the welcome page.

Figure 16. Welcome page configuration in Branding tab
Welcome page configuration in Branding tab

To enable a welcome page in your product, you will extend two extensions: org.eclipse.ui.intro and org.eclipse.ui.intro.config. Add the following code into the plugin.xml file.

Listing 8. Intro configuration in plugin.xml
<extension
         point="org.eclipse.ui.intro">
         <intro
               class="org.eclipse.ui.intro.config.CustomizableIntroPart"
               icon="icons/alt_window_16.gif"
               id="com.example.zyx.intro">
      </intro>
      <introProductBinding
            introId="com.example.zyx.intro"
            productId="com.example.zyx.product">
      </introProductBinding>
   </extension>
<extension
         point="org.eclipse.ui.intro.config">
      <config
            content="introContent.xml"
            id="com.example.zyx.configId"
            introId="com.example.zyx.intro">
            <presentation
               home-page-id="root">
            <implementation
                  kind="html"
                  os="win32,linux,macosx">
            </implementation>
         </presentation>
         </config>
   </extension>

Next, add an action in menu bar by selecting Help > Welcome. Open the ApplicationActionBarAdvisor.java file again and remove the comment tag of the following code.

Listing 9. ApplicationActionBarAdvisor.java
public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
    ...
    private IWorkbenchAction introAction;
    protected void makeActions(final IWorkbenchWindow window) {
         ...
	introAction = ActionFactory.INTRO.create(window);
	register(introAction);
    }
    protected void fillMenuBar(IMenuManager menuBar) {		
	...
	helpMenu.add(introAction);
         ...
    }
}

You will see the following welcome page when you launch your product.

Figure 17. Welcome page sample
Welcome page sample

Publish Your RCP product

Test before publishing

Go back to the Overview tab and find the Testing section. When you have changed the product name, window images, about image and about text, etc., click Synchronize link to reflect your changes to plugin.xml to ensure that the plug-in manifest is up to date. Click Launch the product to test your product before it's exported.

There is an example of how the Synchronize link works. Change the product name from %productName to my product, then click Synchronize. Go to the plugin.xml file and verify whether the product name value ws changed to my product. After that, change it back to %productName and click Synchronize, then click Launch the product, and your product will launch.

Export product

Go to the find Exporting section of the Overview tab, where there is a link to export your product. Click the Eclipse Product export wizard. In the export dialog that pops up, specify MyProduct as the Root directory and C:\export as the destination directory.

After clicking Finish, verify the export result by navigating to the C:\export\MyProduct directory. You will find the FrogAcrossRiver.exe and FrogAcrossRiver.ini files in which your launching arguments are recorded. You will also verify that the icon of the FrogAcrossRiver.exe file is what you desire.

Figure 18. Exported RCP product in file system
Exported RCP product in file system

If you have installed JRE, double-click the FrogAcrossRiver.exe to launch your product.

Congratulations! You configured and published your RCP application as a product successfully.

JRE

This tip can help you publish your product on a non-JRE OS: Just find a platform with JRE installed, copy its JRE directory into the root folder of your exported product, as shown below.

Figure 19. JRE added to exported RCP product
JRE added to exported RCP product

Double-click FrogAcrossRiver.exe and it launches your RCP product successfully.


Troubleshooting

  1. You will be notified if your .ico file doesn't include the required image files in the specified sizes or color depths with the error message: [Program Launcher] The launcher may not get branded correctly, .ico file is missing its image. Similarly, you will get the following warning message if you specified an invalid image in the .product file: [About Dialog] Image: path/ImageName — is not a path to a valid file.
  2. If you add -clean in Program Arguments and launch the product from an exported folder, you will not see the splash screen. However, you can see it when launched from the Launch the product link.

Summary

This article has shown how to create and pack your branded Eclipse product by leveraging Eclipse's Product Configuration and PDE. Although you can do this using a script, we have demonstrated a more effective and efficient way to produce the product where you can configure and manage all branding information and elements. Most importantly, this article has shown the possibilities of an RCP world with the aid of the Eclipse Production Configuration feature.


Download

DescriptionNameSize
Sample jar filesos-eclipse-brand.example.zyx.zip45KB

Resources

Learn

Get products and technologies

Discuss

  • Learn more about RCP from the Eclipse Foundation's Official Eclipse FAQs.
  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=216839
ArticleTitle=Brand your Eclipse RCP applications
publish-date=05082007