Support free tutorials:











vogella training Training Books



Eclipse Forms API - Tutorial

Lars Vogel

Version 0.3

27.11.2010

Revision History
Revision 0.1 03.05.2009 Lars
Vogel
created
Revision 0.3 27.11.2010 Lars
Vogel
bug fixes and enhancements

Eclipse Forms API

This article describes how to build User Interfaces using Eclipse Forms.


Table of Contents

1. Eclipse Forms
1.1. Overview
1.2. Form / ScrolledForm
2. Forms Example
2.1. First Example
2.2. Adding command to the menu
3. Support this website
3.1. Thank you
3.2. Questions and Discussion
4. Links and Literature
4.1. Source Code
4.2. vogella Resources

1. Eclipse Forms

1.1. Overview

Eclipse supports a web-like user interface style, called Eclipse Forms. Eclipse Forms is a plugin based on SWT and JFace that provides the support for creating portable web-style user interfaces across all Eclipse UI categories. The Eclipse forms functionality is contained in the plug-in "org.eclipse.ui.forms".

The class FormToolkit serves as a factory for the creation of the required user interface elements. This factory adjust the look and feel of the standard SWT and JFace elements to the Forms API. Existing UI elements can be enhanced to the form API via the method adapt(Composite).

1.2. Form / ScrolledForm

FormToolkit provides Form or ScrollForm which are serves as the frame for the user interface elements. They provide a header, a toolbar and a body. The body can get accessed via getBody() and contains other ui elements.

2. Forms Example

2.1. First Example

Create a new Eclipse RCP project "de.vogella.rcp.intro.forms". Use the "RCP Application with a view" as a template. Add a dependency to "org.eclipse.ui.forms" in plugin.xml. You do this via selecting the Dependencies tab. Press the "Add" button and type in the name of "org.eclipse.ui.forms".

Change the View.java to the following. This will create a re-sizable table in a form with a button on the right side of it.

package de.vogella.rcp.intro.forms;

import org.eclipse.jface.viewers.ArrayContentProvider;
import org.eclipse.jface.viewers.ColumnLabelProvider;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.jface.viewers.TableViewerColumn;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Image;
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.Table;
import org.eclipse.ui.ISharedImages;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.forms.widgets.FormToolkit;
import org.eclipse.ui.forms.widgets.ScrolledForm;
import org.eclipse.ui.forms.widgets.Section;
import org.eclipse.ui.part.ViewPart;

public class View extends ViewPart {
  public static final String ID = "de.vogella.rcp.intro.forms.view";

  private TableViewer viewer;

  
/** * This is a callback that will allow us to create the viewer and initialize * it. */
public void createPartControl(Composite parent) { FormToolkit toolkit = new FormToolkit(parent.getDisplay()); ScrolledForm form = toolkit.createScrolledForm(parent); form.setText("Eclipse Forms API Example"); // Lets make a layout for the first section of the screen GridLayout layout = new GridLayout(); layout.numColumns = 1; layout.marginWidth = 2; layout.marginHeight = 2; // Creating the Screen Section section = toolkit.createSection(parent, Section.DESCRIPTION | Section.TITLE_BAR); section.setText("Section 1 for demonstration"); //$NON-NLS-1$ section.setDescription("This demonstrates the usage of section"); // Composite for storing the data Composite client = toolkit.createComposite(section, SWT.WRAP); layout = new GridLayout(); layout.numColumns = 2; layout.marginWidth = 2; layout.marginHeight = 2; client.setLayout(layout); Table t = toolkit.createTable(client, SWT.NONE); GridData gd = new GridData(GridData.FILL_BOTH); gd.heightHint = 20; gd.widthHint = 100; t.setLayoutData(gd); toolkit.paintBordersFor(client); Button b = toolkit.createButton(client, "Do something", SWT.PUSH); //$NON-NLS-1$ gd = new GridData(GridData.VERTICAL_ALIGN_BEGINNING); b.setLayoutData(gd); section.setClient(client); viewer = new TableViewer(t); viewer.setContentProvider(new ArrayContentProvider()); TableViewerColumn viewerColumn = new TableViewerColumn(viewer, SWT.NONE); viewerColumn.getColumn().setWidth(100); viewerColumn.setLabelProvider(new ColumnLabelProvider() { @Override public String getText(Object element) { return element.toString(); }; public Image getImage(Object element) { return PlatformUI.getWorkbench().getSharedImages() .getImage(ISharedImages.IMG_OBJ_ELEMENT); }; }); viewer.setInput(getViewSite()); }
/** * Passing the focus request to the viewer's control. */
public void setFocus() { viewer.getControl().setFocus(); } }

The result should look like the following:

2.2. Adding command to the menu

You can also add Eclipse Commands to the menu of the form. For this define a command with a handler. Add this command to a popup menu contribution as for example in the following plugin.xml.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>

