The graphical sub-system of the Eclipse platform is made up of two components: SWT, the Standard Widget Toolkit ;and JFace, an architecture-independent modeling layer. This module describes how JFace extends SWT with viewers, commands, wizards, dialogs, and field assist.

1. JFace
The graphical sub-system of the Eclipse platform is made up of two
components: SWT, the Standard Widget Toolkit ;and JFace, an
architecture-independent modeling layer. This module describes how
JFace extends SWT with viewers, commands, wizards, dialogs, and field
assist.
Redistribution and other use of this material requires written permission from The RCP Company.
L0001 - 2010-11-27

2. Eclipse User Interface Layers
4 Layers: Eclipse RCP
Preferences
Commands
Registry
Workbench
 The Eclipse Workbench
Jobs
ICU
JFace

Overall look-n-feel
SWT
 JFace OSGi/Run-time

Architecture-independent models
 SWT

Platform independent API yet rather close to the metal
 Native widgets

Platform dependent: Windows, Linux, Mac, Unix
The “Eclipse User Interface Guidelines” governs the look-n-feel of the
workbench and JFace
 Consequently (nearly) all Eclipse RCP based applications look the same!
Use the SWT Bible “The Definitive Guide to SWT and JFace” by Robert Harris
and Rob Warner
L0001 - 2010-11-27

3. JFace
A set of classes for handling many common UI programming tasks
 Viewers handle the drudgery of populating, sorting, filtering, and
updating widgets
 Actions and contributions introduce semantics for defining user
actions and specifying where to make them available
 Image and font registries provide common patterns for handling UI
resources
 Dialogs and wizards define a framework for building complex
interactions with the user
 Field assist provides classes that help guide the user in choosing
appropriate content for fields in dialogs, wizards, or forms
Does not hide SWT; rather, it extends SWT
L0001 - 2010-11-27

4. The JFace Viewers
Provides a glue layer between the application model and SWT
Viewers exists for most structured widgets – e.g.
 Combo boxes
 Lists
 Trees
 Tables
Uses common interfaces to control:
 The content of the viewer: IContentProvider and child interfaces
 The text and image of the cells: ILabelProvider and child interfaces
 Decoration of images: ILabelDecorator
 Filtering: ViewerFilter
 Sorting: ViewerComparator
L0001 - 2010-11-27

5. Using JFace Viewers
Common design pattern
 Create viewer in parent Composite

Assign layout to the Control of the viewer
 Add columns

new TableViewerColumn(viewer, ...)

Set text and width of columns
 Set content provider – normally ArrayContentProvider

The interface depends on the type of the viewer
 Install commands and action
 Set input

Must be last
Call viewer.refresh(…) when changes are made to the data
L0001 - 2010-11-27

6. Using JFace Viewers
Also possible to specify background, foreground, font, tooltip…
public void createPartControl(Composite parent) {
TableViewer viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL |
SWT.V_SCROLL);
viewer.setContentProvider(new ArrayContentProvider());
Table table = viewer.getTable();
TableViewerColumn c;
table.setHeaderVisible(true);
c = new TableViewerColumn(viewer, SWT.LEFT);
c.setLabelProvider(new NameLabelProvider());
c.getColumn().setText("Name");
c.getColumn().setWidth(100);
c = new TableViewerColumn(viewer, SWT.LEFT);
c.setLabelProvider(new RestLabelProvider());
c.getColumn().setText("Rest");
c.getColumn().setWidth(300);
viewer.setInput(getSite().getShell().getDisplay().getFontList(null, true));
}
private class NameLabelProvider extends ColumnLabelProvider {
@Override
public String getText(Object element) {
return ((FontData) element).getName();
}
}
L0001 - 2010-11-27

7. IContentProvider
Provides the glue between the content of the application model and the
appropriate viewer
 IStructuredContentProvider – used for combo boxes, lists and tables
 ITreeContentProvider – used for trees
 ILazyContentProvider – used for SWT.VIRTUAL tables
 ILazyTreeContentProvider – used for SWT.VIRTUAL trees
