L0033 - JFace


Published on

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 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • \n
  • The look-n-feel of the native widgets and SWT is governed by the native look-n-feel guide. Eclipse adds some further rules on top of these in the form of “Eclipse User Interface Guidelines”.\nThe look-n-feel of an RCP application can be changed; this is described in the module “L0019 - Changing the Look-n-Feel”.\n
  • Where does JFace end and the workbench begin? Sometimes the lines aren't so obvious. In general, the JFace APIs (from the packages org.eclipse.jface.*) are independent of the workbench extension points and APIs. Conceivably, a JFace program could be written without using any workbench code at all.\nThe workbench makes use of JFace but attempts to reduce dependencies where possible. For example, the workbench part model (IWorkbenchPart) is designed to be independent of JFace. Views and editors can be implemented using SWT widgets directly without using any JFace classes. The workbench attempts to remain "JFace neutral" wherever possible, allowing programmers to use the parts of JFace they find useful. In practice, the workbench uses JFace for much of its implementation and there are references to JFace types in API definitions. (For example, the JFace interfaces for IMenuManager, IToolBarManager, and IStatusLineManager show up as types in the workbench IActionBar methods.)\nWhen using JFace API, it's a good idea to keep in mind the rules of engagement for using background threads.\nThe lines between SWT and JFace are much cleaner. SWT does not depend on any JFace or platform code at all. Many of the SWT examples show how you can build a standalone application. \nJFace is designed to provide common application UI function on top of the SWT library. JFace does not try to "hide" SWT or replace its function. It provides classes and interfaces that handle many of the common tasks associated with programming a dynamic UI using SWT.\nThe relationship between JFace and SWT is most clearly demonstrated by looking at viewers and their relationship to SWT widgets.\nDialogs and wizards are described in the module “L0007 - More Interaction with the Workbench”.\n
  • JFace viewers exist in most cases where data must be mapped to a structured widget.\nSee “JFace Plug-in Developers Guide” for more information.\nThe use of two types of providers is a major difference from the corresponding models in Swing.\n
  • If any changes are made to the structure of a viewer, then refresh(..) must be called.\nIf setInput(…) is not the last method called, all sorts of peculiar things can happen – most often some columns will only be present in the header and not in the table data. \n
  • Use ColumnLabelProvider, not CellLabelProvider.\n
  • The methods of the IStructuredContentProvider are:\ndispose() – called when the viewer is disposed\ninputChanged(Viewer viewer, Object oldInput, Object newInput) - notifies this content provider that the given viewer's input has been switched to a different element\ngetElements(Object inputElement) - returns the elements to display in the viewer when its input is set to the given element\n
  • There are two means for providing labels and images in the Eclipse platform. The base label and image are provided via an ILabelProvider. These can then be augmented or decorated via ILabelDecorators.\nIn Eclipse IDE, the current set of decorators can be found on the “Label Decoration” page of the preferences.\nDecorators are registered via the extension point org.eclipse.ui.decorators – see later slide for example.\n
  • There are two means for providing labels and images in the Eclipse platform. The base label and image are provided via an ILabelProvider. These can then be augmented or decorated via ILabelDecorators.\nIn Eclipse IDE, the current set of decorators can be found on the “Label Decoration” page of the preferences.\nDecorators are registered via the extension point org.eclipse.ui.decorators – see later slide for example.\n
  • The primary advantage of the column label providers is the ability to use the same label providers across a complete project. The means the same look will be used for the same field throughout the application – something most users appreciate \nThe feel of viewers is to a large degree handled via the commands that are installed in the viewer and the content menu.\n
  • \n
  • \n
  • \n
  • \n
  • Now it’s time for the lab.\nThe data for the table will be provided by the trainer. It consists of a plug-in with a ContactManager that provides a number of contacts each with name, address, zip, city and country attributes.\n
  • Now it’s time for the lab.\nThe data for the table will be provided by the trainer. It consists of a plug-in with a ContactManager that provides a number of contacts each with name, address, zip, city and country attributes.\n
  • \n
  • \n
  • A main cause of resource problems in many Eclipse RCP applications is faulty management of images! Either they are never released (or disposed) properly or they are shared between parts of the application and released too early.\nThe important issue is to handle images (and fonts) consistently. Eclipse includes multiple resource managers:\norg.eclipse.ui.plugin.AbstractUIPlugin.imageDescriptorFromPlugin()\norg.eclipse.jface.resource.ResourceManager\nOne special issue is that images and fonts are associated with a specific Display. So, if multiple monitors are used in the application, the images must be handled on a per Display basis.\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • L0033 - JFace

    1. 1. JFaceThe graphical sub-system of the Eclipse platform is made up of twocomponents: SWT, the Standard Widget Toolkit ;and JFace, anarchitecture-independent modeling layer. This module describes howJFace extends SWT with viewers, commands, wizards, dialogs, and fieldassist.Redistribution and other use of this material requires written permission from The RCP Company.L0001 - 2010-11-27
    2. 2. Eclipse User Interface Layers4 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, UnixThe “Eclipse User Interface Guidelines” governs the look-n-feel of theworkbench 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 Harrisand Rob Warner L0001 - 2010-11-27
    3. 3. JFaceA 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 formsDoes not hide SWT; rather, it extends SWT L0001 - 2010-11-27
    4. 4. The JFace ViewersProvides a glue layer between the application model and SWTViewers exists for most structured widgets – e.g.  Combo boxes  Lists  Trees  TablesUses 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. 5. Using JFace ViewersCommon 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 lastCall viewer.refresh(…) when changes are made to the data L0001 - 2010-11-27
    6. 6. Using JFace ViewersAlso 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. 7. IContentProviderProvides the glue between the content of the application model and theappropriate viewer  IStructuredContentProvider – used for combo boxes, lists and tables  ITreeContentProvider – used for trees  ILazyContentProvider – used for SWT.VIRTUAL tables  ILazyTreeContentProvider – used for SWT.VIRTUAL treesFor 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. 8. ILabelProviderILabelProvider provides the basic label and image for a row object in aviewer  Given the row object, the text, image. colors, font, ... for the cell is returnedSeveral 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. 9. ILabelDecoratorILabelDecorator provides a standard means todecorate an existing label and image  Used extensively in Eclipse IDE: team and class informationLabel decorators can be registered asextensions  Activated automatically based on the class of the current row object of the viewer L0001 - 2010-11-27
    10. 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 CellLabelProviderThis allows reuse of label providers across projects L0001 - 2010-11-27
    11. 11. Sample DecoratorThis decorator will add a bullet to the top-right corner of the image for anIRes object, if the IActionFilter of the object returns true for the childrenpropertyThe 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. 12. Filters and SortersViewers 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. 13. Using SearchPatternCreate 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. 14. Filters and SortersViewers support sorting  viewer.setComparator(ViewerComparator) – sets the comparator/sorter of a viewerFor Table the header can be changed to show the current sort  setSortColumn(TableColumn) and setSortDirection(int) L0001 - 2010-11-27
    15. 15. Lab ExerciseCreate a view with a JFace table  Add columns for first name and family nameCreate 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. 16. Lab ExerciseExtra: When the “arrow down” key is pressed in the filter box, move thefocus to the tableExtra: And back againExtra: Add column for all cities of a contact and filter on this as well as thefull nameExtra: Add a dialog to select the shown columns L0001 - 2010-11-27
    17. 17. When You Want to…Paint specific columns of a TableViewer yourself  Use OwnerDrawLabelProviderDecorate images  Use new DecoratingLabelProvider(yourLabelProvider, PlatformUI.getWorkbench().getDecoratorManager().getLabelDecorator())Control navigation in a Table or Tree  Subclass and use TableViewerFocusCellManager and TreeViewerFocusCellManagerEdit the values in a column  See the EditingSupport class and subclasses  Remember to use SWT.FULL_SELECTION L0001 - 2010-11-27
    18. 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. 19. Management of Image ResourcesTwo 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 imageThe 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 covermany usages:  PlatformUI.getWorkbench().getSharedImages().getImage(…) L0001 - 2010-11-27
    20. 20. Managing Resources - JFaceResourcesJFace contains a resource manager that handles fonts, images, and colorsYou store RGB, FontData and ImageDescriptor objects and you retrieveColor, Font and Image objectsAs 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. 21. Managing Resources - JFaceResourcesTo 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. 22. Managing Resources - JFaceResourcesYou can add images from your plug-in in your Activator.start(...) using thefollowing 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. 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. 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. 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