Eclipse Rcp Tutoriallars Vogel

by Lars Vogel

Tutorial

327

Lars Vogel

Version 7.0

Copyright © 2007, 2008, 2009, 2010, 2011, 2012 Lars Vogel

08.05.2012

Revision History

Revision 0.1 - 0.7 14.08.2007 - 03.09.2007 LarsVogel

Eclipse RCP with Eclipse 3.3

Revision 0.8 - 7.0 03.11.2008 - 08.05.2012 LarsVogel

Several bug fixes and enhancements

Eclipse RCP

This tutorial describes how to develop Eclipse RCP applications. It is based on Eclipse 3.7 (EclipseIndigo).

Table of Contents

1. Eclipse based Applications1.1. What are Eclipse RCP applications?1.2. Advantages of Eclipse based applications

2. Eclipse 3.x vs. Eclipse 4.x3. What are Extension Points?

Home Tutorials Trainings Books Connect

Eclipse RCP Tutorial http://www.vogella.com/articles/EclipseRCP/article.html

1 of 51 17-05-2012 00:45

6. Installation6.1. Java6.2. Download the Eclipse plug-in package6.3. Update an Eclipse Java IDE

7. Approach8. Tutorial: Create your first RCP application

8.1. Create an RCP application8.2. Start an RCP application

9. Tutorial: Create and Launch Product9.1. Create your product configuration9.2. Launch your product

10. Overview11. Specifying Arguments12. Common run configuration problems13. Application and Advisor Classes14. Products and Branding

14.1. Product and application14.2. Dependencies14.3. Configuration

15. Deployment15.1. Overview15.2. Which artifacts are included in the export?15.3. Exporting the product15.4. Export for multiple platforms via the deltapack15.5. Including the required JRE into the export

16. Common product export problems17. WorkbenchParts and Perspectives

17.1. WorkbenchParts - Views and Editors17.2. Perspective

18. Convention19. Tutorial: Adding Views to your application

19.1. Create a view19.2. Add the view to your perspective19.3. Result19.4. Add view to perspective via code

20. SWT21. JFace Viewers22. Commands23. Tutorial: Adding an Perspectives24. Tutorial: System Tray25. Target Platform

25.1. Developing against the Eclipse IDE25.2. Defining your Target Platform



2 of 51 17-05-2012 00:45

27. Tips and Tricks27.1. Load an image from your plugin27.2. Save users layout27.3. Accessing the status line27.4. Finding unused dependencies27.5. Multi-User settings

28. Reading resources from plug-ins29. Questions and Discussion30. Links and Literature

30.1. Source Code30.2. Eclipse Resources30.3. vogella Resources

1.1. What are Eclipse RCP applications?

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

At this point the term "Eclipse RCP" was coined. Eclipse RCP is short for "Eclipse Rich Client Platform"and indicates that the Eclipse platform is used as a basis to create feature-rich stand-alone applications.

The Eclipse 4 platform simplifies and unifies the Eclipse programming model and extends the concept ofbuilding Eclipse based applications with new technologies, like dependency injection and declarativestyling via CSS files.

1.2. Advantages of Eclipse based applications

The Eclipse platform forms the basis of the most successful Java IDE and therefore is very stable andbroadly used. It uses native user interface components which are fast and reliable and with its strongmodularity approach it allows to design component based systems.

Companies like IBM and Google use the Eclipse framework for their products and therefore ensure that



3 of 51 17-05-2012 00:45

The Eclipse platform also fosters a large community of individuals which provide support, informationand extensions to the Eclipse framework. Tapping into this Ecosystem allows you to find requiredresources and information.

The following describes how to build Eclipse RCP applications based on the Eclipse 3.x programmingmodel. Eclipse 4 makes significant changes to this programming, please see Eclipse 4 Tutorial for anintroduction into the Eclipse 4 programming model.

Currently development with Eclipse 3.x programming model is much more stable and has better toolsupport then developing for Eclipse 4.x programming model. On the other hand the Eclipse 4.xprogramming model is much more flexible and simpler to use.

Extension-points define interfaces for other plug-ins to contribute functionality (code and non-code).