For arrays and List use ArrayContentProvider
public interface IStructuredContentProvider {
public void dispose();
public void inputChanged(Viewer viewer, Object oldInput, Object newInput);
public Object[] getElements(Object inputElement);
}
L0001 - 2010-11-27

8. ILabelProvider
ILabelProvider provides the basic label and image for a row object in a
viewer
 Given the row object, the text, image. colors, font, ... for the cell is
returned
Several interesting implementations
 ColumnLabelProvider - base class for label providers for
TableViewerColumn
 OwnerDrawLabelProvider - base class for label providers that wish to
paint their cells
 CellLabelProvider - don’t use this; use ColumnLabelProvider instead
L0001 - 2010-11-27

9. ILabelDecorator
ILabelDecorator provides a standard means to
decorate an existing label and image
 Used extensively in Eclipse IDE: team and
class information
Label decorators can be registered as
extensions
 Activated automatically based on the class
of the current row object of the viewer
L0001 - 2010-11-27

10. Label Providers for Table and Tree (3.3 and later edition)
For Table and Tree, a label provider can be registered per column
 Use superclass ColumnLabelProvider and not CellLabelProvider
This allows reuse of label providers across projects
L0001 - 2010-11-27

11. Sample Decorator
This decorator will add a bullet to the top-right corner of the image for an
IRes object, if the IActionFilter of the object returns true for the children
property
The extension point currently uses the “old” style expression form
<extension
point="org.eclipse.ui.decorators">
<decorator
adaptable="true"
icon="icons/sample_decorator.gif"
id="com.rcpcompany.demo.providers.ui.decorators.decorator"
label="Resource Decorator"
lightweight="true"
location="TOP_RIGHT"
state="true">
<enablement>
<and>
<objectClass
name="com.rcpcompany.demo.providers.model.IRes"/>
<objectState
name="children"
value="true"/>
</and>
</enablement>
</decorator>
</extension>
L0001 - 2010-11-27

12. Filters and Sorters
Viewers support filtering
 viewer.addFilter(ViewerFilter) – adds a filter to a viewer

Implement filter.select(viewer, parentElement, element)
•element is the object of the current row

Consider using the label providers for the different columns along
with SearchPattern

Multiple filters are logically and’ed
 For trees use FilteredTree
final TableViewer viewer = new TableViewer(top, SWT.SINGLE);
...
viewer.addFilter(new ViewerFilter() {
public boolean select(Viewer viewer, Object parentElement, Object element) {
Contact c = (Contact)element;
return ...;
}
});
L0001 - 2010-11-27

13. Using SearchPattern
Create a new Pattern
 SeachPattern sp = new SearchPattern();
 sp.setPattern(“”)=;
Set the current pattern
 sp.setPattern(“*M”);
Test the pattern
 sp.matches(“Madsen”);
L0001 - 2010-11-27

14. Filters and Sorters
Viewers support sorting
 viewer.setComparator(ViewerComparator) – sets the comparator/sorter
of a viewer
For Table the header can be changed to show the current sort
 setSortColumn(TableColumn) and setSortDirection(int)
L0001 - 2010-11-27

15. Lab Exercise
Create a view with a JFace table
 Add columns for first name and family name
Create both content and label providers (3.3 edition style)
Add a filter for the full name of a contact
 Check out SearchPattern (3.3 and later edition)
L0001 - 2010-11-27

16. Lab Exercise
Extra: When the “arrow down” key is pressed in the filter box, move the
focus to the table
Extra: And back again
Extra: Add column for all cities of a contact and filter on this as well as the
full name
Extra: Add a dialog to select the shown columns
L0001 - 2010-11-27

17. When You Want to…
Paint specific columns of a TableViewer yourself
 Use OwnerDrawLabelProvider
Decorate images
 Use new DecoratingLabelProvider(yourLabelProvider,
PlatformUI.getWorkbench().getDecoratorManager().getLabelDecorator())
Control navigation in a Table or Tree
 Subclass and use TableViewerFocusCellManager and
TreeViewerFocusCellManager
Edit the values in a column
 See the EditingSupport class and subclasses

