|
|
| (One intermediate revision by one other user not shown) |
| Line 1: |
Line 1: |
| − | '''Contents superseded by ISV'''
| |
| | | | |
| − |
| |
| − |
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | <source lang="xml">
| |
| − | <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>
| |
| − | </source>
| |
| − |
| |
| − | 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:
| |
| − |
| |
| − | <source lang="java">
| |
| − | @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;
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | <source lang="java">
| |
| − | @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());
| |
| − | }
| |
| − | };
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − | 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 ==
| |
| − |
| |
| − | {| border="1" cellpadding="6" cellspacing="0"
| |
| − | ! style="background: #ffdead;" | Selection
| |
| − | ! style="background: #ffdead;" | JavaElement
| |
| − | ! style="background: #ffdead;" | AstNode / Parent
| |
| − | ! style="background: #ffdead;" | Location
| |
| − | |-
| |
| − | ! style="background: #efefef;" colspan="4" | 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
| |
| − | |-
| |
| − | ! style="background: #efefef;" colspan="4" | Package Explorer / JavaElement
| |
| − | |-
| |
| − | | colspan="4" | JavaProject, PackageFragmentRoot, PackageFragment, CompilationUnit, SourceType, SourceField, SourceMethod
| |
| − | |-
| |
| − | ! style="background: #efefef;" colspan="4" | Outline / JavaElement
| |
| − | |-
| |
| − | | colspan="4" | PackageDeclaration, ImportContainer, ImportDeclaration, SourceType, SourceField, SourceMethod
| |
| − | |}
| |
| − |
| |
| − |
| |
| − | == IJavaElementSelection ==
| |
| − |
| |
| − | <source lang="java">
| |
| − | /**
| |
| − | * 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();
| |
| − |
| |
| − | }
| |
| − | </source>
| |
| − | [Category:Recommenders|Z]]
| |
