Support free tutorials:











vogella training Training Books



Eclipse JFace Overview - Tutorial

Lars Vogel,

Version 2.9

07.10.2014

Revision History
Revision 0.1 - 2.9 01.07.2007 - 07.10.2014 Lars
Vogel
created, bug fixes and enhancements

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).


Table of Contents

1. What is Eclipse JFace?
2. JFace resource manager for Colors, Fonts and Images
3. ControlDecoration
4. User input help with field assistance
5. Eclipse JFace Viewers
5.1. Purpose of the JFace viewer framework
5.2. Standard JFace viewer
6. JFace ComboViewer
7. Learn more about Eclipse 4 RCP development
8. Support this website
8.1. Thank you
8.2. Questions and Discussion
9. Links and Literature
9.1. Source Code
9.2. JFace resources
9.3. Other JFace Resources
9.4. vogella Resources

Get the book Eclipse RCP book

1. What is Eclipse JFace?

Eclipse JFace is 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.

It provides the JFace Viewers which simplify 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 system. Whenever a 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 LocalResourceManager class.

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

// create the manager and bind to a widget
LocalResourceManager 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); 

To create the Image directly from the ImageDescriptor you can use the createImage() method on the ImageDescriptor object.

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.
  getDefault().
  getFieldDecoration(FieldDecorationRegistry.DEC_INFORMATION).
  getImage();
// set description and image
deco.setDescriptionText("This is a tooltip text");
deco.setImage(image);
// hide deco if not in focus
deco.setShowOnlyOnFocus(true); 

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

deco.hide();
deco.show(); 

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. 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
parent.setLayout(layout);
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;
text.setLayoutData(gd_text);
GridData data = new GridData(SWT.FILL, SWT.TOP, true, false);
text.setData(data);

// 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()
  .getFieldDecoration(FieldDecorationRegistry.DEC_INFORMATION)
  .getImage();

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

// always show decoration
deco.setShowOnlyOnFocus(false);

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

// 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) {
  e1.printStackTrace();
} 

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. The following list contains the most important ones.

  • ComboViewer

  • ListViewer

  • TreeViewer

  • TableViewer

These viewers are part of the org.eclipse.jface.viewers package.

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

Table 1. Content providers

Class Description
IStructuredContentProvider Used for the List-, Combo- and TableViewer. JFace provides a default implementation for Collections and Arrays with the ArrayContentProvider class.
ITreeContentProvider Used for the TreeViewer class. Has additional methods to determine the children and the parents of the elements.


Tip

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.

Important standard label providers are listed in the following table.

Table 2. Label providers

Required class Standard label providers Description
ILabelProvider LabelProvider Used for lists and trees, can return an icon and a label per element.
CellLabelProvider ColumnLabelProvider 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 a SWT Composite

GridLayout layout = new GridLayout(2, false);
parent.setLayout(layout);


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.setContentProvider(ArrayContentProvider.getInstance());
viewer.setLabelProvider(new LabelProvider() {
  @Override
  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

viewer.setInput(persons); 

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() {
  @Override
  public void selectionChanged(SelectionChangedEvent event) {
    IStructuredSelection selection = (IStructuredSelection) event
      .getSelection();
    if (selection.size() > 0){
      System.out.println(((Person) selection.getFirstElement())
          .getLastName());
    }
  }
}); 

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 = 
  (IStructuredSelection) viewer.getSelection();
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 from this author.

8. 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.

8.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

8.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.

9. Links and Literature

9.1. Source Code

Source Code of Examples

9.2. JFace resources

http://wiki.eclipse.org/index.php/JFaceSnippets JFace snippets, e.g. small code examples

NatTable - Flexible Table / Data Grid

9.4. 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