Brand your Eclipse RCP applications
How to understand and use Eclipse Production Configuration
Xing Xing Li (lixx@cn.ibm.com), Software Engineer, IBM
Ying Xi Zhao (lois_alert@sohu.com), Software Engineer
08 May 2007
查看原文请点此处
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.
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:
- JRE V1.5.0 or later; Eclipse requires the Java Runtime Environment to operate
- Eclipse Platform or IBM Rational Software Development Platform V7.X
- 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.
- From the Eclipse menu, select File > New > Project... > Plug-in Development > Plug-in Project and click Next.
- In the Plug-in Project wizard page, input
com.example.zyx
as project name and click Next.
- 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.
- 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
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
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
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
The following table provides the description of these resources.
Table 1. Resource description
File/folder name |
Function |
splash.bmp |
Comes up when product is launching |
plugin_customization.ini |
Defines default preference values |
plugin_customization.properties |
Contains externalized strings for plugin_customization.ini file |
plugin.properties |
Contains translating values from plugin.xml file |
intoContent.xml |
Configures welcome page |
content |
Contains welcome page resources |
icon |
Contains useful icons, etc. |
image |
Contains useful images resources, such as window images, etc. |
about.html |
Provides 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
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
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
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
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 property |
Value |
Usage |
Size |
16x16 pixels |
When 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 pixels |
This is used on the left side of the Start menu in Windows XP. |
|
32x32 pixels |
When the view is Icon view mode, this is used for Windows desktop and Windows Explorer. |
|
48x48 pixels |
When the view is Large Icons mode, this is used. |
Color depth |
4-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
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
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
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
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
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
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
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
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
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
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
Double-click FrogAcrossRiver.exe and it launches your RCP product successfully.
Troubleshooting
- 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.
- 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
Description |
Name |
Size |
Download method |
Sample jar files |
os-eclipse-brand.example.zyx.zip |
45KB |
HTTP |
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.
About the authors
|
|
|
Xing 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 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.
|