Recommenders/Attic/ExtDoc

ExtDoc is a framework for providing small JavaDoc-like pieces of information for elements selected in the Java editor. The following contains guidelines for implementing your own content provider, general information on ExtDoc is available at Recommenders/New_and_Noteworthy/0.3.

How-to: Create your own Provider

Before you can start, you have to add ExtDoc to your Eclipse runtime environment and org.eclipse.recommenders.rcp.extdoc to your plugin's required bundles.

The first step in implementing an own provider is to register it in your project's plugin.xml with the ExtDoc extension point. The higher the priority, the earlier your provider appears (Javadoc has 100, you probably don't want to get higher :-), however this is only the default settings, users can modify the order manually.

<extension
         point="org.eclipse.recommenders.rcp.extdoc.provider">
      <provider
            class="full.path.to.my.ProviderClass"
            long_name="Full Name of my Provider"
            priority="0"
            short_name="Fancy Provider"
            icon="icons/myProviderIcon16x16.gif">
      </provider>
   </extension>

You are only required to let your class implement org.eclipse.recommenders.rcp.extdoc.IProvider, however there are abstract classes that already take lots of work from your shoulders, for example creating a nice header including your provider name and icon.

Therefore we will have a look at org.eclipse.recommenders.rcp.extdoc.AbstractTitledProvider, which is the standard way to go and only requires you to implement two methods.

The first method acts as a kind of factory method for creating the top-level SWT composite. The reason for this is that provider content is displayed in several places, so ExtDoc has to manage multiple instances of your composite. As you might, for example, only want to change parts of your composite, a composite is only created once for each place and will be handed to you at each update.

Our basic provider will just have simple label:

@Override
protected Composite createContentComposite(Composite parent) {
    Composite myComposite = new Composite(parent, SWT.NONE);
    Label label = new Label(myComposite, SWT.NONE);
    label.setText("I'm the default text, please select something in your editor :-)");
    return myComposite;
}

The fun begins as soon as some Java element is selected, now we want to present our information. To do so, the second method is called by the framework, handing us an object containing information about the selection. The declaration of the interface is given at the bottom of this page. ExtDoc also delivers information on the position of the element inside the code as, for example, you might want to present different content for a type name as a field declaration than for a method return type. The different locations can be seen in the table below.

Our "hello world" provider doesn't care about the location, since his message is very simple.

@Override
protected ProviderUiJob updateSelection(final IJavaElementSelection selection) {
   // Do some computation here ...
   return new ProviderUiJob() {
        @Override
        public void run(final Composite composite) {
            ((Label) composite.getChildren()[0]).setText("Hello " + selection.getJavaElement().getElementName());
        }
    };
}

Looks a bit strange, doesn't it!? ExtDoc tries to occupy as little time of the main threads as possible, so each provider is updated in his own thread. However, updating SWT components is only allow from the UI thread, which is why the action is splitted here. First, you can do all your complex business, e.g. accessing a database or doing costly computations. Second, you return a runnable object in which a given composite (one of those you've created above) is updated. Since we only have one child - the label - we'll just select it and update the text, ExtDoc cares for the rest, e.g. layouting. Note: you could also return null in case you don't have content for this particular Java element, your provider will be hidden until the next user selection.

Well, that's it already! Pretty short tutorial, right!? Basically, that's all you need to have your information displayed in the view, pop-ups and code assistant! Of course, ExtDoc also provides you much more aid for creating complex providers, like SWT factories or abstract server implementations - just have a look around the ExtDoc bundles :-)

Selection Information

Selection	JavaElement	AstNode / Parent	Location
CompilationUnitEditor
package tes↓t;	PackageFragment	SimpleName / QualifiedName	PACKAGE_DECLARATION
import org.eclipse.swt.widgets.But↓ton;	ResolvedBinaryType	SimpleName / QualifiedName	IMPORT_DECLARATION
import org.eclipse.swt.widg↓ets.Button;	JarPackageFragment	SimpleName / QualifiedName	IMPORT_DECLARATION
public class Tes↓t extends Button implements ISelectionListener	SourceType	SimpleName / TypeDeclaration	TYPE_DECLARATION
public class Test extends Butto↓n implements ISelectionListener	ResolvedBinaryType	SimpleName / SimpleType	TYPE_DECLARATION_EXTENDS
public class Test extends Button implements ISelectionListen↓er	ResolvedBinaryType	SimpleName / SimpleType	TYPE_DECLARATION_IMPLEMENTS
private Button butto↓n;	ResolvedBinaryType	SimpleName / VariableDeclarationFragment	FIELD_DECLARATION
private Butto↓n button;	ResolvedBinaryType	SimpleName / SimpleType	FIELD_DECLARATION
public Button test(Composite arg0, int arg↓1)	LocalVariable	SingleName / SingleVariableDeclaration	METHOD_DECLARATION_PARAMETER
public Button test(Composit↓e arg0, int arg1)	ResolvedBinaryType	SimpleName / SimpleType	METHOD_DECLARATION_PARAMETER
public Button tes↓t(Composite arg0, int arg1)	SourceMethod	SimpleName / MethodDeclaration	METHOD_DECLARATION
public Butto↓n test(Composite arg0, int arg1)	ResolvedBinaryType	SimpleName / SimpleType	METHOD_DECLARATION
Button butto↓n = new Button(null, 0);	LocalVariable	SimpleName / VariableDeclarationFragment	BLOCK
button.setEnabl↓e()	ResolvedBinaryMethod	SimpleName / MethodInvocation	BLOCK
butto↓n.setEnable()	LocalVariable	SimpleName / MethodInvocation	BLOCK
this.butto↓n.setEnable()	ResolvedSourceField	SimpleName / FieldAccess	BLOCK
return butto↓n;	LocalVariable	SimpleName / ReturnStatement	BLOCK
Package Explorer / JavaElement
JavaProject, PackageFragmentRoot, PackageFragment, CompilationUnit, SourceType, SourceField, SourceMethod
Outline / JavaElement
PackageDeclaration, ImportContainer, ImportDeclaration, SourceType, SourceField, SourceMethod

IJavaElementSelection

/**
 * Contains all required information about the user's selection of a java
 * element in the perspective (e.g. Editor, Package Explorer, Outline, ...).
 */
public interface IJavaElementSelection {
 
    /**
     * @return The selected java element.
     */
    IJavaElement getJavaElement();
 
    /**
     * @return The location type inside the compilation unit (e.g.
     *         "method declaration" or "block") if the selection occurs in the
     *         editor.
     */
    ElementLocation getElementLocation();
 
    /**
     * @return The invocation as if the selection in the editor was followed by
     *         a content assist invocation.
     */
    JavaContentAssistInvocationContext getInvocationContext();
 
    /**
     * @return The selected java element's AST node.
     */
    ASTNode getAstNode();
 
}