L0033 - JFace

L0001 - 2010-11-27

Redistribution and other use of this material requires written permission from The RCP Company.

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.

L0001 - 2010-11-27

Eclipse User Interface Layers

4 Layers:

The Eclipse Workbench

Overall look-n-feel

JFace

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

Eclipse RCP

OSGi/Run-time

SWT

JFace

Workbench

Preferences

Jobs

Registry

ICU

Commands

L0001 - 2010-11-27

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


To add a color – really RGB value:

To retrieve the color:

To monitor changes to the resources:

Remember to remove the listener as well!

Likewise for fonts and images

RGB rgb = new RGB(100, 100, 100);JFaceResources.getColorRegistry().put(“BGColor”, rgb);

Color color = JFaceResources.getColorRegistry().get(“BGColor”);

JFaceResources.getColorRegistry().addListener(new IPropertyChangeListener() { public void propertyChange(PropertyChangeEvent event) { ... }});

L0001 - 2010-11-27


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

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

More Information

“Eclipse Forms: Rich UI for the Rich Client”


“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”


“Decorating resources in WebSphere”

http://www.ibm.com/developerworks/ibm/library/i-wsdeco/

In-dept article on the decorators











L0001 - 2010-11-27

More Information

“Building and delivering a table editor with SWT/JFace”


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













Education

L0033 - JFace