Tutorial

Eclipse was originally started as a modular IDE application. In 2004 the Eclipse 3.0 version was released which supported the re-use of the Eclipse platform to build stand-alone applications based on the same technology as the Eclipse IDE.

At this point the term Eclipse RCP was coined. RCP stands for Rich Client Platform and indicates that the Eclipse platform is used to created feature-rich standalone applications.

Eclipse applications are built upon a plug-in architecture. Plug-ins are software components. Plug-ins are the smallest deployable and installable components of Eclipse.

A plug-in is a collection of files and a configuration file (MANIFEST.MF) which describes the plug-in and its dependencies.

This plug-in architecture allows Eclipse based applications to get extended by third parties.

The Eclipse 4 platform extends the concept of building Eclipse based applications with new technologies, for example with dependency injection and declarative styling via CSS files.

The Eclipse platform is the basis for the most successful Java IDE and therefore very stable and broadly used. It uses native UI components to provide as much as possible a native look and feel and with its strong modularity approach allow to design component based systems.

Companies like IBM and Google use the Eclipse framework heavily for their products and therefore ensure that Eclipse is flexible, fast and continues to evolve.

The Eclipse platform also fosters a large community of individuals which provide support, information and extensions to the Eclipse framework. Tapping into this Eco-system allows you to find required resources and information.

An Eclipse application consists of individual software components.

The Eclipse IDE is a collection of specific software components. The components of the Eclipse IDE are primarily the following.

An Eclipse based application (RCP) uses only parts of these components. An Eclipse application typically uses:

For a headless Eclipse based applications (without UI), only the runtime is necessary.

The OSGi runtime provides the framework to run the modular application. SWT is the standard UI component library used by Eclipse and JFace provides some convenient API on top of SWT. The workbench provides the framework for your application. The workbench is responsible for displaying all other UI components.

The basis for the Eclipse architecture is the OSGi specification. The OSGI specification defines a modularity layer.

Equinox is the reference implementation of OSGi and is used by the Eclipse platform.

A software component in Eclipse is called "Plug-in". A software component in OSGi is called "bundle". Both terms can be used interchangeably.

A plug-in defines:

OSGi defines also services. Services are dynamic components.

An Eclipse plug-in has two main configuration files.

The following assumes that you have already Java installed. If not please Google for "How to installed Java for MyOS", while replacing "MyOS" with the operating system your are using.

Browse to Eclipse download site and download the package "Eclipse for RCP and RAP Developers". Extract the download to your harddisk. Avoid having special characters or spaces in the path to Eclipse.

In case you have downloaded the Eclipse Java IDE (or any other non RCP flavor) distribution you can use the Eclipse Update Manager to install the plug-ins required for RCP development.

Install General Purpose Tools → Eclipse Plug-in Development Environment → Eclipse RCP Plug-in Developer Resources → → from the Eclipse update site for your release. You may have to remove the "Group items by category" flag to see all available features.

The following explains how to create a simple RCP application. In Eclipse select File-> New Project. From the list select "Plug-In Project".

Give your plugin the name "de.vogella.rcp.intro.first" .

Press "Next" and make the following settings. As we are going to develop an RCP application, select "Yes" at the question "Would you like to create a rich client application".

Press next and select the template "Hello RCP" .

Press next and select "Add branding" and press Finish.

As a result a project with the following project structure will be created. Have a look at the different files especially the Java files to get a first feeling about the project structure.

While it is possible in Eclipse 3.7 to start an application directly, it is consistent to create a product to start the application. Therefore we will not run the application directly but create first an product.

This is also in line with Eclipse 4.x. In Eclipse 4.x you cannot start an Application directly, you always need a product.

Right-click on your "de.vogella.rcp.intro.first" project and select New → Product Configuration .

Name your product configuration "de.vogella.rcp.intro.first.product". Select "Create a configuration file with basis settings". Press finish.

