| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> |
| <html> |
| <head> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. 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=ISO-8859-1"> |
| <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">JavaElementLabels</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><font color="#4444cc"> ... |
| TreeViewer viewer= new TreeViewer(parent); |
| // Provide members of a compilation unit or class file, but no working copy elements |
| ITreeContentProvider contentProvider= new StandardJavaElementContentProvider(true, false); |
| 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())); |
| ...</font></pre> |
| <p>The example above uses aJava 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><font color="#4444cc"> ... |
| DecoratingLabelProvider decorator= new DecoratingLabelProvider(labelProvider, new ProblemsLabelDecorator()); |
| viewer.setLabelProvider(decorator); |
| ...</font></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><b> </b>nor the <a href="../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b> |
| ProblemsLabelDecorator</b></a><b> </b>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><b> |
| </b>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> |
