分类： Java
2010-07-18 10:57:24
Version 4.6
Copyright © 2007-2010 Lars Vogel
28.06.2010
| Revision History | ||
|---|---|---|
| Revision 0.1 - 0.7 | 14.08.2007 - 03.09.2007 | Lars Vogel |
| Eclipse RCP with Eclipse 3.3 | ||
| Revision 0.8 | 15.06.2008 - 10.07.2008 | Lars Vogel |
| Updated to Eclipse 3.4 | ||
| Revision 0.9 - 2.5 | 03.11.2008 - 02.05.2009 | Lars Vogel |
| Several bug fixes and enhancements | ||
| Revision 2.0 | 03.05.2009 - 10.06.2009 | Lars Vogel |
| Update to Eclipse 3.5 (Galileo), removed actions | ||
| Revision 2.1 - 4.3 | 24.06.2009 | Lars Vogel |
| Several bug fixes and enhancements | ||
| Revision 4.4 - 4.6 | 01.06.2010 - 28.06.2010 | Lars Vogel |
| Update to Eclipse 3.6 (Helios) | ||
Eclipse RCP
This article describes how to develop Eclipse RCP applications. It is baesd on Eclipse 3.6 (Eclipse Helios).
Table of Contents
The following assumes that you already know how to use the .
Eclipse RCP allows developers to use the Eclipse platform to create flexible and extensible desktop applications. Eclipse is build upon a . Plugins are the smallest deployable and installable software components of Eclipse. This architecture allows the Eclipse applications to get extended by third parties. Eclipse RCP provides the same modular concept for stand-alone applications.
The components of the Eclipse IDE are typically the following.
An Eclipse RCP application can decided to use parts of these components. It is possible to design headless Eclipse based applications, then only the runtime is necessary. An Eclipse RCP application typically uses.
The minimal required plugins to create and run an Eclipse RCP application (with UI) are the two plugins "org.eclipse.core.runtime" and "org.eclipse.ui"
The provides the framework to run the modular application. is the standard UI component library used by Eclipse and provides some convenient API on top of SWT. The workbench provides the application frame in which all other UI components are displayed.
The most important architectural characteristics of Eclipse is the Plugin architecture. Eclipse application are build as a number of plugins which define their API and their dependencies. The basis for this architecture is the runtime environment which is the reference implementation of . Eclipse uses the term "Plugin" and OSGi uses the term "bundle", but both terms mean the same. OSGi supports that Eclipse plugins defines
their API - public classes which can be used by other plugins
their dependencies - package or plugins which are required for the plugin to run correctly
Each plugin can define which define possibilities for functionality contributions ( code and non-code ) by other plugins. A plugin can use extensions, e.g. provide functionality to these extension points.
Extensions and extension-points are described in the file plugin.xml. This file is a XML file which can be edited via the PDE (Plugin Development Environment) which provides a user interface for editing this file.
An Eclipse RCP application requires the following elements. The definition of the components will be explained later in this tutorial.
Main program - A RCP main application class implements the interface IApplication. This class can be viewed as the equivalent to the main method for standard Java application. Eclipse expects that the application class is defined via the extension point org.eclipse.core.runtime.application.
A Perspective - The perspective is extended from org.eclipse.ui.perspective
Workbench Advisor- invisible technical component which controls the appearance of the application (menus, toolbars, perspectives, etc)
An Eclipse RCP application has two main configuration files.
MANIFEST.MF - contains the OSGi configuration information.
plugin.xml - Information about the extensions and extension points
On the webpage of , click on DOWNLOADS. Download the package "Eclipse for RCP/Plug-in 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 plugins required for RCP development. See for details on using the update manager.
Install "General Purpose Tools" -> "Eclipse Plug-in Development Environment" and "Eclipse RCP Plug-in Developer Resources" from the Helios update site. You may have to remove the "Group items by category" flag to see these features.
The following gives a quick guide on 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 a 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.
Open the file "MANIFEST.MF" by double-clicking on it. You should see an editor and the tab "Overview" should be selected. Click the link "Launch an Eclipse Application".
The result should look like the following:
Congratulations, you have created your first RCP application.
During the startup of an Eclipse RCP application the Eclipse runtime will evaluate which class is defined via the "org.eclipse.core.runtime.application" extension point. This class will be loaded and creates and runs a Workbench. The Workbench is configured via a "WorkbenchAdvisor". The Workbench will start a "WorkbenchWindow" which is configured via a WorkbenchWindowAdvisor. This WorkbenchWindow will create the toolbar of the application which can get configured at startup via the "ActionBarAdvisor".
Each adviser allow to configure certain behavior of the application, e.g. the WorkbenchAdvisor allows to perform certain actions at startup or shutdown by overriding the methods preStartUp() and preShutdown().
A run configuration in Eclipse defines the environment under which your application will be started, e.g. compiler flag, plugin (classpath) dependencies etc. Sometimes a run configuration is called "launch configuration". If you start your RCP application a run configuration will be automatically created for you.
To see and edit your run configuration select the file "MANIFEST.MF", right-click on it and select -> Run As -> Run Configurations
In the field "location" you specify their the files will be created which are necessary to run your RCP application.
On the Plug-ins Tab select "Validate plug-ins prior to launching". This will check if you have all required plugins in your launch configuration. If this check reports that some plugins are missing, try clicking the "Add Required-Plug-Ins" button.
On the tab Arguments you find the parameter -consoleLog. This option allows to see errors in the RCP application in the console view and is very helpful to identify problems. .
A command is a declarative description of a component and is independent from the implementation details. A command can be categorized and a hot key (key binding) can be assigned to it. Commands can be used in menus, toolbars and / or context menus. The following will give demonstrates the usage of commands in menus. For details on commands see
We will create a command which will exit the application. Create a new RCP project "de.vogella.rcp.commands.first" using the "Hello RCP" template. Click on the plugin.xml and select the Extensions tab. Press the "Add" button.
Search for the extension "org.eclipse.ui.commands". Select it and press finish.
Create a new command by right-clicking on your extension point and by selecting New -> command.
Set the ID to "de.vogella.rcp.commands.first.commands.Exit" and the name to "Exit". Enter the class "de.vogella.rcp.commands.first.commands.ExitHandler" as defaultHandler. Press the hyperlink "defaultHandler" to create this class and select "org.eclipse.core.commands.AbstractHandler" as Superclass.
Implement the following coding. Afterwards your new command is ready to be used.
package de.vogella.rcp.commands.first.commands;
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.ui.handlers.HandlerUtil;
public class ExitHandler extends AbstractHandler {
@Override
public Object execute(ExecutionEvent event) throws ExecutionException {
HandlerUtil.getActiveWorkbenchWindow(event).close();
return null;
}
}
The command which we defined should be used in a menu. Add the extension point "org.eclipse.ui.menus" to your application similar to adding the extension "org.eclipse.ui.commands". Right click on the extension point and select new -> menuContribution.
Create a new menu contribution with the location URI "menu:org.eclipse.ui.main.menu". Make sure this URL is correct otherwise your menu will not be shown.
Right click your menucontribution and select New -> Menu. Add a menu with the label "File" and the id "fileMenu".
Select your menu, right-click on it, select New-> Command. Maintain your commandID. Set the label to "Exit" and the tooltip to "Exits the application".
Your work should result in a plugin.xml file which looks like the following.
Run the example. You should see menu with the file and if you select the "Exit" entry you application should exit.
The following add an icon for the RCP application to the system tray and adds a menu to this icon. We add the functionality that if the window is minimized then the program is not visible in the taskpane (only via the tray icon).
Create a new project "de.vogella.rcp.intro.traytest". Use the "Hello RCP" as a template. Create a command which the id "de.vogella.rcp.intro.traytest.exitCommand" which exists the application.
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.ShellAdapter;
import org.eclipse.swt.events.ShellEvent;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.widgets.Event;
import org.eclipse.swt.widgets.Listener;
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;
import org.eclipse.ui.application.IWorkbenchWindowConfigurer;
import org.eclipse.ui.application.WorkbenchWindowAdvisor;
import org.eclipse.ui.handlers.IHandlerService;
import org.eclipse.ui.plugin.AbstractUIPlugin;
public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor {
private IWorkbenchWindow window;
private TrayItem trayItem;
private Image trayImage;
private final static String COMMAND_ID = "de.vogella.rcp.intro.traytest.exitCommand";
public ApplicationWorkbenchWindowAdvisor(
IWorkbenchWindowConfigurer configurer) {
super(configurer);
}
public ActionBarAdvisor createActionBarAdvisor(
IActionBarConfigurer configurer) {
return new ApplicationActionBarAdvisor(configurer);
}
public void preWindowOpen() {
IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
configurer.setInitialSize(new Point(400, 300));
configurer.setShowCoolBar(false);
configurer.setShowStatusLine(false);
configurer.setTitle("Hello RCP"); //$NON-NLS-1$
}
// As of here is the new stuff
@Override
public void postWindowOpen() {
super.postWindowOpen();
window = getWindowConfigurer().getWindow();
trayItem = initTaskItem(window);
// Some OS might not support tray items
if (trayItem != null) {
minimizeBehavior();
// Create exit and about action on the icon
hookPopupMenu();
}
}
// Add a listener to the shell
private void minimizeBehavior() {
window.getShell().addShellListener(new ShellAdapter() {
// If the window is minimized hide the window
public void shellIconified(ShellEvent e) {
window.getShell().setVisible(false);
}
});
// If user double-clicks on the tray icons the application will be
// visible again
trayItem.addListener(SWT.DefaultSelection, new Listener() {
public void handleEvent(Event event) {
Shell shell = window.getShell();
if (!shell.isVisible()) {
window.getShell().setMinimized(false);
shell.setVisible(true);
}
}
});
}
// We hook up on menu entry which allows to close the application
private void hookPopupMenu() {
trayItem.addListener(SWT.MenuDetect, new Listener() {
public void handleEvent(Event event) {
Menu menu = new Menu(window.getShell(), SWT.POP_UP);
// Creates a new menu item that terminates the program
// when selected
MenuItem exit = new MenuItem(menu, SWT.NONE);
exit.setText("Goodbye!");
exit.addListener(SWT.Selection, new Listener() {
public void handleEvent(Event event) {
// Lets call our command
IHandlerService handlerService = (IHandlerService) window
.getService(IHandlerService.class);
try {
handlerService.executeCommand(COMMAND_ID, null);
} catch (Exception ex) {
throw new RuntimeException(COMMAND_ID);
}
}
});
// We need to make the menu visible
menu.setVisible(true);
}
});
}
// This methods create the tray item and return a reference
private TrayItem initTaskItem(IWorkbenchWindow window) {
final Tray tray = window.getShell().getDisplay().getSystemTray();
TrayItem trayItem = new TrayItem(tray, SWT.NONE);
trayImage = AbstractUIPlugin.imageDescriptorFromPlugin(
"de.vogella.rcp.intro.traytest", "/icons/alt_about.gif")
.createImage();
trayItem.setImage(trayImage);
trayItem.setToolTipText("TrayItem");
return trayItem;
}
// We need to clean-up after ourself
@Override
public void dispose() {
if (trayImage != null) {
trayImage.dispose();
}
if (trayItem != null) {
trayItem.dispose();
}
}
}
Run your application and see that you have a system tray icon. Test the menu and the minimized behavior. If the application is minized it should not be vislble in the taskbar but only in the system tray.
Views are ViewParts which are used to display information in an application, they can also be used to change data. The following will explain how to add views to your application. Create a new RCP project "de.vogella.rcp.intro.view". Use the "Hello RCP" as a template.
Add the extension "org.eclipse.ui.views" to your plugin. 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.view;
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 it and select view. Maintain your view id "de.vogella.rcp.intro.view.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.view.MyView", IPageLayout.TOP,
IPageLayout.RATIO_MAX, IPageLayout.ID_EDITOR_AREA);
}
}
For an example using views, editor and interaction between both please see .
Dialogs allow to prompt the user for additional information or provide the user with feedback. Eclipse supports several predefined dialogs. For example you have dialog for file or directory selection or to display message and / or errors. Eclipse supports also user defined dialogs. Usually the class "TitleAreaDialog" is then extended.
Create a new project "de.vogella.rcp.intro.dialogs.standard". Use the "Hello RCP" as a template. Create the command "de.vogella.rcp.intro.dialogs.standard.openDialog" with the default handler "de.vogella.rcp.intro.dialogs.standard.handler.OpenDialog". Add the command to the menu and define the following code for the default handler.
package de.vogella.rcp.intro.dialogs.standard.handler;
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.graphics.FontData;
import org.eclipse.swt.graphics.RGB;
import org.eclipse.swt.widgets.ColorDialog;
import org.eclipse.swt.widgets.DirectoryDialog;
import org.eclipse.swt.widgets.FileDialog;
import org.eclipse.swt.widgets.FontDialog;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.ui.handlers.HandlerUtil;
public class OpenDialog extends AbstractHandler {
@Override
public Object execute(ExecutionEvent event) throws ExecutionException {
Shell shell = HandlerUtil.getActiveWorkbenchWindow(event).getShell();
// File standard dialog
FileDialog fileDialog = new FileDialog(shell);
// Set the text
fileDialog.setText("Select File");
// Set filter on .txt files
fileDialog.setFilterExtensions(new String[] { "*.txt" });
// Put in a readable name for the filter
fileDialog.setFilterNames(new String[] { "Textfiles(*.txt)" });
// Open Dialog and save result of selection
String selected = fileDialog.open();
System.out.println(selected);
// Directly standard selection
DirectoryDialog dirDialog = new DirectoryDialog(shell);
dirDialog.setText("Select your home directory");
String selectedDir = dirDialog.open();
System.out.println(selectedDir);
// Select Font
FontDialog fontDialog = new FontDialog(shell);
fontDialog.setText("Select your favorite font");
FontData selectedFont = fontDialog.open();
System.out.println(selectedFont);
// Select Color
ColorDialog colorDialog = new ColorDialog(shell);
colorDialog.setText("Select your favorite color");
RGB selectedColor = colorDialog.open();
System.out.println(selectedColor);
// Now a few messages
MessageDialog.openConfirm(shell, "Confirm", "Please confirm");
MessageDialog.openError(shell, "Error", "Error occured");
MessageDialog.openInformation(shell, "Info", "Info for you");
MessageDialog.openQuestion(shell, "Question", "Really, really?");
MessageDialog.openWarning(shell, "Warning", "I warn you");
return null;
}
}
Run the application. If you select your command the dialogs will be called after each other.
Eclipse provides the "ElementListSelectionDialog" which allows to select elements from a list.
Create a new project "de.vogella.rcp.intro.dialogs.selection". Use the "Hello RCP" as a template. Add the command "de.vogella.rcp.intro.dialogs.selection.selectionDialog" with the default handler "de.vogella.rcp.intro.dialogs.selection.handler.SelectionDialog". Add the command to the menu and define the following code in your handler.
package de.vogella.rcp.intro.dialogs.selection.handler;
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.jface.viewers.LabelProvider;
import org.eclipse.jface.window.Window;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.ui.dialogs.ElementListSelectionDialog;
import org.eclipse.ui.handlers.HandlerUtil;
public class SelectionDialog extends AbstractHandler {
private Object[] result;
@Override
public Object execute(ExecutionEvent event) throws ExecutionException {
Shell shell = HandlerUtil.getActiveWorkbenchWindow(event).getShell();
ElementListSelectionDialog dialog = new ElementListSelectionDialog(
shell, new LabelProvider());
dialog.setElements(new String[] { "Linux", "Mac", "Windows" });
dialog.setTitle("Which operating system are you using");
// User pressed cancel
if (dialog.open()!= Window.OK){
return false;
}
result = dialog.getResult();
for (Object s : result) {
System.out.println(s.toString());
}
return true;
}
}
Run the application and select your command to display the dialog.
You can also define your own dialogs based on "TitleAreaDialog". "TitleAreaDialog" provides out of the box user feedback reporting via the method setMessage() and serErrorMessage().
Create a new project "de.vogella.rcp.intro.dialogs.custom". Use the "Hello RCP" as a template and create the following class "MyDialog".
package de.vogella.rcp.intro.dialogs.custom.dialogs;
import org.eclipse.jface.dialogs.IMessageProvider;
import org.eclipse.jface.dialogs.TitleAreaDialog;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.SelectionAdapter;
import org.eclipse.swt.events.SelectionEvent;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Shell;
import org.eclipse.swt.widgets.Text;
public class MyDialog extends TitleAreaDialog {
private Text firstNameText;
private Text lastNameText;
private String firstName;
private String lastName;
public MyDialog(Shell parentShell) {
super(parentShell);
}
@Override
public void create() {
super.create();
// Set the title
setTitle("This is my first own dialog");
// Set the message
setMessage("This is a TitleAreaDialog", IMessageProvider.INFORMATION);
}
@Override
protected Control createDialogArea(Composite parent) {
GridLayout layout = new GridLayout();
layout.numColumns = 2;
// layout.horizontalAlignment = GridData.FILL;
parent.setLayout(layout);
// The text fields will grow with the size of the dialog
GridData gridData = new GridData();
gridData.grabExcessHorizontalSpace = true;
gridData.horizontalAlignment = GridData.FILL;
Label label1 = new Label(parent, SWT.NONE);
label1.setText("First Name");
firstNameText = new Text(parent, SWT.BORDER);
firstNameText.setLayoutData(gridData);
Label label2 = new Label(parent, SWT.NONE);
label2.setText("Last Name");
lastNameText = new Text(parent, SWT.BORDER);
lastNameText.setLayoutData(gridData);
return parent;
}
@Override
protected void createButtonsForButtonBar(Composite parent) {
GridData gridData = new GridData();
gridData.verticalAlignment = GridData.FILL;
gridData.horizontalSpan = 3;
gridData.grabExcessHorizontalSpace = true;
gridData.grabExcessVerticalSpace = true;
gridData.horizontalAlignment = SWT.CENTER;
parent.setLayoutData(gridData);
// Create Add button
// Own method as we need to overview the SelectionAdapter
createOkButton(parent, OK, "Add", true);
// Add a SelectionListener
// Create Cancel button
Button cancelButton = createButton(parent, CANCEL, "Cancel", false);
// Add a SelectionListener
cancelButton.addSelectionListener(new SelectionAdapter() {
public void widgetSelected(SelectionEvent e) {
setReturnCode(CANCEL);
close();
}
});
}
protected Button createOkButton(Composite parent, int id, String label,
boolean defaultButton) {
// increment the number of columns in the button bar
((GridLayout) parent.getLayout()).numColumns++;
Button button = new Button(parent, SWT.PUSH);
button.setText(label);
button.setFont(JFaceResources.getDialogFont());
button.setData(new Integer(id));
button.addSelectionListener(new SelectionAdapter() {
public void widgetSelected(SelectionEvent event) {
if (isValidInput()) {
okPressed();
}
}
});
if (defaultButton) {
Shell shell = parent.getShell();
if (shell != null) {
shell.setDefaultButton(button);
}
}
setButtonLayoutData(button);
return button;
}
private boolean isValidInput() {
boolean valid = true;
if (firstNameText.getText().length() == 0) {
setErrorMessage("Please maintain the first name");
valid = false;
}
if (lastNameText.getText().length() == 0) {
setErrorMessage("Please maintain the last name");
valid = false;
}
return valid;
}
// We allow the user to resize this dialog
@Override
protected boolean isResizable() {
return true;
}
// We need to have the textFields into Strings because the UI gets disposed
// and the Text Fields are not accessible any more.
private void saveInput() {
firstName = firstNameText.getText();
lastName = lastNameText.getText();
}
@Override
protected void okPressed() {
saveInput();
super.okPressed();
}
public String getFirstName() {
return firstName;
}
public String getLastName() {
return lastName;
}
}
Add one command "de.vogella.rcp.intro.dialogs.custom.openMyDialog" with the following default handler "de.vogella.rcp.intro.dialogs.custom.handler.OpenMyDialog". Add the command to the menu.
package de.vogella.rcp.intro.dialogs.custom.handler;
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.jface.window.Window;
import org.eclipse.ui.handlers.HandlerUtil;
import de.vogella.rcp.intro.dialogs.custom.dialogs.MyDialog;
public class OpenMyDialog extends AbstractHandler {
@Override
public Object execute(ExecutionEvent event) throws ExecutionException {
MyDialog dialog = new MyDialog(HandlerUtil.getActiveWorkbenchWindow(
event).getShell());
dialog.create();
if (dialog.open() == Window.OK) {
System.out.println(dialog.getFirstName());
System.out.println(dialog.getLastName());
}
return null;
}
}
Run the application and open your dialog. To press Ok you need to maintain the first and last name. If you press "Ok" both fields are written to the console.
Field Assist can be used to provide information about the possible inputs and status of a simple field, e.g. text field or combo box. The "org.eclipse.jface.fieldassist" package provides assistance in two ways: ControlDecorations and Content Proposals.
Control decorations allow you to place image decorations on SWT controls to show additional information about the control. These decorations can also have descriptions which are displayed once the user places the mouse over them. During the layout of your screen you need to make sure that enough space is available to display these decorations.
Content proposal allows to provide user input help for the possible choices for this field.
Create a new project "de.vogella.rcp.intro.fieldassist". Use "RCP application with a view" as an example. In our example the content proposal should get activated via certain keys ("." and "#") as well as the key combination "Cntrl+Space".
Change the View.java to the following.
package de.vogella.rcp.intro.fieldassist;
import org.eclipse.jface.bindings.keys.KeyStroke;
import org.eclipse.jface.bindings.keys.ParseException;
import org.eclipse.jface.fieldassist.ContentProposalAdapter;
import org.eclipse.jface.fieldassist.ControlDecoration;
import org.eclipse.jface.fieldassist.FieldDecorationRegistry;
import org.eclipse.jface.fieldassist.SimpleContentProposalProvider;
import org.eclipse.jface.fieldassist.TextContentAdapter;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.part.ViewPart;
public class View extends ViewPart {
public static final String ID = "de.vogella.rcp.intro.fieldassist.view";
public void createPartControl(Composite parent) {
GridLayout layout = new GridLayout(2,false);
parent.setLayout(layout);
Label label = new Label(parent, SWT.NONE);
label.setText("Please select a value: ");
Text text = new Text(parent, SWT.BORDER);
createDeco(text, "Use CNTL + SPACE to see possible values");
GridData data = new GridData(GridData.FILL_HORIZONTAL);
text.setLayoutData(data);
ControlDecoration deco = new ControlDecoration(text, SWT.LEFT);
deco.setDescriptionText("Use CNTL + SPACE to see possible values");
deco.setImage(FieldDecorationRegistry.getDefault().getFieldDecoration(FieldDecorationRegistry.DEC_INFORMATION).getImage());
deco.setShowOnlyOnFocus(false);
// Help the user with the possible inputs
// "." and "#" will also activate the content proposals
char[] autoActivationCharacters = new char[] { '.', '#' };
KeyStroke keyStroke;
try {
//
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// assume that myTextControl has already been created in some way
ContentProposalAdapter adapter = new ContentProposalAdapter(text,
new TextContentAdapter(),
new SimpleContentProposalProvider(new String[] {
"ProposalOne", "ProposalTwo", "ProposalThree" }),
keyStroke, autoActivationCharacters);
} catch (ParseException e) {
e.printStackTrace();
}
}
public void setFocus() {
}
private void createDeco(Text text, String s){
}
}
Run the application and check that the control decorations and the content proposal works.
A wizard guides a user step by step through a process and allows to gather user input in a systematic way including input validation.Eclipse implements a Wizard via the class "WizardDialog". The WizardDialog controls the process (Navigation, process bar, area for error and information messages). The Wizard content and is provided by the class Wizard and the pages are provided via class WizardPages.
To define a wizard you define the individual wizard pages and then the main wizard class.
Create a new project "de.vogella.rcp.intro.wizards". Use the "Hello RCP" as a template. Create the command "de.vogella.rcp.intro.wizards.showWizard" with the default handler "de.vogella.rcp.intro.wizards.handler.ShowWizard". Add the command to the menu.
Create a package "de.vogella.rcp.intro.wizards.wizard". Create the classes "MyPageOne" and "MyPageTwo" MyWizard which extends "org.eclipse.jface.wizard.WizardPage". Maintain the following code.
package de.vogella.rcp.intro.wizards.wizard;
import org.eclipse.jface.wizard.WizardPage;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.KeyListener;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
public class MyPageOne extends WizardPage {
private Text text1;
private Composite container;
public MyPageOne() {
super("First Page");
setTitle("First Page2");
setDescription("This wizard does not really do anything. But this is the first page");
}
@Override
public void createControl(Composite parent) {
container = new Composite(parent, SWT.NULL);
GridLayout layout = new GridLayout();
container.setLayout(layout);
layout.numColumns = 2;
Label label1 = new Label(container, SWT.NULL);
label1.setText("Put here a value");
text1 = new Text(container, SWT.BORDER | SWT.SINGLE);
text1.setText("");
text1.addKeyListener(new KeyListener() {
@Override
public void keyPressed(KeyEvent e) {
}
@Override
public void keyReleased(KeyEvent e) {
if (!text1.getText().isEmpty()) {
setPageComplete(true);
}
}
});
GridData gd = new GridData(GridData.FILL_HORIZONTAL);
text1.setLayoutData(gd);
// Required to avoid an error in the system
setControl(container);
setPageComplete(false);
}
public String getText1() {
return text1.getText();
}
}
package de.vogella.rcp.intro.wizards.wizard;
import org.eclipse.jface.wizard.WizardPage;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.KeyListener;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
public class MyPageTwo extends WizardPage {
private Text text1;
private Composite container;
public MyPageTwo() {
super("Second Page");
setTitle("Second Page");
setDescription("Now this is the second page");
setControl(text1);
}
@Override
public void createControl(Composite parent) {
container = new Composite(parent, SWT.NULL);
GridLayout layout = new GridLayout();
container.setLayout(layout);
layout.numColumns = 2;
Label label1 = new Label(container, SWT.NULL);
label1.setText("Say hello to Fred");
text1 = new Text(container, SWT.BORDER | SWT.SINGLE);
text1.setText("");
text1.addKeyListener(new KeyListener() {
@Override
public void keyPressed(KeyEvent e) {
// TODO Auto-generated method stub
}
@Override
public void keyReleased(KeyEvent e) {
if (!text1.getText().isEmpty()) {
setPageComplete(true);
}
}
});
GridData gd = new GridData(GridData.FILL_HORIZONTAL);
text1.setLayoutData(gd);
Label labelCheck = new Label(container, SWT.NONE);
labelCheck.setText("This is a check");
Button check = new Button(container, SWT.CHECK);
check.setSelection(true);
// Required to avoid an error in the system
setControl(container);
setPageComplete(false);
}
public String getText1() {
return text1.getText();
}
}
Create the class "MyWizard" which extends "org.eclipse.jface.wizard.Wizard".
package de.vogella.rcp.intro.wizards.wizard;
import org.eclipse.jface.wizard.Wizard;
public class MyWizard extends Wizard {
private MyPageOne one;
private MyPageTwo two;
public MyWizard() {
super();
setNeedsProgressMonitor(true);
}
@Override
public void addPages() {
one = new MyPageOne();
two = new MyPageTwo();
addPage(one);
addPage(two);
}
@Override
public boolean performFinish() {
// just put the result to the console, imagine here much more
// intelligent stuff.
System.out.println(one.getText1());
System.out.println(two.getText1());
return true;
}
}
Implement the handler for the command.
package de.vogella.rcp.intro.wizards.handler;
import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.jface.wizard.WizardDialog;
import org.eclipse.ui.handlers.HandlerUtil;
import de.vogella.rcp.intro.wizards.wizard.MyWizard;
public class ShowWizard extends AbstractHandler {
@Override
public Object execute(ExecutionEvent event) throws ExecutionException {
MyWizard wizard = new MyWizard();
WizardDialog dialog = new WizardDialog(HandlerUtil
.getActiveShell(event), wizard);
dialog.open();
return null;
}
}
Run your application and select the menu entry. The wizard should open and after pressing "Finish" you should see the result on the console.
Create a new RCP project "de.vogella.rcp.intro.statusline". Use the "Hello RCP" as the template. Open the class "ApplicationWorkbenchWindowAdvisor" and change method preWindowOpen(). The relevant line in the coding is: "configurer.setShowStatusLine(true);"
package de.vogella.rcp.intro.statusline;
import org.eclipse.swt.graphics.Point;
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);
}
@Override
public void preWindowOpen() {
IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
configurer.setInitialSize(new Point(400, 300));
configurer.setShowCoolBar(false);
configurer.setShowStatusLine(false);
configurer.setTitle("Status Line Example");
configurer.setShowStatusLine(true);
}
}
If you run the application you should already see a status line. At this point the status line does not contain text.
The shared message area can be used by all parts of the application to write messages to this area.
The following write a text to the status line.
package de.vogella.rcp.intro.statusline;
import org.eclipse.jface.action.IStatusLineManager;
import org.eclipse.swt.graphics.Point;
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);
}
@Override
public void preWindowOpen() {
IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
configurer.setInitialSize(new Point(400, 300));
configurer.setShowCoolBar(false);
configurer.setShowStatusLine(false);
configurer.setTitle("Status Line Example");
configurer.setShowStatusLine(true);
}
// This is the new method
@Override
public void postWindowOpen() {
IStatusLineManager statusline = getWindowConfigurer()
.getActionBarConfigurer().getStatusLineManager();
statusline.setMessage(null, "Status line is ready");
}
}
Run your application. You should now see the following.
Add a view with the ID "de.vogella.rcp.intro.statusline.View1" and the implementation class "de.vogella.rcp.intro.statusline.ViewPart1" to your application. This view contains a button to set the status line.
package de.vogella.rcp.intro.statusline;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.SelectionAdapter;
import org.eclipse.swt.events.SelectionEvent;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.IActionBars;
import org.eclipse.ui.part.ViewPart;
public class ViewPart1 extends ViewPart {
boolean pressed = false;
@Override
public void createPartControl(Composite parent) {
Button setStatusLine = new Button(parent, SWT.PUSH);
setStatusLine.setText("Set Statusline ");
setStatusLine.addSelectionListener(new SelectionAdapter() {
public void widgetSelected(SelectionEvent e) {
String message = "I would like to say hello to you.";
if (pressed) {
message = "Thank you for using me";
}
setStatusLine(message);
pressed = !pressed;
}
});
}
private void setStatusLine(String message) {
// Get the status line and set the text
IActionBars bars = getViewSite().getActionBars();
bars.getStatusLineManager().setMessage(message);
}
@Override
public void setFocus() {
}
}
If you run it the result should look like the following.
From an editor you can access the status line via the following:
IEditorPart.getEditorSite().getActionBars();
Perspectives group together and organize UI element that relate to a specific task. Eclipse RCP allows you to add perspectives to your application. The following presents an example.
Create a new RCP project called "de.vogella.rcp.intro.perspective". Use the "RCP application with a view" as a template. In "plugin.xml" add a new extension point "org.eclipse.ui.perspective". Give the perspective the id "de.vogella.rcp.intro.perspective.perspective" and the name "vogella.de Perspective". Change the class name to "de.vogella.rcp.intro.perspective.Perspective".
Click on the "class*" link to create the class.
The method createInitialLayout() in your new class is responsible for creating the new perspective. We re-use the existing view in the coding. After this step the 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;
public class Perspective implements IPerspectiveFactory {
public void createInitialLayout(IPageLayout layout) {
String editorArea = layout.getEditorArea();
layout.setEditorAreaVisible(false);
layout.setFixed(true);
layout.addStandaloneView(View.ID, false, IPageLayout.LEFT, 1.0f, editorArea);
}
}
You can activate the switch between perspectives the ApplicationWorkbenchWindowAdvisor in method preWindowOpen() with configurer.setShowPerspectiveBar(true);
package perspectivetest;
import org.eclipse.jface.preference.IPreferenceStore;
import org.eclipse.swt.graphics.Point;
import org.eclipse.ui.IWorkbenchPreferenceConstants;
import org.eclipse.ui.PlatformUI;
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);
}
public void preWindowOpen() {
IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
configurer.setInitialSize(new Point(400, 300));
configurer.setShowCoolBar(false);
configurer.setShowStatusLine(false);
configurer.setTitle("RCP Application");
configurer.setShowPerspectiveBar(true);
// Set the preference toolbar to the left place
// If other menus exists then this will be on the left of them
IPreferenceStore apiStore = PlatformUI.getPreferenceStore();
apiStore.setValue(IWorkbenchPreferenceConstants.DOCK_PERSPECTIVE_BAR,
"TOP_LEFT");
}
}
You should now be able to select your perspective interactively.
You can re-use the Eclipse perspective switch in a menu via the following standard command "org.eclipse.ui.perspectives.showPerspective". See .
So far your RCP applications can only get started from Eclipse. We will now create a product configuration which will in the next chapter be used to export a program which can run outside the Eclipse IDE.
The equivalent of the Java main() method in Eclipse RCP is the "application". Applications are defined via the extension point "org.eclipse.core.runtime.applications". You can define many application but and only one can be started at a time.
Eclipse defines also "product" which defines all resources that goes with your 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 it not required at runtime.
To create a product you need a product configuration. This configuration file contains all the information about required packages, configuration file, etc. The configuration file is used for exporting / creating your product.
Create a new RCP project "de.vogella.rcp.intro.deploy" based on the "RCP application with a view" template. Run your application to check that is running. Right-click on your project and select New -> Product Configuration.
Name your product configuration "de.vogella.rcp.intro.deploy.product". Select "Create a configuration file with basis settings". Press finish.
Open the file "de.vogella.rcp.intro.deploy.product" and select the "Overview" tab. Maintain the id "de.vogella.rcp.intro.deploy.product" and name "DeployTest" for your product. The name will be displayed in the title of the window.
Press "New" in the "Product Definition" part and select the application of your plugin "de.vogella.rcp.intro.deploy.application".
As a result the "Product Definition" part should now be filled.
The product identifier is stored as the extension "org.eclipse.core.runtime.product" in the file "plugin.xml".
A product can either be based on plugins or . This setting is done on the overview tab. We will use a product definition based on plugins. See for details on how to create a feature project.
Switch to the "Dependencies" Tab and click "Add". Select the plugin "de.vogella.rcp.intro.deploy". Press "Add Required Plug-ins". Save.
On the overview tab press synchronize and then press "Launch an Eclipse application". Synchronize will allign your product configuration with the launch configuration.
The tab "Splash" allows you to specify the plugin 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 and cannot be changed. selecting the corresponding settings.
Create a "splash.bmp" via your favority graphics tool and save it in the "de.vogella.rcp.intro.deploy" project. You can also add a message and a process bar to your splash screen by
If you now start your application you should see a slashscreen. For example I used a screenshot of my webpage.
The standard Eclipse About Dialog can be branded and the . You can add an icon and / or and a text to your application. In this example I do not use this.
To show the "About dialog" add the standard command "org.eclipse.ui.help.about" to your menu. See for information how to use Eclipse standard commands.
In this example I do not use this.
The launcher is the executable program that is created during the deployment of the product. Per default "eclipse.exe" with an "eclipse" icon is created. To change this 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 deep 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.
You created your product configuration. The next chapter will explain how to use this configuration to create an product, e.g. a stand- alone program which can be started outside of Eclipse.
Your product configuration can be used to create a standalone RCP. You export the product and the result can be shared with other users. Eclipse will automatically include all your compiled classes into the build output. You have to manage manually the other files. If you using icons / splash screens images, etc. you have to add them to the build output.
What is included in the build is defined via the file "plugin.xml". Select "plugin.xml" and the build tab. Make sure the "META-INF "directory and the file "plugin.xml" and all other static files, e.g. icons, splash.bmp, are included in the output.
Switch to your product configuration file and select the tab Overview. Click on the "Eclipse Product export wizard" to export your product.
Maintain the target directory and press finish.
If you take the content of this directory and unzip on another machine (which has Java installed) your program should run there too. The export dialog allows to created a Archive file which you can the send directly to your users.
To learn how to automate the creation of a product please see .
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 .
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.
YOu can also deploy your own RCP application to make sure that a certain JRE is used. An Eclipse RCP application first checks in the installation directory for a folder "jre" and for a contained Java-VM. If it find one then this JRE is used to start the Eclipse RCP application.
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.
In general you find lots of good Eclipse articles on
To learn how to use JFace Views you can use
To learn how to use Eclipse Preferences and Preference Pages you can use
Good luck in your journey of learning Eclipse the platform!
Thank you for practicing with this tutorial.
I maintain this tutorial in my private time. If you like the information please help me by donating or byBefore posting questions, please see the . If you have questions or find an error in this article please use the . I have created a short list how to create good questions which might also help you. .