l0033 - jface
TRANSCRIPT
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
Managing Resources - JFaceResources
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
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
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”
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
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