They are defined in the "plugin.xml" file, which must be in the root directory of your plug-in project.

Existing extensions (contributions) are collected during the start of an Eclipse application.

The minimal required plug-ins to create and run an minimal Eclipse RCP application (with UI) are the twoplugins "org.eclipse.core.runtime" and "org.eclipse.ui". Based on these components an Eclipse RCPapplication must define the following elements:

Main program - A RCP main application class implements the interface "IApplication". This classcan be viewed as the equivalent to the main method for standard Java application. Eclipse expectsthat the application class is defined via the extension point "org.eclipse.core.runtime.application".



4 of 51 17-05-2012 00:45

"org.eclipse.ui.perspective".

Workbench Advisor- invisible technical component which controls the appearance of the application(menus, toolbars, perspectives, etc)

The Eclipse application is the equivalent of the Java main() method. Applications are defined via theextension point org.eclipse.core.runtime.applications and must extend IApplication.

The following assumes that you already have some knowledge in using the Eclipse IDE for standardJava development. See Eclipse IDE Tutorial if you don't have this knowledge.

Is also assume that you are familiar with using the Eclipse update manager. See Eclipse UpdateManager to learn how to use it.

6.1. Java

The following description assumes that you have already Java installed. If not please download andinstall the most current version before continuing with this chapter.

To find instructions how to install Java, please google for "How to installed Java for MyOS", whilereplacing "MyOS" with the Operating System your are using.

6.2. Download the Eclipse plug-in package

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.

6.3. Update an Eclipse Java IDE

In case you have downloaded the Eclipse Java IDE (or any other non RCP flavor) distribution you can



5 of 51 17-05-2012 00:45

Install General Purpose Tools → Eclipse Plug-in Development Environment → Eclipse RCP Plug-inDeveloper 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.



6 of 51 17-05-2012 00:45

If you teach programming you basically have two extreme choices. The first approach is that you explaineverything first and then do it. The second choice is that you first do everything and then explain whatyou have done.

The following description tends towards the second approach.

We will develop a small RCP application, create a product and launch it, before explaining the projectstructure, the involved classes and what a product or a launch configuration is.

In my experience its easier to understand an explanation, if you have already created an example.

The risk associated with that approach is that if you run into a problem you don't know how to solve it.

Therefore if you have problem starting your product, I suggest to read the chapter about launchconfigurations and if that doesn't help, check the "Products and Branding" chapter.

8.1. Create an RCP application

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



7 of 51 17-05-2012 00:45

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



8 of 51 17-05-2012 00:45

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".



9 of 51 17-05-2012 00:45

Press next and select the template "Hello RCP" .



10 of 51 17-05-2012 00:45

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



11 of 51 17-05-2012 00:45

especially the Java files to get a first feeling about the project structure.

8.2. Start an RCP application

While it is possible in Eclipse 3.7 to start an application directly, it is consistent to create a product tostart 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 alwaysneed a product.



12 of 51 17-05-2012 00:45

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 filewith 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 thewindow, the ID is not required and entering it leads sometimes to problems. You can change this defaultname in class ApplicationWorkbenchWindowAdvisor in the method preWindowOpen() via theconfigurer.setTitle("New title");)

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



13 of 51 17-05-2012 00:45

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 the Add button. Add your application plug-ins. Press thebutton "Add Required Plug-ins" to add all dependent plug-ins to your product. Save.

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



14 of 51 17-05-2012 00:45

9.2. Launch your product

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

The result should look like the following:

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

A run configuration in Eclipse defines the environment under which an Eclipse application will be started.For example it defines compiler flags, plug-in (classpath) dependencies etc. Sometimes a runconfiguration is called "launch configuration".

If you start your Eclipse application, using the link in the product file, the run configuration will be

Java program for Freshers Programs in Core java,Advanced java and Java EE. Enroll today ! Talentedge.in

Flipkart™ Official Site Get 1TB - 3TB Harddisks @Huge Discounts Easy EMI & Payment Option www.Flipkart.com/Harddisk

Java Application Code and Debug Your Apps On The Fly In The Cloud. Download the Trial windowsazure.com



