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

Currently development with Eclipse 3.x programming model is much more stable and has better tool support then developing for Eclipse 4.x programming model. On the other hand the Eclipse 4 programming 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 two plugins "org.eclipse.core.runtime" and "org.eclipse.ui". Based on these components an Eclipse RCP application must define the following elements:

The Eclipse application is the equivalent of the Java main() method. Applications are defined via the extension 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 standard Java development. See Eclipse IDE Tutorial if you do not have this knowledge.

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

If you teach programming you basically have two extreme choices. The first approach is that you explain everything first and then do it. The second choice is that you first do everything and then explain what you 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 project structure, 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 do not know how to solve it.

Therefore if you have problem starting your product, I suggest to read the chapter about launch configurations and if that does not help, check the "Products and Branding" chapter.

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 is the equivalent of the main class of standard Java programs. This class is responsible for creating the 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 via the WorkbenchWindow class. A Workbench can have several WorkbenchWindows opened. The inner part of the WorkbenchWindow is represented via the class WorkbenchPage.

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

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

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("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
@Override
public 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 is replaced by the superior command framework.

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 preStartUp() and preShutdown() methods. .

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

SWT is the UI library used by Eclipse. SWT provides the same rich UI components on several platforms using the native widgets of the platform whenever possible. If a widget is not available on a certain platform, SWT emulates the unavailable widget. The native widgets of the OS are accessed by the SWT 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 a user interface. Viewers are available for trees, tables, lists and comboboxes. Please see JFaces Tables Tutorial and JFace Tree Viewer Tutorial for a detailed tutorial.

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.

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 a view" as a template. In plugin.xml add a new extension point "org.eclipse.ui.perspectives". Give the perspective with the id "de.vogella.rcp.intro.perspective.perspective" and the name "vogella.com Perspective". Change the class name to "de.vogella.rcp.intro.perspective.Perspective".

Click on the "class*" link to create the class. The createInitialLayout() method 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);
  }

} 

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

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

package de.vogella.rcp.intro.perspective;

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

  public void preWindowOpen() {
    IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
    configurer.setInitialSize(new Point(400, 300));
    configurer.setShowStatusLine(false);
    configurer.setTitle("RCP Application");
    configurer.setShowPerspectiveBar(true);
  }
} 

You should now be able to select your perspective interactively.

In addition you could re-use the Eclipse command "org.eclipse.ui.perspectives.showPerspective" which 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. 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. 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;
import org.eclipse.ui.application.IWorkbenchWindowConfigurer;
import org.eclipse.ui.application.WorkbenchWindowAdvisor;

public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor {

  private IWorkbenchWindow window;
  private TrayItem trayItem;
  private Image trayImage;

  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.addSelectionListener(new SelectionAdapter() {
      @Override
      public void widgetSelected(SelectionEvent e) {
        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.addMenuDetectListener(new MenuDetectListener() {

      @Override
      public void menuDetected(MenuDetectEvent e) {
        Menu menu = new Menu(window.getShell(), SWT.POP_UP);
        // Creates a new menu item that terminates the program
        MenuItem exit = new MenuItem(menu, SWT.NONE);
        exit.setText("Goodbye!");
        exit.addSelectionListener(new SelectionAdapter() {
          @Override
          public void widgetSelected(SelectionEvent e) {
            window.getWorkbench().close();
          }
        });
        // 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 = Activator.getImageDescriptor("/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 minimized it should not be visible in the taskbar but only in the system tray.

To interact with the Workbench you have access to the Workbench API. For example you can access the active editor or view and open or close Views and Editors.

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. An editor 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 all views 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.

IEditorPart editorPart = page.getActiveEditor();
    if (editorPart != null) {
        // 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 an example how to add such a listener in ApplicationWorkbenchWindowAdvisor.

@Override
  public void postWindowOpen() {
    super.postWindowOpen();
    IWorkbenchPage page = PlatformUI.getWorkbench()
        .getActiveWorkbenchWindow().getActivePage();

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

    page.addPartListener(new IPartListener2() {
      @Override
      public void partVisible(IWorkbenchPartReference partRef) {
        System.out.println("Part visible: " + partRef.getId());
      }

      @Override
      public void partOpened(IWorkbenchPartReference partRef) {
        System.out.println("Part opened: " + partRef.getId());
      }

      @Override
      public void partInputChanged(IWorkbenchPartReference partRef) {
      }

      @Override
      public void partHidden(IWorkbenchPartReference partRef) {
        System.out.println("Part hidden: " + partRef.getId());
      }

      @Override
      public void partDeactivated(IWorkbenchPartReference partRef) {
        System.out.println("Part deactivated:" + partRef.getId());
      }

      @Override
      public void partClosed(IWorkbenchPartReference partRef) {
        System.out.println("Part closed:" + partRef.getId());
      }

      @Override
      public void partBroughtToTop(IWorkbenchPartReference partRef) {
        System.out.println("Part top:" + partRef.getId());
      }

      @Override
      public void partActivated(IWorkbenchPartReference partRef) {
        System.out.println("Part activated: " + partRef.getId());
      }
    });
  } 

You can access files in your plug-in via two different approaches: via the FileLocator class or via an Eclipse specific URL. Both approaches require that your plug-in defines a dependency to the org.eclipse.core.runtime plug-in.

Both approaches return a URL which can be used to get an InputStream.

The following code shows an example with FileLocator.

Bundle bundle = FrameworkUtil.getBundle(this.getClass());
URL url = FileLocator.find(bundle, 
  new Path("path_to_file"), null); 

The following code shows an example for the usage of the Eclipse specific URL.

URL url = null;

try {

  url = new URL("platform:/plugin/" 
    + "your_bundle-symbolicname"
  + "path_to_file");
  
  } catch (MalformedURLException e1) {
    e1.printStackTrace();
} 

Using the URL to create an InputStream and to read the file is demonstrated in the next code example.

public String readTextFile(URL url) {
  InputStream inputStream = null;
  String output = "";
   try {
    inputStream = url.openConnection().getInputStream();
    BufferedReader in = 
        new BufferedReader(new InputStreamReader(inputStream));
    String inputLine;

    while ((inputLine = in.readLine()) != null) {
      output += inputLine;
    }
    in.close();

   } catch (IOException e) {
    e.printStackTrace();
  } finally {
    if (inputStream != null) {
      try {
        inputStream.close();
      } catch (IOException e) {
        e.printStackTrace();
      }
    }
  }
  return output;
} 

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