Saturday, November 8, 2008

Adding a View to an Eclipse RCP Application

As shown in the article Hello World with Eclipse RCP - Your First Application, it is quite simple to create and run your own very basic Java RCP application using Eclipse. This article shows you how to add a "View" to your application. Part of learning how to create RCP applications using Eclipse is to learn the terminology people use. A view is the part of your application where you put things like tables, buttons, combo boxes, labels, charts, etc. - all the graphical interfaces that a user will interact with when using your application. These visible units of interaction are called "widgets" and Eclipse provides us with many customizable widgets in the SWT and JFACE libraries.

When an RCP application starts up, a string of events occurs under the hood that generates a stand-alone window containing all your customized widgets that give your program its unique look and functionality. At the top of the hierarchy is the Application class and contains the application's main method (actually called "start()"). In the start() method, a single Workbench object is created, which is a behind-the-scenes class controlling your RCP application. The Workbench in turn contains one or more WorkbenchWindow objects, which are the visible windows making up your program. In most cases you just have one WorkbenchWindow. A WorkbenchWindow in turn contains a menu (optional), a toolbar (optional), and/or one or more Perspective objects. In most cases you just have one Perspective. A Perspective in turn contains one Editor object and/or one or more View objects. View objects in turn contain one or more Widgets, which are the finest grain visible units of the RCP application. As a visual example of all this, look at the following BitTorrent application called Vuze (aka Azureus). You see a WorkbenchWindow with a menu, a toolbar, and two views called "My Torrents" and "Statistics". The "Statistics" view contains Tab widgets which in turn contain other widgets.





As a review, the hierarchy is like this:

Application
|
Workbench
|
WorkbenchWindow(s)
|
Perspective(s) Menu Toolbar
|
View(s) Editor
|
SWT and/or JFace Widget(s)

When Eclipse set up a HelloWorld RCP application for you with a wizard described here, it generated an Application, a Workbench, and a WorkbenchWindow with a Perspective. This article shows how to build off of that, by adding a View with a Label widget containing some text to the View. Let's get to it...

Step 0: Create a HelloWorld RCP application.

Step 1: Add the "views" extension point to your RCP project. Click on the "Extensions" tab along the bottom of the view in Eclipse that shows all the properties for your RCP project. If you don't see that view, double-click on "MANIFEST.MF" in the "META-INF" folder in your project folder in the Package Explorer. Here, you need to add an extension point to your application. Click "Add..." and a dialog box will pop up for selecting a new extension point. Scroll down and find the extension point called "org.eclipse.ui.views", select it and click "Finish".


Step 2: Add a View to your RCP project. You should now see the org.eclispe.ui.views extension added to the "All Extensions" list for your project. Right-click on "org.eclispe.ui.views" and select New --> view.


Step 3: Set the properties of the View. Make sure the View is highlighted in the All Extensions list. To the right you will be able to set some properties of the view. For right now, just the first two properties need to be set. In this example an id of com.blogspot.eclipsercptutorials.mainView and a name of MainView.


Step 4: Generate the view's class. In the properties list click on the "class" link. This will bring up a wizard. Leave everything at the default values but give it a name that matches the name you entered in the name property before. Click "Finish".

Step 5: Add some code to the MainView class that you generated earlier. You need to make sure a "public static final String" field called ID is defined and set equal to the id that you set in the view's properties editor. Also, in createPartControl() add two lines of code that creates a Label widget and set it's text. You may find that when you add the Label code you get an error "Label cannot be resolved to a type". This is because you haven't added an import statement yet above the class definition. The import statements tell the compiler what classes your class will be using. If you ever get an error like that, you can click on the class name, i.e. "Label", in your code and type ctrl+m (windows or Linux) or command+m (Mac). Make sure to always choose the SWT version of the widget and not the Swing or other type of class with the same name.

package com.blogspot.obscuredclarity.addview;

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

public class MainView extends ViewPart {

public static final String ID = "com.blogspot.eclipsercptutorials.mainView"; // the ID needs to match the id set in the view's properties

public MainView() { }

public void createPartControl(Composite parent) {

Label label = new Label(parent, SWT.None); //new up a Label widget
label.setText("  All this program does is display this text in a view."); //set the label's text

}

public void setFocus() { }

}


Step 6: Add the view to the application's perspective. Remember how when you used the wizard in Eclipse to create a standalone HelloWrold application and it generated a perspective for you automatically? And remember that views are children of perspectives? The Perspective class in your project should look similar to the following if you want it to add your new view. Open Perspective.java and add the two lines of code shown below in the createInitialLayout method.

package com.blogspot.obscuredclarity.addview;

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

public class Perspective implements IPerspectiveFactory {

public void createInitialLayout(IPageLayout layout) {

layout.addStandaloneView(MainView.ID, false, IPageLayout.LEFT, 1.0f, layout.getEditorArea());
layout.setEditorAreaVisible(false); //hide the editor in the perspective
}
}


Step 7: Run your application. Congrats, you now have an Eclipse RCP application with a view! The view gives you a place to add more widgets and add funtionality to your program. The next things you'll want to add to your program are things like a menu, an editor, more views, status bars, a toolbar, and widgets.




Next ---> Add an Icon to an Eclipse RCP Application View
<--- Previous - Hello World with Eclipse RCP - Your First Application
Also see: Eclipse RCP Tutorial Table of Contents

5 comments:

Anonymous said...

Great tutorial, thank you.

Unknown said...

Great thank you

dendy said...

hi...i'm dendy from indonesian.me reading you tutorial add knowledge for me about eclipse rcp.thank you..

Paula said...

Thanks! :)

Srijani said...

Thanks for such a wonderful tutorial.
But, when I am trying to replicate each and every steps mentioned here and then run the project, it displays no text in the window.
Can you please help me to resolve this?

Thanks!