Remember to use SWT.FULL_SELECTION
L0001 - 2010-11-27

18. When You Want to…
Get the item of a TableViewer at a specific event position
 Use table.getItem(new Point(e.x,e.y))
Hide the selection when nothing can be selected
v.getTable().addMouseListener(new MouseAdapter() {
public void mouseDown(MouseEvent e) {
if( v.getTable().getItem(new Point(e.x,e.y)) == null ) {
v.setSelection(new StructuredSelection());
}
}
});
L0001 - 2010-11-27

19. Management of Image Resources
Two types of image resources in Eclipse
 Image

1-to-1 with the underlying image resource

Must be disposed when not used any more
 ImageDescription

Lightweight descriptor of image
The Plugin class contains an image manager!
 AbstractUIPlugin.imageDescriptorFromPlugin()
 Different method must be used if using multiple monitors (and thus
possibly multiple Displays)
The platform also contains a large set of shared images that can cover
many usages:
 PlatformUI.getWorkbench().getSharedImages().getImage(…)
L0001 - 2010-11-27

20. Managing Resources - JFaceResources
JFace contains a resource manager that handles fonts, images, and colors
You store RGB, FontData and ImageDescriptor objects and you retrieve
Color, Font and Image objects
As you don’t create these resources, you don’t have to dispose them!!!
JFaceResources contains a lot of standard resources:
 All colors and fonts as specified in the current theme
L0001 - 2010-11-27

21. Managing Resources - JFaceResources
To add a color – really RGB value:
RGB rgb = new RGB(100, 100, 100);
JFaceResources.getColorRegistry().put(“BGColor”, rgb);
To retrieve the color:
Color color = JFaceResources.getColorRegistry().get(“BGColor”);
To monitor changes to the resources:
JFaceResources.getColorRegistry().addListener(new IPropertyChangeListener() {
public void propertyChange(PropertyChangeEvent event) {
...
}
});
 Remember to remove the listener as well!
Likewise for fonts and images
L0001 - 2010-11-27

22. Managing Resources - JFaceResources
You can add images from your plug-in in your Activator.start(...) using the
following code
 OK, as the existence of nor checked
ImageDescriptor id = imageDescriptorFromPlugin("com.rcpcompany.cexx", "icons/exit16.gif");
JFaceResources.getImageRegistry().put("exit", id);
L0001 - 2010-11-27

23. More Information
“Eclipse User Interface Guidelines: Version 2.1”
 http://www.eclipse.org/resources/resource.php?id=162

The Look-n-Feel guidelines for Eclipse – heavily influenced by the
corresponding Microsoft Windows Look-n-Feel guidelines
“The Definitive Guide to SWT and JFace” by Robert Harris and Rob Warner
(ISBN: 978-1590593257)
 As it says – “The Definitive Guide…” – and needed due to the poor
Javadoc of SWT
“JFaceSnippets” Repository
 http://wiki.eclipse.org/index.php/JFaceSnippets

Likewise for JFace
L0001 - 2010-11-27

24. More Information
“Eclipse Forms: Rich UI for the Rich Client”
 http://www.eclipse.org/resources/resource.php?id=140
“Rich clients with the SWT and JFace”
 http://www.javaworld.com/javaworld/jw-04-2004/jw-0426-
swtjface.html?page=2
“Understanding Decorators in Eclipse”
 http://www.eclipse.org/resources/resource.php?id=216
“Decorating resources in WebSphere”
 http://www.ibm.com/developerworks/ibm/library/i-wsdeco/

In-dept article on the decorators
L0001 - 2010-11-27

25. More Information
“Building and delivering a table editor with SWT/JFace”
 http://www.eclipse.org/resources/resource.php?id=209

Older – yet correct – article with all the needed information for editors
in tables
“JFace Plug-in Developers Guide”
 http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/
guide/jface.htm
“UI Forms”
 http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.isv/
guide/forms.htm
“Eclipse Forms: Rich UI for the Rich Client”
 http://www.eclipse.org/articles/Article-Forms/article.html

The Forms UI explained with some good examples
L0001 - 2010-11-27