15 of 51 17-05-2012 00:45

You can use the created run configuration directly for starting the application again. Changes in theproduct configuration file will not be considered.

You can update the run configuration by starting the application from the product definition again.

To see and edit your run configuration select your product configuration file, right-click on it and selectRun As → Run Configurations... .

On the "Main" tab in the field "location" you specify where the Eclipse IDE will create the files necessaryto start your Eclipse based application.



16 of 51 17-05-2012 00:45

The run configuration allows to add additional parameters for your application on the Arguments tab. Perdefault the -consoleLog parameter is included. This will write error messages of the running Eclipseapplication instance to the Eclipse IDE "Console" View.

If you provide different translations for your Eclipse application, you can specify the language for yourapplication via the -nl parameter. For example -nl will start your application with the English language.This is useful to test your application with different languages.

Other useful parameters are -console (which will give you a OSGi console where you can check thestatus of your application) and -noExit (which will keep the OSGi console open even if the applicationcrashes).

Run configurations are frequent sources of problems.

The most common problem is that required plug-ins are missing. Eclipse can check this automatically foryou before every start. On the Plug-ins Tab select the Validate plug-ins prior to launching option. Thiswill check if you have all required plug-ins in your run configuration.

If this check reports that some plug-ins are missing, try clicking the Add Required Plug-Ins button. Alsomake sure to define all dependencies in your product.



17 of 51 17-05-2012 00:45

The following table lists potential problems and solutions.

Table 1. Common problems with Run Configuration

Problem How to investigate or solve

During start you get error messages like "One or more bundlesare not resolved because the following root constraints are notresolved" or "java.lang.RuntimeException: No application id hasbeen found."

Check that all required plug-ins are included inyour run configuration. Make sure that yourproduct defines dependencies to all requiredplug-ins or features.

Strange behavior but no error message. Check if your run configuration includes theparameter -consoleLog. This option allows tosee errors of the Eclipse based application inthe console view of the Eclipse IDE.

Runtime configuration is frequently missing required plug-ins Make sure that your product includes all



18 of 51 17-05-2012 00:45

required dependencies.

A change in the product dependencies, e.g. a new plug-in isadded, is not included in the run configuration.

A product updates an existing run configurationif you start the product directly from the productdefinition file. If you select the run configurationdirectly it will not be updated.

During the startup of an Eclipse RCP application the Eclipse runtime will evaluate which class is definedvia the org.eclipse.core.runtime.application extension point.

This is the equivalent of the main class of standard Java programs. This class is responsible for creatingthe SWT Display and for starting the event loop for the application.

This class is typically called Application and must implement the interface IApplication.

Display display = PlatformUI.createDisplay();

PlatformUI.createAndRunWorkbench(display, new ApplicationWorkbenchAdvisor());

PlatformUI.createAndRunWorkbench() creates and runs a Workbench. The Workbench

represents the graphical user interface of Eclipse. The visual part of the Workbench is represented viathe WorkbenchWindow class. A Workbench can have several WorkbenchWindows opened. The innerpart of the WorkbenchWindow is represented via the class WorkbenchPage.

The Workbench is configured via a class of type WorkbenchAdvisor. This class defines the initialPerspective and defines the WorkbenchWindowAdvisor class.

WorkbenchWindowAdvisor calls the class ActionBarAdvisor which configures Actions for theWorkbench and defines initial attribute for the WorkbenchWindow as initial size, title and visibility of thestatusline.



19 of 51 17-05-2012 00:45

}

public void preWindowOpen() {

IWorkbenchWindowConfigurer configurer = getWindowConfigurer();

configurer.setInitialSize(new Point(400, 300));

configurer.setShowCoolBar(false);

configurer.setShowStatusLine(false);

configurer.setTitle("Todo"); //$NON-NLS-1$}

For example you could set the initial position of the application via postWindowCreate() method.

// For further info see https://bugs.eclipse.org/bugs/show_bug.cgi?id=84938@Overridepublic void postWindowCreate() {

Shell shell = getWindowConfigurer().getWindow().getShell();

shell.setLocation(100, 400);

super.postWindowCreate();

}

