A minimal plug-in

We all know what "Hello World" looks like in plain old Java without using any user interface or other framework.

   public class HelloWorld {
      public static void main(String[] args) {
         System.out.println("Hello World");
      }
   }

What happens to this old standard in the context of the Eclipse platform? Instead of thinking of Hello World as a self-contained program, we recast it as an extension of the platform. Since we want to say hello to the world, we need to figure out how to extend the workbench to include our greeting.

When we get deeper into the platform user interface components, we'll do an exhaustive review of the ways that you can extend and customize the workbench UI. For now, let's start with one of the simplest workbench extensions - a view. 

You can think of the workbench window as a frame that presents various visual parts. These parts fall into two major categories: views and editors.  We will look at editors later.  Views provide information about some object that the user is working with in the workbench. Views often change their content as the user selects different objects in the workbench.

Hello world view

For our hello world plug-in, we will implement our own view to greet the user with "Hello World."

The package org.eclipse.ui and its sub packages contain the public interfaces that define the workbench user interface (UI) API. Many of these interfaces have default implementation classes that you can extend to provide simple modifications to the system. In our hello world example, we will extend a workbench view to provide a label that says hello.

The interface of interest is IViewPart, which defines the methods that must be implemented to contribute a view to the workbench. The class ViewPart provides a default implementation of this interface. In a nutshell, a view part is responsible for creating the widgets needed to show the view.

The standard views in the workbench often display some information about an object that the user has selected or is navigating. Views update their contents based on actions that occur in the workbench. In our case, we are just saying hello, so our view is quite simple.

Using the tools to write our plug-in

You can use any Java IDE you wish to build Eclipse plug-ins, but we'll walk through the steps for building our plug-in with the Eclipse Java IDE.  If you are not already familiar with the Eclipse workbench and the Java IDE, consult the Java Development User Guide for further explanations of the steps we are taking.  For now we are focusing on the code, not the tool.  However, there are some IDE logistics for getting started.

Setting up your environment

If you are starting with a clean environment, you will need to ensure that your code has access to the plug-ins org.eclipse.ui. Import this plug-in and any plug-ins it requires into your run-time workbench instance by performing the steps below. If you already have these plug-ins in your workbench instance, proceed to the section "Creating your plug-in project".

  1. From the resource perspective, use File > Import... > External Plug-ins and Fragments.
  2. Continue clicking on the Next > buttons until you get to the screen called Selection. This screen will contain a list of all of the plug-ins in your host workbench instance.
  3. Select org.eclipse.ui and then click the button Add Required Plug-ins.
  4. Click on the Finish button. Your Navigator view should contain org.eclipse.ui and all of the plug-ins it requires (including org.eclipse.swt).

For a complete discussion of setting up host and run-time workbench instances consult the PDE Guide.

Creating your plug-in project

  1. You will need to create a project to do your work.  The simplest way is to open the New Project... wizard (File > New > Project...) and choose Plug-in Project from the Plug-in Development category.  This will set up your project for writing Java code and give you a default plug-in manifest file (explained in a moment.)  Use org.eclipse.examples.helloworld as the name for your project. By default, the wizard sets org.eclipse.examples.helloworld as the id as well.  The wizard gives you the option of generating code for different kinds of plug-ins, but we want to keep this simple.  For now, be sure to choose Create a blank plug-in project on the Plug-in Code Generators page.
  2. When asked if you would like to switch to the Plug-in Development perspective, answer Yes.
  3. Create a package org.eclipse.examples.helloworld underneath the src directory for the project. To do this, double click on the project org.eclipse.examples.helloworld in the Package Explorer view. This expands the project and shows you the src directory. Right click on the src directory to get the context menu. Use New > Package to create a new package and give it the name org.eclipse.examples.helloworld
  4. Create a new class called HelloWorldView in this package. Right click on the package you just created in the previous step to get the context menu. Use New > Class to create your new class with the name HelloWorldView.

Writing the code

