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 Preferences and Preference pages, Wizards and Dialogs. It also contains functionality to support icon decorations and 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.

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 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 re-used 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 from it
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());
URL url = FileLocator.find(bundle, 
  new Path("icons/alt_window_32.gif"), null);
ImageDescriptor image = ImageDescriptor.createFromURL(url); 

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

The ControlDecorations class allows you to place image decorations on SWT controls to show additional information about the control. These decorations can also set 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 shows how to create ControlDecorations 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 also hide and show the decoration.

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

The org.eclipse.jface.fieldassist package provides assistance to define 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 FieldAssists. It also uses the ControlDecoration class.

Text text = new Text(parent, SWT.BORDER);

// 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("Use CNTL + SPACE to see possible values");
deco.setImage(image);

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

// Also if the text UI componet is not empty hide the decoration
text.addModifyListener(new ModifyListener() {
  @Override
  public void modifyText(ModifyEvent e) {
    Text text = (Text) e.getSource();
    if (text.getText().length() > 0) {
      deco.hide();
    } else {
      deco.show();
    }
  }
});

// Help the user with the possible inputs
// "." and "#" will also 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.

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

package de.vogella.rcp.intro.first;

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

  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;
  }

} 

Given this data model, here is an example snippet which shows how you could use a ComboViewer in a part.

// This happens in the method which creates the user interface
// parent is the composite which is available

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

// ArrayContentProvider does not store 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 set the input to the Viewer. 
// This input will be send to the
// content provider

viewer.setInput(persons); 

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

// React to the selection of the viewer
// Note that the viewer return the real object and not just a string
// representation

viewer.addSelectionChangedListener(new ISelectionChangedListener() {
  @Override
  public void selectionChanged(SelectionChangedEvent event) {
    IStructuredSelection selection = (IStructuredSelection) event
      .getSelection();
    System.out.println(((Person) selection.getFirstElement())
      .getLastName());
  }
}); 

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

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

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

Please help me to support this article:

Before posting questions, please see the vogella FAQ. If you have questions or find an error in this article please use the www.vogella.com Google Group. I have created a short list how to create good questions which might also help you.