The ActionBarAdvisor class is as of Eclipse 3.7 not important any more as the Action framework isreplaced by the superior command framework.

Each adviser allow to configure certain behavior of the application, e.g. the WorkbenchAdvisor allowsto perform certain actions at startup or shutdown by overriding the preStartUp() and preShutdown()

methods. .

14.1. Product and 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 whichdescribes 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



20 of 51 17-05-2012 00:45

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

This configuration file contains all the information about required plug-ins, configuration files, resourcesetc. 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 theproduct ID is the same as a plug-in ID.

On the overview tab of your product you can start the product and select the "Synchronize" link. Thisselection will write the product configuration, which is required at runtime, into the plugin.xml file.

14.2. Dependencies

A product configuration file can either be based on plug-ins or features. This setting is done on the"Overview" tab of the product configuration file.

On the dependency tab you maintain the plug-ins or features your products consists of. A product willnot do any automatic dependency resolution for you. If you add a plug-in to your product and want to



21 of 51 17-05-2012 00:45

14.3. Configuration

The Splash tab allows to specify the plug-in which contains the splash screen. You need to put thesplash.bmp file into the project main directory. This name and directory is predefined in Eclipse, but canbe changed via the osgi.splashPath parameter.

You can configure the launcher name and icon for your exported product. The launcher is the executableprogram that is created during the deployment of the product. A launcher is platform specific. Forexample eclipse.exe on the Windows platform. This launcher has also an icon associated with it. Tochange the name and the icon, select the Launcher tab of your product configuration.

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



22 of 51 17-05-2012 00:45

In the launcher section you can also specify parameters to your Eclipse application or arguments to theJava runtime environment.

15.1. Overview

Your product configuration file can be used to export your application to run outside of Eclipse.

Exporting your product will create a directory or a zipped file which contains all artifacts required to runyour application. It will also contain a native launcher specific to the platforms, e.g. Windows or Linux,you have exported it for. The resulting directory can be shared with others.



23 of 51 17-05-2012 00:45

The included artifacts are defined by the "build.properties" file.

Eclipse will per default add the compiled Java classes. You have to add other files manually, e.g. iconsor splash screen images.

To change the "build.properties" file you can use the "plugin.xml" editor. Open the "plugin.xml" file andselect the build tab.

Make sure the META-INF directory, the plugin.xml file and all other static files, e.g. icons, splash.bmpand in the case of an Eclipse 4 application the Application.e4xmi file and potentially CSS files, areflagged to be included in the exported product. An Eclipse application started from the Eclipse IDE willhave access to resources which are not contained in the build.properties, but these files will not becontained in the exported application. Your exported application will therefore fail to find the files.Therefore it's a good rule to directly include new resources in the configuration.

15.3. Exporting the product

To export the product switch to your product configuration file, select the Overview tab and click on theEclipse Product export wizard link. On the second page of the wizard you can specify the destination

directory and the root directory for the exported application.

This root directory will be a sub-folder in the destination directory and will contain the completeapplication.

The following screenshots show the export wizard in action.



24 of 51 17-05-2012 00:45



25 of 51 17-05-2012 00:45

should start your application.

If you transfer the content of this directory to another machine (with the same architecture, e.g. Linux 64bit) your application should run on this machine. The machine only needs to have Java installed. Theexport dialog allows to create an archive file directly, which makes it easier to transfer all files to anothermachine.

15.4. Export for multiple platforms via the delta pack

The delta pack is a separate download and can be added to your Eclipse installation via the settings inthe target platform. If the delta pack is available, you can export for multiple platform.

15.5. Including the required JRE into the export

You can also deploy your own RCP application bundled with a JRE to make sure that a certain JRE isused. An Eclipse application first searches in the installation directory for a folder called jre and for acontained Java-VM. If it finds one, then this JRE is used to start the Eclipse application.

To include the JRE from your running environment, select the Bundle JRE for this environment with theproduct flag on the Launching tab of your product configuration file.

If the export encounters a problem please have a look into the following table for a solution:

Table 2. Problems with the product export

Problem Possible cause