Open the file de.vogella.rcp.intro.first.product" and select the "Overview" tab. Enter the name "DeployTest". Leave the ID empty. The name is the default which will be displayed in the title of the window, the ID is not required and entering it leads sometimes to problems. You can change this default name in class ApplicationWorkbenchWindowAdvisor in the method preWindowOpen() via the configurer.setTitle("New title");)

Press "New" in the "Product Definition" part and select the application of your plugin "de.vogella.rcp.intro.first.application".

As a result the "Product Definition" part of the overview tab should now be filled with your selection.

The product identifier is stored as the extension "org.eclipse.core.runtime.product" in the file "plugin.xml".

Switch to the "Dependencies" Tab and click "Add". Add your application plugins. Press the button "Add Required Plug-ins" to add all dependent plugins to your product. Save.

Optional create a "splash.bmp" via your favorite graphics tool and save it in the project with contains the product. Also add a message and a progress bar to your splash screen.

Change the launch name to "myapplication".

On the overview tab press synchronize and then press "Launch an Eclipse application". Make sure your product starts.

The result should look like the following:

Congratulations, you have created and started your first RCP application.

A product configuration (short: product) defines all resources that goes with your Eclipse application , e.g. icons, splash screen, external jars, other plugins, etc. The product is a development artifact which describes the content of your application and is not required at runtime.

A product always points to one Application class. This Application class must implement the IApplication interface.

You define your product configuration via a ".product" file. A product configuration file can be created via a right-click on your project and select New → Product Configuration.

This configuration file contains all the information about required plug-ins, configuration files, resources etc. The configuration file is used for exporting / creating your product.

It is recommended to leave the product ID blank, because the product export may have issues if the product ID is the same as a plug-in ID.

On the overview tab of your product you can start the product and select synchronize. Synchronize will align your product artifacts with the launch configuration.

A product configuration file can either be based on plug-ins or features. Features are groupings of other features and plug-ins. This setting is done on the overview tab.

On the dependency tab you can maintain the plug-ins your products consists of. A product will not do any automatic dependency resolution for you. If you add a plug-in to your product and want to add the dependencies, press the dependency button.

The tab "Splash" allows you to specify the plug-in which contains the splash screen. You need to put the file "splash.bmp" into the project directory. The name and the format is hard-coded in Eclipse and cannot be changed.

You can also configure the launcher name and icon for your exported product. The launcher is the executable program that is created during the deployment of the product. Per default a launcher specific to your platform is created. For example "eclipse.exe" on the Windows platform. The launcher will also get an "eclipse" icon. To change the name and the icon select the launcher tab of your product configuration.

Here you can specify the name of the application and the icon which should be used. Make sure the size of the icons is correctly maintained otherwise Eclipse will not use these icons.

In the launcher section you can also specify parameters to your Eclipse program or JVM arguments.

As described earlier the WorkbenchWindow and the WorkbenchPage represent the visual and inner part of the graphical user interface.

The WorkbenchPage contains Parts, which can be Views or Editors.

Views are used to display information in an RCP application; they can also be used to change data. Views extend the abstract class ViewPart. Editors extend the abstract EditorPart. Both extend WorkbenchPart.

An editor typically requires that the user explicitly select "save" to apply the changes to the data while a view typically changes the data immediately. All editors are opened in the same area. Via the perspective you can configure if the editor area is visible or not.

Views and Editors are defined via extension points in the file "plugin.xml" via the tab "Extensions".

Views are defined via the extension point "org.eclipse.ui.views" and Editors via the extension point "org.eclipse.ui.editors".

Views must implement the createPartControl() and setFocus() methods.

createPartControl() is used to create the UI components of the View.

createPartControl() will get as parameter a Composite which can be used to construct the user interface. This composite has per default a FillLayout layout manager assigned to it. This layout manager assigns the same space to all components equally.

setFocus() must set the focus to a specific UI component.

