| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| <head> |
| <meta name="copyright" content= |
| "Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." /> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <meta http-equiv="Content-Style-Type" content="text/css" /> |
| <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" /> |
| <title>Presenting Java elements in a JFace viewer</title> |
| |
| </head> |
| <body> |
| <h2>Presenting Java elements in a JFace viewer</h2> |
| <p>The JDT UI API provides classes that allow you to present the Java model or parts of it in a |
| standard JFace viewer. This functionality is provided primarily by:</p> |
| |
| <ul> |
| <li><a href= |
| "../reference/api/org/eclipse/jdt/ui/StandardJavaElementContentProvider.html"><b>StandardJavaElementContentProvider</b></a> |
| - translates the Java element hierarchy into a data structure accessible by a tree, table or list |
| viewer</li> |
| <li><a href= |
| "../reference/api/org/eclipse/jdt/ui/JavaElementLabelProvider.html"><b>JavaElementLabelProvider</b></a> |
| - provides corresponding images and labels for a standard JFace viewer</li> |
| <li><a href= |
| "../reference/api/org/eclipse/jdt/ui/JavaElementLabels.html"><b>JavaElementLabels</b></a> - |
| provides corresponding text labels for Java elements</li> |
| </ul> |
| <p>Content and label providers for JFace viewers are described in detail in <a href= |
| "../../org.eclipse.platform.doc.isv/guide/jface_viewers.htm" class="XRef">JFace viewers</a>.</p> |
| |
| If you understand the basic platform mechanism, then putting the Java content and label providers |
| together is quite simple: |
| <pre class="color1"> |
| ... |
| TreeViewer viewer= new TreeViewer(parent); |
| // Provide members of a compilation unit or class file |
| ITreeContentProvider contentProvider= new StandardJavaElementContentProvider(true); |
| viewer.setContentProvider(contentProvider); |
| // There are more flags defined in class JavaElementLabelProvider |
| ILabelProvider labelProvider= new JavaElementLabelProvider( |
| JavaElementLabelProvider.SHOW_DEFAULT | |
| JavaElementLabelProvider.SHOW_QUALIFIED | |
| JavaElementLabelProvider.SHOW_ROOT); |
| viewer.setLabelProvider(labelProvider); |
| // Using the Java model as the viewers input present Java projects on the first level. |
| viewer.setInput(JavaCore.create(ResourcesPlugin.getWorkspace().getRoot())); |
| ... |
| </pre> |
| <p>The example above uses a Java model (<a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaModel.html"><b>IJavaModel</b></a>) as the input element |
| for the viewer. The <a href= |
| "../reference/api/org/eclipse/jdt/ui/StandardJavaElementContentProvider.html"><b>StandardJavaElementContentProvider</b></a> |
| also supports <a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html"><b>IJavaProject</b></a>, <a href= |
| "../reference/api/org/eclipse/jdt/core/IPackageFragmentRoot.html"><b>IPackageFragmentRoot</b></a>, |
| |
| <a href="../reference/api/org/eclipse/jdt/core/IPackageFragment.html"><b>IPackageFragment</b></a>, |
| and <b>IFolder</b> as input elements:</p> |
| <h3>Overlaying images with Java information</h3> |
| <p><a href= |
| "../reference/api/org/eclipse/jdt/ui/JavaElementImageDescriptor.html"><b>JavaElementImageDescriptor</b></a> |
| can be used to create an image based on an arbitrary base image descriptor and a set of flags |
| specifying which Java specific adornments (e.g. static, final, synchronized, ....) are to be |
| superimposed on the image.</p> |
| <h3>Adding problem and override decorators</h3> |
| When a viewer is supposed to include problem annotations, the JFace <b>DecoratingLabelProvider</b> |
| |
| together with the <a href= |
| "../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b>ProblemsLabelDecorator</b></a> |
| is used. The snippet below illustrates the use of a problem label decorator. |
| <pre class="color1"> |
| ... |
| DecoratingLabelProvider decorator= new DecoratingLabelProvider(labelProvider, new ProblemsLabelDecorator()); |
| viewer.setLabelProvider(decorator); |
| ... |
| </pre> |
| <p>In the same way the <a href= |
| "../reference/api/org/eclipse/jdt/ui/OverrideIndicatorLabelDecorator.html"><b>OverrideIndicatorLabelDecorator</b></a> |
| can be used to decorate a normal label provider to show the implement and override indicators for |
| methods.</p> |
| <h3>Updating the presentation on model changes</h3> |
| <p>Neither the <a href= |
| "../reference/api/org/eclipse/jdt/ui/OverrideIndicatorLabelDecorator.html"><b>OverrideIndicatorLabelDecorator</b></a> |
| |
| nor the <a href= |
| "../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b>ProblemsLabelDecorator</b></a> |
| listen to model changes. Hence, the viewer doesn't update its presentation if the Java or resource |
| marker model changes. The reason for pushing the update onto the client for these classes is that |
| there isn't yet a generic implementation that fulfills all performance concerns. Handling Java |
| model delta inspection and viewer refreshing in each label decorator or provider would lead to |
| multiple delta inspections and unnecessary viewer updates.</p> |
| <p>So what does the client need to do in order to update their viewers ?</p> |
| <ul> |
| <li><a href= |
| "../reference/api/org/eclipse/jdt/ui/OverrideIndicatorLabelDecorator.html"><b>OverrideIndicatorLabelDecorator</b></a>: |
| the client must listen to Java model changes (see <a href="jdt_api_manip.htm#javadeltas">Responding |
| to changes in Java elements</a>) and decide if the change(s) described by the delta invalidates the |
| override indicator of elements presented in the viewer. If so, the class inspecting the delta |
| should trigger a repaint of the corresponding Java elements using the standard JFace viewer API |
| (see update methods on StructuredViewer).</li> |
| <li><a href= |
| "../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b>ProblemsLabelDecorator</b></a>: |
| the client should listen to changes notified by the decorator via a <a href= |
| "../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.ProblemsLabelChangedEvent.html"><b>ProblemsLabelChangedEvent</b></a> |
| |
| (see also <a href= |
| "../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html#addListener(org.eclipse.jface.viewers.ILabelProviderListener)"> |
| <b>ProblemsLabelDecorator.addListener</b></a> ). Since the marker model is resource based, the |
| listener has to map the resource notifications to its underlying data model. For an example showing |
| how to do this for viewers presenting Java elements see the internal classes |
| <code>ProblemTreeViewer.handleLabelProviderChanged.</code></li> |
| </ul> |
| <p>For the same reasons enumerated for label decorators the <a href= |
| "../reference/api/org/eclipse/jdt/ui/StandardJavaElementContentProvider.html"><b>StandardJavaElementContentProvider</b></a> |
| doesn't listen to model changes. If the viewer needs to update its presentation according to Java |
| model changes, then the client should add a corresponding listener to JavaCore. If the change |
| described by the delta invalidates the structure of the elements presented in the viewer then the |
| client should update the viewer using the standard JFace API (see refresh methods on |
| StructuredViewer, and the add and remove methods on TableViewer and AbstractTreeViewer).</p> |
| <h3>Sorting the viewer</h3> |
| <p><a href= |
| "../reference/api/org/eclipse/jdt/ui/JavaElementSorter.html"><b>JavaElementSorter</b></a> can be |
| plugged into a JFace viewer to sort Java elements according to the Java UI sorting style.</p> |
| |
| </body> |
| </html> |