Export fails Try using an empty target directory, sometimes the export cannot delete the existing filesand therefore fails.

No .exe file after theexport

Check the flag "The product includes native launcher artifacts" in your .product file on the"Overview" tab.

Product could not be Validate that all dependencies are included in the product. Delete an existing launch



26 of 51 17-05-2012 00:45

found configuration and restart the product from the IDE to see if everything is configuredcorrectly.

Splash Screen or othericons are missing

Check build.properties to see if all required images and icons are included in the export.

Splash Screen ismissing

Ensure that you have entered the defining plug-in in the "Splash" tab on the productconfiguration file. Not defining it works, if you start the plug-in from Eclipse, but not if youstart the exported product.

Issues during startup Check the log file in the workspace folder of your export product to see the errormessages during startup. Alternatively add the "-consoleLog" parameter to the ".ini" file infolder of the export product.

applicationXMIargument is missing

Check build.properties to see if the Application.e4xmi and the plugin.xml are included in theexport.

Service could not befound or injected

Make sure that the service start level is set to "auto" so that the bundle which defines theOSGi service is started. Also make sure that the org.eclipse.equinox.dsbundle is started before your bundle which define a service via declarative services.

Translations notavailable in theexported product

Check the "build.properties" file of the plug-in which provides the property files, if theproperty files are included in the export.

17.1. WorkbenchParts - Views and Editors

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



27 of 51 17-05-2012 00:45

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 extendWorkbenchPart.

An editor typically requires that the user explicitly select "save" to apply the changes to the data whilea view typically changes the data immediately. All editors are opened in the same area. Via theperspective 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 userinterface. This composite has per default a FillLayout layout manager assigned to it. This layoutmanager assigns the same space to all components equally.

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

17.2. Perspective

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 aPerspective 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);

}

}



28 of 51 17-05-2012 00:45

layout.addView() adds a view to the perspective. You can also add placeholders for views via thelayout.addPlaceholder() method call. This methods accepts wildcards and a View with a matchingID would open in this area. For example if you want to open all views in a specific place you could usethe layout.addPlaceholder("*",...) method call, orlayout.addPlaceholder("view_id",....) to open a View with the "view_id" ID in this placeholder.

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

In this tutorial we will always create RCP applications. Therefore if the instruction says "Create an RCPproject" you should create a new plug-in project with the flag "Would you like to create a rich clientapplication" enabled.

19.1. Create a view

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".



29 of 51 17-05-2012 00:45

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 {

@Overridepublic void createPartControl(Composite parent) {

Text text = new Text(parent, SWT.BORDER);

text.setText("Imagine a fantastic user interface here");

}

@Overridepublic void setFocus() {

}

}

19.2. Add the view to your perspective

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



30 of 51 17-05-2012 00:45

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 thecurrently invisible editor area and make the view use all the space by selecting the maximum ratio of"0.95f".

19.3. Result

Run your application to see the result.



31 of 51 17-05-2012 00:45

19.4. Add view to perspective via code

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 thismodify "Perspective.java" to the following.

package de.vogella.rcp.intro.view;

import org.eclipse.ui.IPageLayout;

import org.eclipse.ui.IPerspectiveFactory;



layout.addView("de.vogella.rcp.intro.first.MyView", IPageLayout.TOP,

IPageLayout.RATIO_MAX, IPageLayout.ID_EDITOR_AREA);

}

}

SWT is the UI library used by Eclipse. SWT provides the same rich UI components on several platformsusing the native widgets of the platform whenever possible. If a widget is not available on a certain



32 of 51 17-05-2012 00:45

framework via JNI.

For an introduction into SWT please use the SWT Tutorial.

JFace provides also viewers which allow to work with Java object directly to create an user interface.Viewers are available for trees, tables, lists and comboboxes. Please see JFaces Tables Tutorial andJFace Tree Viewer Tutorial for a detailed tutorial.

A command is a declarative description of a component and is independent from the implementationdetails. A command can be categorized and a hot key (key binding) can be assigned to it. Commandscan be used in menus, toolbars and / or context menus.

See Eclipse Commands Tutorial for an introduction into the commands framework.

