| <!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>Performing code assist on Java code</title> |
| <link rel="stylesheet" type="text/css" href="../book.css" /> |
| </head> |
| <body> |
| <h2>Performing code assist on Java code</h2> |
| <p>The JDT API allows other plug-ins to perform code assist or code select on some Java elements. |
| Elements that allow this manipulation should implement <b><a href= |
| "../reference/api/org/eclipse/jdt/core/ICodeAssist.html">ICodeAssist</a></b>.</p> |
| |
| <p>There are two kinds of manipulation:</p> |
| <ul> |
| <li>Code completion - compute the completion of a Java token.</li> |
| <li>Code selection - answer the Java element indicated by the selected text of a given offset and |
| length.</li> |
| </ul> |
| <p>In the Java model there are two elements that implement this interface: <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IClassFile.html">IClassFile</a></b> and <b><a href= |
| "../reference/api/org/eclipse/jdt/core/ICompilationUnit.html">ICompilationUnit</a></b>. Code |
| completion and code selection only answer results for a class file if it has attached source.</p> |
| |
| <h3>Code completion</h3> |
| <h4>Performing a code completion</h4> |
| <p>One way to programmatically perform code completion is to invoke <b><a href= |
| "../reference/api/org/eclipse/jdt/core/ICodeAssist.html#codeComplete(int,%20org.eclipse.jdt.core.CompletionRequestor)"> |
| ICodeAssist.codeComplete</a></b>. You specify the offset in the compilation unit after which the |
| code completion is desired. You must also supply an instance of <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionRequestor.html">CompletionRequestor</a></b> to |
| accept the possible completions.</p> |
| <p>The method in <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionRequestor.html#accept(org.eclipse.jdt.core.CompletionProposal)"> |
| CompletionRequestor.accept(CompletionProposal)</a></b> accepts all kinds of proposals for code |
| completion. The methods of <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html">CompletionProposal</a></b> give |
| information that describes the proposed element (its name, declaring type, etc.), its proposed |
| position for insertion in the compilation unit, and its relevance. </p> |
| |
| <p>A completion requestor can accept many different kinds of completions. This kind is given by |
| <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#getKind()">CompletionProposal.getKind</a></b>.</p> |
| <p>Some of the possible completion kinds are (The complete list of possible completion kinds can be |
| seen on <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html">CompletionProposal</a></b>):</p> |
| <ul> |
| <li>annotation attribute - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#ANNOTATION_ATTRIBUTE_REF">ANNOTATION_ATTRIBUTE_REF</a></b></li> |
| <li>anonymous type - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#ANONYMOUS_CLASS_DECLARATION">ANONYMOUS_CLASS_DECLARATION</a></b></li> |
| <li>type reference - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#TYPE_REF">TYPE_REF</a></b></li> |
| |
| <li>field reference- <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#FIELD_REF">FIELD_REF</a></b></li> |
| <li>keyword - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#KEYWORD">KEYWORD</a></b></li> |
| <li>label reference - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#LABEL_REF">LABEL_REF</a></b></li> |
| <li>local variable reference - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#LOCAL_VARIABLE_REF">LOCAL_VARIABLE_REF</a></b></li> |
| <li>method reference - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#METHOD_REF">METHOD_REF</a></b></li> |
| <li>method declaration - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#METHOD_DECLARATION">METHOD_DECLARATION</a></b></li> |
| |
| <li>package import or reference - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#PACKAGE_REF">PACKAGE_REF</a></b></li> |
| <li>variable name - <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionProposal.html#VARIABLE_DECLARATION">VARIABLE_DECLARATION</a></b></li> |
| </ul> |
| <p>The completion requestor must also be able to accept compilation errors. </p> |
| <h4>Completion relevance</h4> |
| <p>Because there may be many different possible completions, the notion of relevance is used to |
| compare the relevance of a suggested completion to other proposals. Relevance is represented |
| by a positive integer. The value has no implicit meaning except to be used relative to the |
| value for other proposals. The relevance of a code completion candidate can be affected by |
| the expected type of the expression, as it relates to the types in the surrounding code, such as |
| variable types, cast types, return types, etc. The presence of an expected prefix or suffix |
| in a completion also affects its relevance.</p> |
| |
| <h4>Completion context</h4> |
| <p>An instance of <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionRequestor.html">CompletionRequestor</a></b> can |
| also accept a completion context. This context is given by the method <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionRequestor.html#acceptContext(org.eclipse.jdt.core.CompletionContext)"> |
| CompletionRequestor.acceptContext(CompletionContext)</a></b> and does not depend on a specific |
| completion proposal. The methods of <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionContext.html">CompletionContext</a></b> give |
| information that describe the general context like the offset of completion, the completed token, |
| the completed token kind (name or string literal) and its position.<br /></p> |
| <p>A <b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionContext.html">CompletionContext</a></b> can also |
| give some information about elements (<b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaElement.html">IJavaElement</a></b>) which are related |
| to the completion location. These elements are based on the content of the completed compilation |
| unit's buffer and are not the result of the last reconcile operation.<br /></p> |
| |
| <p>Some of these methods are:</p> |
| <ul> |
| <li><b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionContext.html#getEnclosingElement()">getEnclosingElement()</a></b> |
| - This method returns the innermost enclosing element which contains the completion location</li> |
| <li><b><a href= |
| "../reference/api/org/eclipse/jdt/core/CompletionContext.html#getVisibleElements(java.lang.String)"> |
| getVisibleElements(String)</a></b> - This method returns the elements which are visible from the |
| completion location and which can be assigned to the given type</li> |
| </ul> |
| <h4>Code completion options</h4> |
| <p>The JDT Core plug-in defines options that control the behavior of code completion. These |
| options can be changed by other plug-ins. </p> |
| |
| <ul> |
| <li>Activate Visibility Sensitive Completion<br /> |
| When this option is active, code completion will not answer elements that are not visible in the |
| current context. (For example, it will not answer private methods of a super class.)</li> |
| <li>Automatic Qualification of Implicit Members<br /> |
| When this option is active, completion automatically qualifies completion on implicit field |
| references and message expressions.</li> |
| </ul> |
| <p>Additional options allow you to specify prefixes and suffixes for the proposed completion names |
| for fields, static fields, local variables, and method arguments. </p> |
| <p>See <a href="jdt_api_options.htm#codeassist">JDT Core Code Assist Options</a> for more |
| information about the code assist options and their defaults.</p> |
| |
| <h3>Code selection</h3> |
| <h4>Performing a code selection</h4> |
| <p>Code selection is used to find the Java element represented by a range of text (typically the |
| selected text) in a compilation unit. To programmatically perform code selection, you must |
| invoke <b><a href= |
| "../reference/api/org/eclipse/jdt/core/ICodeAssist.html#codeSelect(int,%20int)">ICodeAssist.codeSelect</a></b>. |
| You must supply the starting index location of the selection and its length. The result is an array |
| of Java elements. Most of the time there is only one element in the array, but if the selection is |
| ambiguous then all the possible elements are returned.</p> |
| <p>In the following example, code select is invoked for a compilation unit.</p> |
| <pre class="color1"> |
| // Get the compilation unit |
| ICompilationUnit unit = ...; |
| |
| // Get the offset and length |
| int offset = ...; |
| int length = ...; |
| |
| // perform selection |
| IJavaElement[] elements = unit.codeSelect(offset, length); |
| System.out.println("the selected element is " + element[0].getElementName()); |
| </pre> |
| <h4>Selection at cursor location</h4> |
| |
| <p>When the selection length is specified as 0, a selection will be computed by finding the |
| complete token that encloses the specified offset. Consider the following example method:</p> |
| <p><code> public void fooMethod(Object) {<br /> |
| }<br /></code></p> |
| If you specify an offset after the first character of <i>fooMethod</i>, and you specify a length of |
| 0, then the selection will be computed to include the entire token <i>fooMethod</i>. If |
| instead, you specify a length of 5, the selection will considered as <i>ooMet</i>. |
| |
| </body> |
| </html> |