Now we're ready to study some code.  Here is everything you need in your HelloWorldView.  (You can copy the contents below into the class you created.) 

   package org.eclipse.examples.helloworld;

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

   public class HelloWorldView extends ViewPart {
      Label label;
      public HelloWorldView() {
      }
      public void createPartControl(Composite parent) {
         label = new Label(parent, SWT.WRAP);
         label.setText("Hello World");
      }
      public void setFocus() {
         // set focus to my widget.  For a label, this doesn't
         // make much sense, but for more complex sets of widgets
         // you would decide which one gets the focus.
      }
   }

The view part creates the widgets that will represent it in the createPartControl method. In this example, we create an SWT label and set the "Hello World" text into it. 

This is all we need!  We can compile our new class, but we better make sure that our .classpath is set up properly so that we can compile the code.  

  1. Select the org.eclipse.examples.helloWorld project and open the Properties dialog (right click on the project org.eclipse.examples.helloWorld > Properties).
  2. In the Java Build Path properties, select the Projects tab, and check the projects  org.eclipse.ui and org.eclipse.swt. These are the projects that contain the classes we imported.
  3. Rebuild the project. 

Okay, so we've compiled the view.  Our new view is supposed to look something like this:

Simple view that says Hello World

How do we run the code and add this view to the workbench?

The hello world plug-in

We need to inform the platform that we want to contribute our view. This is done by extending the org.eclipse.ui.views extension point. We register our extension by providing a manifest file, plugin.xml, which describes our plug-in, including where its code is located, and the extension we are adding.

(If you are still following along, you can copy this information into the plugin.xml that was generated when you created the project.)

   <?xml version="1.0" ?>
   <plugin
      name="Hello World Example" 
      id="org.eclipse.examples.helloworld"
      version="1.0">
      <requires>
         <import plugin="org.eclipse.ui" />
      </requires>
      <runtime>
         <library name="helloworld.jar" />
      </runtime>
      <extension point="org.eclipse.ui.views">
         <category 
            id="org.eclipse.examples.helloworld.hello"
            name="Hello" />
         <view 
            id="org.eclipse.examples.helloworld.helloworldview"
            name="Hello Greetings"
            category="org.eclipse.examples.helloworld.hello"
            class="org.eclipse.examples.helloworld.HelloWorldView" />
      </extension>
   </plugin>

In this file, we define the name, id, and version for our plug-in.

We also list our required plug-ins. Since we use workbench and SWT API in our plug-in, we must list org.eclipse.ui. We must also describe where our executable code is located. We intend to package the code in helloworld.jar, so we register that as our library name.

Finally, we declare what extension point our plug-in is contributing. The org.eclipse.ui.views extension has several different configuration parameters. We first declare a category for our view extension. Categories can be used to group related views together in the workbench Show View dialog. We define our own category, "Hello," so that it will display in its own group.  We declare a unique id for our view and specify the name of the class that provides the implementation of the view. We also specify a name for the view, "Hello Greetings" which will be shown in the Show View dialog and in our view's title bar.

Plug-in ids

There are many ids used in a plug-in manifest file. Individual extension points often define configuration parameters that require ids (such as the category id used above for the views extension point). We also define a plug-in id. In general, you should use Java package name prefixes for all of your ids in order to ensure uniqueness among all the installed plug-ins. 

The specific name that you use after the prefix is completely up to you. However, if your plug-in id prefix is exactly the same name as one of your packages, you should avoid using class names from that package.   Otherwise it will become difficult to tell whether you are looking at an id name or a class name. 

You should also avoid using the same id for different extension configuration parameters. In the above manifest, we have used a common id prefix (org.eclipse.examples.helloworld) but all of our ids are unique.  This naming approach helps us to read the file and see which ids are related. 

What next?

At this point, we have implemented a view and declared our contribution in our plug-in manifest.  Now we need to install our plug-in into the platform so that we can run it.

Copyright IBM Corporation and others 2000, 2003.