Create a new RCP project called "de.vogella.rcp.intro.perspective". Use the "RCP application with aview" as a template. In "plugin.xml" add a new extension point "org.eclipse.ui.perspectives". Give theperspective with the id "de.vogella.rcp.intro.perspective.perspective" and the name "vogella.comPerspective". Change the class name to "de.vogella.rcp.intro.perspective.Perspective".



33 of 51 17-05-2012 00:45

Click on the "class*" link to create the class. The method createInitialLayout() in your new class isresponsible for creating the new perspective. We re-use the existing view in the coding. After this stepthe perspective is defined but not yet reachable via the application.

package de.vogella.rcp.intro.perspective;

import org.eclipse.ui.IPageLayout;

import org.eclipse.ui.IPerspectiveFactory;



String editorArea = layout.getEditorArea();

layout.setEditorAreaVisible(false);

layout.setFixed(true);

layout.addStandaloneView(View.ID, false, IPageLayout.LEFT, 1.0f, editorArea);

}

}

After defining your perspective you also need to enable your application so that the user can select thisperspective.

One alternative is to allow the user to select the perspective via the toolbar / coolbar. You can activate theswitch between perspectives the ApplicationWorkbenchWindowAdvisor in method preWindowOpen()with configurer.setShowPerspectiveBar(true);

package de.vogella.rcp.intro.perspective;



34 of 51 17-05-2012 00:45

import org.eclipse.ui.application.ActionBarAdvisor;

import org.eclipse.ui.application.IActionBarConfigurer;

import org.eclipse.ui.application.IWorkbenchWindowConfigurer;

import org.eclipse.ui.application.WorkbenchWindowAdvisor;

public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor {

public ApplicationWorkbenchWindowAdvisor(

IWorkbenchWindowConfigurer configurer) {

super(configurer);

}

public ActionBarAdvisor createActionBarAdvisor(

IActionBarConfigurer configurer) {

return new ApplicationActionBarAdvisor(configurer);

}





configurer.setTitle("RCP Application");

configurer.setShowPerspectiveBar(true);

}

}

You should now be able to select your perspective interactively.



35 of 51 17-05-2012 00:45

allows to switch between perspectives. See Eclipse Commands.

The following add an icon for the RCP application to the system tray and adds a menu to this icon. Weadd the functionality that if the window is minimized then the program is not visible in the taskpane (onlyvia the tray icon).

Create a new project "de.vogella.rcp.intro.traytest". Use the "Hello RCP" as a template. Open the class"ApplicationWorkbenchWindowAdvisor" and maintain the following code.

package de.vogella.rcp.intro.traytest;

import org.eclipse.swt.SWT;

import org.eclipse.swt.events.MenuDetectEvent;

import org.eclipse.swt.events.MenuDetectListener;

import org.eclipse.swt.events.SelectionAdapter;

import org.eclipse.swt.events.SelectionEvent;

import org.eclipse.swt.events.ShellAdapter;

import org.eclipse.swt.events.ShellEvent;

import org.eclipse.swt.graphics.Image;

import org.eclipse.swt.graphics.Point;

import org.eclipse.swt.widgets.Menu;

import org.eclipse.swt.widgets.MenuItem;

import org.eclipse.swt.widgets.Shell;

import org.eclipse.swt.widgets.Tray;

import org.eclipse.swt.widgets.TrayItem;

import org.eclipse.ui.IWorkbenchWindow;

import org.eclipse.ui.application.ActionBarAdvisor;

import org.eclipse.ui.application.IActionBarConfigurer;




private IWorkbenchWindow window;

private TrayItem trayItem;

private Image trayImage;

public ApplicationWorkbenchWindowAdvisor(




36 of 51 17-05-2012 00:45

public ActionBarAdvisor createActionBarAdvisor(

IActionBarConfigurer configurer) {

return new ApplicationActionBarAdvisor(configurer);

}




configurer.setShowCoolBar(false);


configurer.setTitle("Hello RCP"); //$NON-NLS-1$}

// As of here is the new stuff@Overridepublic void postWindowOpen() {

super.postWindowOpen();

window = getWindowConfigurer().getWindow();

trayItem = initTaskItem(window);

// Some OS might not support tray itemsif (trayItem != null) {

minimizeBehavior();

// Create exit and about action on the iconhookPopupMenu();

}

}