   <extension
         id="application"
         point="org.eclipse.core.runtime.applications">
      <application>
         <run
               class="de.vogella.rcp.intro.forms.Application">
         </run>
      </application>
   </extension>
   <extension
         point="org.eclipse.ui.perspectives">
      <perspective
            name="Perspective"
            class="de.vogella.rcp.intro.forms.Perspective"
            id="de.vogella.rcp.intro.forms.perspective">
      </perspective>
   </extension>
   <extension
         point="org.eclipse.ui.views">
      <view
            name="View"
            class="de.vogella.rcp.intro.forms.View"
            id="de.vogella.rcp.intro.forms.view">
      </view>
   </extension>
   <extension
         point="org.eclipse.ui.commands">
      <command
            defaultHandler="de.vogella.rcp.intro.forms.handler.HelloHandler"
            id="de.vogella.rcp.intro.forms.hello"
            name="Hello">
      </command>
   </extension>
   <extension
         point="org.eclipse.ui.menus">
      <menuContribution
            allPopups="false"
            locationURI="popup:formsToolBar">
         <command
               commandId="de.vogella.rcp.intro.forms.hello"
               icon="icons/alt_window_16.gif"
               label="Hello"
               style="push">
         </command>
      </menuContribution>
   </extension>

</plugin> 

Change the view to display the command in the form and you should see the command in your form.

package de.vogella.rcp.intro.forms;

import org.eclipse.jface.action.ToolBarManager;
import org.eclipse.jface.viewers.ArrayContentProvider;
import org.eclipse.jface.viewers.ColumnLabelProvider;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.jface.viewers.TableViewerColumn;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Image;
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.Table;
import org.eclipse.ui.ISharedImages;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.forms.widgets.FormToolkit;
import org.eclipse.ui.forms.widgets.ScrolledForm;
import org.eclipse.ui.forms.widgets.Section;
import org.eclipse.ui.menus.IMenuService;
import org.eclipse.ui.part.ViewPart;

public class View extends ViewPart {
  public static final String ID = "de.vogella.rcp.intro.forms.view";

  private TableViewer viewer;

  
/** * This is a callback that will allow us to create the viewer and initialize * it. */
public void createPartControl(Composite parent) { FormToolkit toolkit = new FormToolkit(parent.getDisplay()); ScrolledForm form = toolkit.createScrolledForm(parent); ToolBarManager manager = (ToolBarManager) form.getToolBarManager(); toolkit.decorateFormHeading(form.getForm()); IMenuService menuService = (IMenuService) getSite().getService(IMenuService.class); menuService.populateContributionManager(manager, "popup:formsToolBar"); manager.update(true); form.setText("Eclipse Forms API Example"); // Lets make a layout for the first section of the screen GridLayout layout = new GridLayout(); layout.numColumns = 1; layout.marginWidth = 2; layout.marginHeight = 2; // Creating the Screen Section section = toolkit.createSection(parent, Section.DESCRIPTION | Section.TITLE_BAR); section.setText("Section 1 for demonstration"); //$NON-NLS-1$ section.setDescription("This demonstrates the usage of section"); // Composite for storing the data Composite client = toolkit.createComposite(section, SWT.WRAP); layout = new GridLayout(); layout.numColumns = 2; layout.marginWidth = 2; layout.marginHeight = 2; client.setLayout(layout); Table t = toolkit.createTable(client, SWT.NONE); GridData gd = new GridData(GridData.FILL_BOTH); gd.heightHint = 20; gd.widthHint = 100; t.setLayoutData(gd); toolkit.paintBordersFor(client); Button b = toolkit.createButton(client, "Do something", SWT.PUSH); //$NON-NLS-1$ gd = new GridData(GridData.VERTICAL_ALIGN_BEGINNING); b.setLayoutData(gd); section.setClient(client); viewer = new TableViewer(t); viewer.setContentProvider(new ArrayContentProvider()); TableViewerColumn viewerColumn = new TableViewerColumn(viewer, SWT.NONE); viewerColumn.getColumn().setWidth(100); viewerColumn.setLabelProvider(new ColumnLabelProvider() { @Override public String getText(Object element) { return element.toString(); }; public Image getImage(Object element) { return PlatformUI.getWorkbench().getSharedImages() .getImage(ISharedImages.IMG_OBJ_ELEMENT); }; }); viewer.setInput(getViewSite()); }
/** * Passing the focus request to the viewer's control. */
public void setFocus() { viewer.getControl().setFocus(); } }

3. Support this website

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

3.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

3.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

4. Links and Literature

4.1. Source Code

Source Code of Examples

4.2. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system

http://www.eclipse.org/articles/Article-Forms/article.html Article about Eclipse Forms