NOW Hiring

Quick links

Eclipse JFace Tutorial. This tutorial gives a overview about Eclipse JFace. It discusses the base concept of JFace Viewers and the JFace LocalResourceManager. The tutorial is based on Eclipse 4.4 (Luna).

1. What is Eclipse JFace?

Eclipse JFace is a set of plug-ins based upon the user interface toolkit SWT. JFace provides classes and frameworks which simplify common SWT use cases. JFace does not hide the SWT API; therefore, SWT knowledge is still required.

JFace provides the viewers framework, which simplifies the mapping of a data model to a visual representation. For example you find viewers for ComboBoxes, Tables and Trees.

JFace also provides helper classes to effectively manage your system resources, like colors, images and fonts.

In addition JFace provides support for handling preferences, preference pages, wizards and dialogs. It also contains functionality to support icon decorations and user-input help for SWT controls.

JFace Data Binding is a framework which connects properties of objects. It is typically used to synchronize fields of the user interface with properties of model objects and allows you to include validation and conversion in this synchronization process.

2. JFace resource manager for Colors, Fonts and Images

SWT is based on the native widgets of the OS. Whenever an SWT widget is allocated, a corresponding OS specific widget is created. The Java garbage collector cannot automatically clean-up these OS-specific widget references.

Fortunately all widgets which are created based on a parent widget are automatically disposed when the parent Composite is disposed. If you develop Eclipse plug-ins, the Composite of a part is automatically disposed once the part is closed. Therefore, these SWT widgets are handled automatically in Eclipse plug-in projects.

This rule does not apply for colors, fonts and images, as these may be reused in other places. For this reason, they need to be explicitly disposed. Fortunately JFace provides the ResourceManager and its derived classes.

An instance of the LocalResourceManager class is created with a reference to a Control. If this Control is disposed, the resources created by the LocalResourceManager are also disposed.

// create the manager and bind to a widget
ResourceManager resManager =
        new LocalResourceManager(JFaceResources.getResources(), composite);

// create resources
Color color = resManager.createColor(new RGB(200, 100, 0));
Font font = resManager.
        createFont(FontDescriptor.createFrom("Arial", 10, SWT.BOLD));
// get an imageDescriptor and create Image object
Image image = resManager.createImage(imageDescriptor);

The createImage() method expects an ImageDescriptor class.

To get one ImageDescriptor from an image file stored in your current plug-in use the following:

Bundle bundle = FrameworkUtil.getBundle(this.getClass());
// use the org.eclipse.core.runtime.Path as import
URL url = FileLocator.find(bundle,
        new Path("icons/alt_window_32.gif"), null);
ImageDescriptor imageDescriptor = ImageDescriptor.createFromURL(url);

In case you do not have an instance of Control, the`LocalResourceManager` also provides another constructor.

A popular example is a LabelProvider, where you wouldn’t want to pass a Control to it in order to properly dispose system resources afterwards:

public class ResourceUsingLabelProvider extends LabelProvider {

    private ResourceManager resourceManager = new LocalResourceManager(JFaceResources.getResources());