A Perspective describes a certain configuration of Views and Editors.

A Perspective is defined via "org.eclipse.ui.perspectives". The WorkbenchParts which are part of a Perspective are either defined via a Java class defined in the extension point "org.eclipse.ui.perspectives" or via the "org.eclipse.ui.perspectiveExtensions".

				
public class Perspective implements IPerspectiveFactory {
	public void createInitialLayout(IPageLayout layout) {
		layout.addView("de.vogella.rcp.intro.first.MyView", IPageLayout.TOP,
				IPageLayout.RATIO_MAX, IPageLayout.ID_EDITOR_AREA);
	}
}
			

layout.addView() adds a view to the perspective. You can also add placeholders for views via the layout.addPlaceholder() method call. This methods accepts wildcards and a View with a matching ID would open in this area.

You can also group view via a IFolderLayout which can be created via layout.createFolder() call and by adding Views to this folder via the addView(id) method on IFolderLayout.

The following will explain how to add views to your application. We will continue to use the RCP project "de.vogella.rcp.intro.first".

Add the extension "org.eclipse.ui.views" to your plugin. Select ""plugin.xml" and the tab "Extentions". Right mouse-click on your new view extension and select New -> View. Maintain the id "de.vogella.rcp.intro.view.MyView" and the class "de.vogella.rcp.intro.view.MyView".

Create the class "MyView" by clicking on the "class" hyperlink and maintain the following code. Afterwards your view is ready to be used.

				
package de.vogella.rcp.intro.first;

import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.part.ViewPart;

public class MyView extends ViewPart {

	@Override
	public void createPartControl(Composite parent) {
		Text text = new Text(parent, SWT.BORDER);
		text.setText("Imagine a fantastic user interface here");
	}

	@Override
	public void setFocus() {
	}
}

			

You have to add the view to your perspective. Add the extension "org.eclipse.ui.perspectiveExtensions" to your plugin.

Right click "*(perspectiveExtension)" -> New -> view". Maintain your view id "de.vogella.rcp.intro.first.MyView". Make the view relative to "org.eclipse.ui.editorss" which is the currently invisible editor area and make the view use all the space by selecting the maximum ratio of "0.95f".

Run your application to see the result.

I personally prefer extension points over code. But instead of using the extension point "org.eclipse.ui.perspectiveExtensions" you could also add the view via code to the perspective. For this modify "Perspective.java" to the following.

				
package de.vogella.rcp.intro.view;

import org.eclipse.ui.IPageLayout;
import org.eclipse.ui.IPerspectiveFactory;

public class Perspective implements IPerspectiveFactory {

	public void createInitialLayout(IPageLayout layout) {
		layout.addView("de.vogella.rcp.intro.first.MyView", IPageLayout.TOP,
				IPageLayout.RATIO_MAX, IPageLayout.ID_EDITOR_AREA);
	}
}

			

If you develop Eclipse plug-ins, you reuse components of the Eclipse Platform for example SWT or JFace.

The question is: how can you control which version of a specific plug-in is used?

Per default these plug-ins are sourced directly from your Eclipse IDE.

This is not an ideal approach, as this makes you dependent on your version of the Eclipse IDE. This can lead to problems, if developers are using different versions of Eclipse. It also makes it difficult to upgrade these plug-ins for everyone at the same time.

If you follow this approach you would also need to install every plug-in required for your product either in your workspace or in your Eclipse IDE.

The last problem with this approach is that you might unintentionally add plug-ins from the Eclipse IDE to your product.

Via a Target Platform you define the set of plug-ins which are available for development. For example you define which version of the SWT and JFace plug-in is part of your target platform.

This makes you independent from the Eclipse IDE you are using. Developers with different versions of Eclipse will compile their work against the same set of plug-ins.

A Target Platform is defined via a ".target" file. This target file defines the list of plug-ins and features. You typically share this target file between different developers to ensure that everyone is using the same basis for development.