// Add a listener to the shell

private void minimizeBehavior() {

window.getShell().addShellListener(new ShellAdapter() {

// If the window is minimized hide the windowpublic void shellIconified(ShellEvent e) {

window.getShell().setVisible(false);

}

});

// If user double-clicks on the tray icons the application will be// visible againtrayItem.addSelectionListener(new SelectionAdapter() {

@Overridepublic void widgetSelected(SelectionEvent e) {

Shell shell = window.getShell();

if (!shell.isVisible()) {

window.getShell().setMinimized(false);

shell.setVisible(true);

}

}

});



37 of 51 17-05-2012 00:45

// We hook up on menu entry which allows to close the applicationprivate void hookPopupMenu() {

trayItem.addMenuDetectListener(new MenuDetectListener() {

@Overridepublic void menuDetected(MenuDetectEvent e) {

Menu menu = new Menu(window.getShell(), SWT.POP_UP);

// Creates a new menu item that terminates the programMenuItem exit = new MenuItem(menu, SWT.NONE);

exit.setText("Goodbye!");

exit.addSelectionListener(new SelectionAdapter() {

@Overridepublic void widgetSelected(SelectionEvent e) {

window.getWorkbench().close();

}

});

// We need to make the menu visiblemenu.setVisible(true);

}

});

}

// This methods create the tray item and return a referenceprivate TrayItem initTaskItem(IWorkbenchWindow window) {

final Tray tray = window.getShell().getDisplay().getSystemTray();

TrayItem trayItem = new TrayItem(tray, SWT.NONE);

trayImage = Activator.getImageDescriptor("/icons/alt_about.gif")

.createImage();

trayItem.setImage(trayImage);

trayItem.setToolTipText("TrayItem");

return trayItem;

}

// We need to clean-up after ourself@Overridepublic void dispose() {

if (trayImage != null) {

trayImage.dispose();

}

if (trayItem != null) {

trayItem.dispose();

}

}

}



38 of 51 17-05-2012 00:45

behavior. If the application is minimized it should not be visible in the taskbar but only in the system tray.

25.1. Developing against the Eclipse IDE

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

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 canlead to problems, if developers are using different versions of Eclipse. It also makes it difficult to upgradethese 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 inyour workspace or in your Eclipse IDE.

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

25.2. Defining your Target Platform

Via a Target Platform you define the set of plug-ins which are available for development. For exampleyou 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 ofEclipse 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.



39 of 51 17-05-2012 00:45

same basis for development.

The most effective way of defining your Target Platform is to use (Eclipse p2) update sites. These are thesame type of update sites which you use if you want to install a new set of plug-ins. If the content in theupdate 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 andtherefore should be avoided.

25.3. Creating a Target Platform definition

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



40 of 51 17-05-2012 00:45

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 "Setas Target Platform" button.



41 of 51 17-05-2012 00:45

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



42 of 51 17-05-2012 00:45

To interact with the Workbench you have access to the Workbench API. For example you can access the



43 of 51 17-05-2012 00:45

Most API calls are done via the WorkbenchPage.

A command handler can get access to the WorkbenchPage via:

IWorkbenchPage page = HandlerUtil.getActiveWorkbenchWindow(event).getActivePage();

A view provides access to the Workbench and the WorkbenchWindow via the getViewSite() method. Aneditor provides the same access via getEditorSite().

IWorkbenchPage page = getViewSite().getPage();

IWorkbenchPage page = getEditorSite().getPage();

You could also get the Workbench page over the PlatformUI Singleton.

IWorkbenchPage page = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage()

Once you have access to the Page you can call its API. The following demonstrates how to first close allviews in the running application and how to open a View with a specific ID.

IViewReference[] views = page.getViewReferences();

for (IViewReference view : views) {

page.hideView(view);

}

try {

page.showView(View.ID);

} catch (PartInitException e) {

e.printStackTrace();

}

