bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_codeassist.htm - gerrit/platform/eclipse.platform.common - Git at Google

 <!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>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:
 <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>
 <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>.&nbsp;
 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>
 The only way to programmatically perform code completion is to invoke <b><a href="../reference/api/org/eclipse/jdt/core/ICodeAssist.html#codeComplete(int, org.eclipse.jdt.core.ICompletionRequestor)">ICodeAssist.codeComplete</a></b>.
 You specify the offset in the compilation unit after which the code completion
 is desired.&nbsp; You must also supply an instance of <b><a href="../reference/api/org/eclipse/jdt/core/ICompletionRequestor.html"> ICompletionRequestor</a></b> to accept the possible completions.</P>

 <P>Each method in <b><a href="../reference/api/org/eclipse/jdt/core/ICompletionRequestor.html"> ICompletionRequestor</a>
 </b>accepts a different kind of proposal for code completion.&nbsp; The
 parameters of each method include text that describes the proposed element (its
 name, declaring type, etc.), its proposed position for insertion in the
 compilation unit, and its relevance.&nbsp;&nbsp;</P>

 <P>A completion requester can accept many different types
 of completions including the insertion of the following elements:</P>

 <ul>
   <li>anonymous types</li>
   <li>classes</li>
   <li>fields</li>
   <li>interfaces</li>
   <li>keywords</li>
   <li>labels</li>
   <li>local variables</li>
   <li>method call</li>
   <li>method declaration</li>
   <li>modifier</li>
   <li>package import or reference</li>
   <li>type</li>
   <li>variable name</li>
 </ul>
 <p>The completion requester must also be able to accept compilation
 errors.&nbsp;&nbsp;</p>
 <p>If your plug-in is not interested in every kind of code completion, a <b><a href="../reference/api/org/eclipse/jdt/core/CompletionRequestorAdapter.html">CompletionRequestorAdapter</a></b>
 can be used so that you need only implement the kinds of completions you are
 interested in.&nbsp; The following example shows an adapter that is only used to
 accept class completions.</p>
 <font color='#4444CC'><pre>
    // Get the compilation unit
    ICompilationUnit unit = ...;

    // Get the offset
    int offset = ...;

    // Create the requester
    ICompletionRequestor requestor = new CompletionRequestorAdapter() {
       public void acceptClass(
          char[] packageName,
          char[] className,
          char[] completionName,
          int modifiers,
          int completionStart,
          int completionEnd,
          int relevance) {
          System.out.println(&quot;propose a class named &quot; + new String(className));
       }
    };

    // Compute proposals
    unit.codeComplete(offset, requestor);</font>
 </pre><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.&nbsp; Relevance is represented by a positive integer.&nbsp; The value
 has no implicit meaning except to be used relative to the value for other
 proposals.&nbsp; 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.&nbsp;
 The presence of an expected prefix or suffix in a completion also affects its
 relevance.
 </p>

 <H4>
 Code completion options
 </h4>

 <P>
 The JDT Core plug-in defines options that control the behavior of code
 completion.&nbsp; These options can be changed by other plug-ins.&nbsp;&nbsp;</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.&nbsp; (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.&nbsp;&nbsp;</p>

 <p> See&nbsp;<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.&nbsp; To programmatically perform code selection,
 you must invoke <b><a href="../reference/api/org/eclipse/jdt/core/ICodeAssist.html#codeSelect(int, int)">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.

 <font color='#4444CC'><pre>   // 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(&quot;the selected element is &quot; + element[0].getElementName());
 </pre></font></p>

 <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.&nbsp; Consider
 the following example method:</P>

 <P>

 <code>&nbsp;&nbsp; public void fooMethod(Object) {<br>
 &nbsp;&nbsp; }<br>
 </P>

 </code>
 If you specify an offset after the first character of <i>fooMethod</i>, and you
 specify a length of 0,&nbsp; 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>
	<!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>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:
	<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>
	<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>
	The only way to programmatically perform code completion is to invoke <b><a href="../reference/api/org/eclipse/jdt/core/ICodeAssist.html#codeComplete(int, org.eclipse.jdt.core.ICompletionRequestor)">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/ICompletionRequestor.html"> ICompletionRequestor</a></b> to accept the possible completions.</P>

	<P>Each method in <b><a href="../reference/api/org/eclipse/jdt/core/ICompletionRequestor.html"> ICompletionRequestor</a>
	</b>accepts a different kind of proposal for code completion.  The
	parameters of each method include text 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 requester can accept many different types
	of completions including the insertion of the following elements:</P>

	<ul>
	<li>anonymous types</li>
	<li>classes</li>
	<li>fields</li>
	<li>interfaces</li>
	<li>keywords</li>
	<li>labels</li>
	<li>local variables</li>
	<li>method call</li>
	<li>method declaration</li>
	<li>modifier</li>
	<li>package import or reference</li>
	<li>type</li>
	<li>variable name</li>
	</ul>
	<p>The completion requester must also be able to accept compilation
	errors.  </p>
	<p>If your plug-in is not interested in every kind of code completion, a <b><a href="../reference/api/org/eclipse/jdt/core/CompletionRequestorAdapter.html">CompletionRequestorAdapter</a></b>
	can be used so that you need only implement the kinds of completions you are
	interested in.  The following example shows an adapter that is only used to
	accept class completions.</p>
	<font color='#4444CC'><pre>
	// Get the compilation unit
	ICompilationUnit unit = ...;

	// Get the offset
	int offset = ...;

	// Create the requester
	ICompletionRequestor requestor = new CompletionRequestorAdapter() {
	public void acceptClass(
	char[] packageName,
	char[] className,
	char[] completionName,
	int modifiers,
	int completionStart,
	int completionEnd,
	int relevance) {
	System.out.println("propose a class named " + new String(className));
	}
	};

	// Compute proposals
	unit.codeComplete(offset, requestor);</font>
	</pre><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>
	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, int)">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.

	<font color='#4444CC'><pre> // 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></font></p>

	<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>
	</P>

	</code>
	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>