The most effective way of defining your Target Platform is to use (Eclipse p2) update sites. These are the same type of update sites which you use if you want to install a new set of plug-ins. If the content in the update site defined by your target platform is changed, your local set of plug-ins can also be updated.

It is also possible to define your target platform based on a file system, but this is not as flexible and therefore should be avoided.

A Target Definition file can be created via File → New → Other → Plug-in Development → Target Definition.

You can add new locations via the "Add" button in the location section. To add an Eclipse p2 update site, select "Software Site" and specify the URL.

After you have defined your Target Definition file, you can set it as target in your Eclipse IDE via the "Set as Target Platform" button.

You can switch the target platform in the Eclipse Preferences. Select Window → Preferences → Plug-in Development → Target Platform

To load an image from your plug-in your use the AbstractUIPlugin.

				
AbstractUIPlugin.imageDescriptorFromPlugin(“YourPluginId”,”/icons/your.gif”).createImage();
			

Alternatively you could load the framework directly.

				
Bundle bundle = FrameworkUtil.getBundle(this.getClass());
URL url = FileLocator.find(bundle, new Path("icons/alt_window_32.gif"), null);
Image image = ImageDescriptor.createFromURL(url).createImage();
			

To remember the user's layout and window size for the next time you start your application, add configurer.setSaveAndRestore(true); to the initialize method of ApplicationWorkbenchAdvisor.

				
package addactiontoview;

import org.eclipse.ui.application.IWorkbenchConfigurer;
import org.eclipse.ui.application.IWorkbenchWindowConfigurer;
import org.eclipse.ui.application.WorkbenchAdvisor;
import org.eclipse.ui.application.WorkbenchWindowAdvisor;

public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor {

	private static final String PERSPECTIVE_ID = "AddActiontoView.perspective";

	public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(
			IWorkbenchWindowConfigurer configurer) {
		return new ApplicationWorkbenchWindowAdvisor(configurer);
	}

	public String getInitialWindowPerspectiveId() {
		return PERSPECTIVE_ID;
	}

	@Override
	public void initialize(IWorkbenchConfigurer configurer) {
		super.initialize(configurer);
		configurer.setSaveAndRestore(true);
	}

}

			

Eclipse has a pre-defined command to reset the perspective. See Eclipse Commands .

The status line in an RCP application can be used to give the user some information about the running application. The shared message area can be used by all parts of the application to write messages to this area. The whole RCP application has access to the information in the shared status line therefore the information in the shared status line might be overwritten.

To show the status line in your RCP application use the "ApplicationWorkbenchWindowAdvisor" and set the status line visible in the method preWindowOpen().

				
public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor {
    //...
    @Override
    public void preWindowOpen() {
    	// ....
        configurer.setShowStatusLine(false);
    }
}

			

The following writes a text to the status line from a view.

				
IStatusLineManager manager = getViewSite().getActionBars().getStatusLineManager();
manager.setMessage("Information for the status line");
			

From an editor you can access the status line via the following:

				
IEditorPart.getEditorSite().getActionBars();

			

In the file plugin.xml (tab dependencies) you define on which plugins your plugin depends. Of course you should only define the required plugins here. You can check if you have any dependency maintained which is actually not used, by selecting Dependency Analysis -> Find unused dependencies.

Eclipse RCP applications save configuration files in the folder ".metadata". In the standard settings the Eclipse RCP installation directory will be used for this folder. If several users are using the same installation folder, then you should supply the parameter "-data" to specify an alternative location. If you specify the value "@user.home/applicationname" the configuration will be saved in a user specific folder.

Source Code of Examples

Using Eclipse IDE (Kindle Book)

Eclipse Plug-in Development FAQ

SWT Graphics

Eclipse RCP Training (German) Eclipse RCP Training with Lars Vogel

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java and compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put everything you have under distributed version control system