return null;

The following shows how to save an editor and how to close it.



44 of 51 17-05-2012 00:45

// Save the editor without confirmation page.saveEditor(editorPart, false);

// Close the editor and save before saving page.closeEditor(editorPart, true);

}

You can also add a PartListener to the page and listen for change in View and Editors. Here is anexample how to add such a listener in ApplicationWorkbenchWindowAdvisor.

@Overridepublic void postWindowOpen() {

super.postWindowOpen();

IWorkbenchPage page = PlatformUI.getWorkbench()

.getActiveWorkbenchWindow().getActivePage();

// Register a part listener for a certain View / Part

page.addPartListener(new IPartListener2() {

@Overridepublic void partVisible(IWorkbenchPartReference partRef) {

System.out.println("Part visible: " + partRef.getId());

}

@Overridepublic void partOpened(IWorkbenchPartReference partRef) {

System.out.println("Part opened: " + partRef.getId());

}

@Overridepublic void partInputChanged(IWorkbenchPartReference partRef) {

}

@Overridepublic void partHidden(IWorkbenchPartReference partRef) {

System.out.println("Part hidden: " + partRef.getId());

}

@Overridepublic void partDeactivated(IWorkbenchPartReference partRef) {

System.out.println("Part deactivated:" + partRef.getId());

}

@Overridepublic void partClosed(IWorkbenchPartReference partRef) {

System.out.println("Part closed:" + partRef.getId());



45 of 51 17-05-2012 00:45

@Overridepublic void partBroughtToTop(IWorkbenchPartReference partRef) {

System.out.println("Part top:" + partRef.getId());

}

@Overridepublic void partActivated(IWorkbenchPartReference partRef) {

System.out.println("Part activated: " + partRef.getId());

}

});

}

27.1. Load an image from your plugin

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();

27.2. Save users layout

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

package addactiontoview;

import org.eclipse.ui.application.IWorkbenchConfigurer;


import org.eclipse.ui.application.WorkbenchAdvisor;




46 of 51 17-05-2012 00:45

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

public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(


return new ApplicationWorkbenchWindowAdvisor(configurer);

}

public String getInitialWindowPerspectiveId() {

return PERSPECTIVE_ID;

}

@Overridepublic void initialize(IWorkbenchConfigurer configurer) {

super.initialize(configurer);

configurer.setSaveAndRestore(true);

}

}

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

27.3. Accessing the status line

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

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


//... @Override public void preWindowOpen() {

// .... configurer.setShowStatusLine(false);

}

}



47 of 51 17-05-2012 00:45

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();

27.4. Finding unused dependencies

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



48 of 51 17-05-2012 00:45

27.5. Multi-User settings

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



49 of 51 17-05-2012 00:45

To access files in your bundle you can use you can use a Eclipse specific URL. The following shows anexample how to access a file in the "files" folder of a specific plug-in.

URL url;

try {

// de.vogella.rcp.plugin.filereader is the Bundle ID // files is the folder// test.txt is the file

url = new URL("platform:/plugin/de.vogella.rcp.plugin.filereader/files/test.txt");

InputStream inputStream = url.openConnection().getInputStream();

BufferedReader in = new BufferedReader(new InputStreamReader(inputStream));

String inputLine;

while ((inputLine = in.readLine()) != null) {

System.out.println(inputLine);

}

in.close();

} catch (IOException e) {

e.printStackTrace();

}

This requires that your plug-in has a dependency to org.eclipse.core.runtime defined.

Before posting questions, please see the vogella FAQ. If you have questions or find an error in thisarticle please use the www.vogella.com Google Group. I have created a short list how to create goodquestions which might also help you.

30.1. Source Code

Source Code of Examples



50 of 51 17-05-2012 00:45

Using Eclipse IDE (Kindle Book)

Eclipse Plug-in Development FAQ

SWT Graphics

30.3. vogella Resources

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



51 of 51 17-05-2012 00:45

Eclipse Rcp Tutoriallars Vogel

Documents

overridepublic

rich client

graphical

eclipse rcp

shared status

eclipse update

eclipse rcp

eclipse rcp