    public Image getImage(Object element) {
        if (element instanceof Task) {
            Bundle bundle = FrameworkUtil.getBundle(this.getClass());
            // use the org.eclipse.core.runtime.Path as import
            URL url = FileLocator.find(bundle, new Path("icons/task.png"), null);
            ImageDescriptor imageDescriptor = ImageDescriptor.createFromURL(url);

            // return the image being created by the resourceManager
            return resourceManager.createImage(imageDescriptor);

        return super.getImage(element);

    public void dispose() {

        // dispose the ResourceManager yourself

In case you do not pass a Control, to the LocalResourceManager. You have to dispose the ResourceManager yourself.

You should use always use a JFace ResouceManager if possible. This avoids problems with system resources or even a "No more handles" SWTException.

3. ControlDecoration

The ControlDecoration class allows you to place image decorations on SWT controls to show additional information about the control. These decorations can also have a description text which is 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.

The following code snippet shows how to create ControlDecoration and how to set a description and an icon to it.

// create the decoration for the text UI component
final ControlDecoration deco =
 new ControlDecoration(text, SWT.TOP | SWT.RIGHT);

// re-use an existing image
Image image = FieldDecorationRegistry.
// set description and image
deco.setDescriptionText("This is a tooltip text");
// hide deco if not in focus

You can hide and show the decoration via the corresponding methods as demonstrated in the following code snippet.


4. User input help with field assistance

The org.eclipse.jface.fieldassist package provides assistance to define user-input help for a widget, e.g., a text field or combo box. The ContentProposalAdapter class is responsible for providing the possible input values.

In the following example the content proposal should get activated via certain keys ("." and "#") as well as the Ctrl+Space key combination.

The following code demonstrates the usage of the field assistance functionality. It also uses the ControlDecoration class.

GridLayout layout = new GridLayout(2, false);
// parent is a Composite
Label lblPleaseEnterA = new Label(parent, SWT.NONE);
lblPleaseEnterA.setText("Please enter a value:");

Text text = new Text(parent, SWT.BORDER);
GridData gd_text = new GridData(SWT.FILL, SWT.CENTER, true, false);
gd_text.horizontalIndent = 8;
GridData data = new GridData(SWT.FILL, SWT.TOP, true, false);

// create the decoration for the text component
final ControlDecoration deco = new ControlDecoration(text, SWT.TOP
        | SWT.LEFT);

// use an existing image
Image image = FieldDecorationRegistry.getDefault()

// set description and image
deco.setDescriptionText("Use CTRL + SPACE to see possible values");

// always show decoration

// hide the decoration if the text component has content
text.addModifyListener(new ModifyListener() {
        public void modifyText(ModifyEvent e) {
                Text text = (Text) e.getSource();
                if (!text.getText().isEmpty()) {
                } else {

// help the user with the possible inputs
// "." and "#" activate the content proposals
char[] autoActivationCharacters = new char[] { '.', '#' };
KeyStroke keyStroke;
try {
        keyStroke = KeyStroke.getInstance("Ctrl+Space");
        ContentProposalAdapter adapter = new ContentProposalAdapter(text,
                new TextContentAdapter(),
                new SimpleContentProposalProvider(new String[] {
                        "ProposalOne", "ProposalTwo", "ProposalThree" }),
                        keyStroke, autoActivationCharacters);
                } catch (ParseException e1) {

If used the result should look similar to the following.

Running application with ControlDecoration and FieldAssists

5. Eclipse JFace Viewers

5.1. Purpose of the JFace viewer framework

The JFace viewer framework allows you to display a domain model in a standard SWT widget like list, combo, tree or table without converting the domain model beforehand.

A viewer allows you to set a content provider which provides the data for the viewer. The content provider makes no assumption about the presentation of the data model.

You can also assign at least one label provider to a viewer. The label provider defines how the data from the model will be displayed in the viewer.

5.2. Standard JFace viewer

JFace provides several standard viewer implementations. These viewers are part of the org.eclipse.jface.viewers package. The following list contains the most important ones.

  • ComboViewer

  • ListViewer

  • TreeViewer

  • TableViewer

5.3. Standard content and label provider

The related interfaces for defining a content provider are described in the following table.

Table 1. Content providers
Interface Default implementation Description



Used for the List-, Combo- and TableViewer. JFace provides a default implementation for Collections and Arrays with the ArrayContentProvider class. Because the ArrayContentProvider class does not store any data, it is possible to share an instance with several viewers. To get a shared instance use the ArrayContentProvider.getInstance() method.


Not available

Used for the TreeViewer class. Has additional methods to determine the children and the parents of the elements.

Important standard label providers are listed in the following table.

Table 2. Label providers
Required class Standard label providers Description



Used for lists and trees, can return an icon and a label per element.



Used for tables. Defines a label provider per column.

6. JFace ComboViewer

A simple example for a JFace Viewer framework is the ComboViewer class. Assume the following data model.

package com.vogella.eclipse.viewer;

public class Person {
        private String firstName;
        private String lastName;
        private boolean married;

        public Person(String firstName, String lastName) {
                this.firstName = firstName;
                this.lastName = lastName;

        public String getFirstName() {
                return firstName;

        public void setFirstName(String firstName) {
                this.firstName = firstName;

        public String getLastName() {
                return lastName;

        public void setLastName(String lastName) {
                this.lastName = lastName;

        public boolean isMarried() {
                return married;

        public void setMarried(boolean married) {
                this.married = married;

The following example snippet shows you how you could use this given data model in a ComboViewer.

// the following code is executed by the method which
// creates the user interface
// assumes parent is an SWT Composite

GridLayout layout = new GridLayout(2, false);

Label label = new Label(parent, SWT.NONE);
label.setText("Select a person:");
final ComboViewer viewer = new ComboViewer(parent, SWT.READ_ONLY);

// the ArrayContentProvider object does not store any state,
// therefore, you can re-use instances

viewer.setLabelProvider(new LabelProvider() {
        public String getText(Object element) {
                if (element instanceof Person) {
                        Person person = (Person) element;
                        return person.getFirstName();
                return super.getText(element);

Person[] persons = new Person[] { new Person("Lars", "Vogel"),
        new Person("Tim", "Taler"), new Person("Jim", "Knopf") };

// set the input of the Viewer,
// this input is send to the content provider


// note: the order of setContentProvider and setInput is important

You can register a listener which is notified whenever the selection of the viewer changes via the following code.

// react to the selection change of the viewer
// note that the viewer returns the actual object

viewer.addSelectionChangedListener(new ISelectionChangedListener() {
        public void selectionChanged(SelectionChangedEvent event) {
                IStructuredSelection selection = (IStructuredSelection) event
                if (selection.size() > 0){
                        System.out.println(((Person) selection.getFirstElement())

You can get and set selections using Java objects based on your domain model.

// you can select an object directly via the domain object
Person person = persons[0];
viewer.setSelection(new StructuredSelection(person));

// retrieves the selection, returns the data model object
IStructuredSelection selection = viewer.getStructuredSelection();
Person p = (Person) selection.getFirstElement();

7. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book.

8. About this website

9. JFace resources

9.1. vogella GmbH training and consulting support


The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2016 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.