Content assist
Content assist allows you to provide context sensitive content completion upon
user request. This functionality is implemented by the platform text framework
in
org.eclipse.jface.text.contentassist
.
Popup windows (infopops) are used to propose possible text choices to complete
a phrase. The user can select these choices for insertion in the text.
Content assist also supports contextual infopops for providing the user with
information that is related to the current position in the document.
Implementing content assist is
optional. By default,
SourceViewerConfiguration
does not install a content assistant since it does not know the
document model used for a particular editor, and has no generic behavior for
content assist.
In order to implement content assist, your editor's source
viewer configuration must be
configured
to define a content assistant. This is done in the Java editor example
inside the JavaSourceViewerConfiguration.
public IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {
ContentAssistant assistant= new ContentAssistant();
assistant.setContentAssistProcessor(new JavaCompletionProcessor(), IDocument.DEFAULT_CONTENT_TYPE);
assistant.setContentAssistProcessor(new JavaDocCompletionProcessor(), JavaPartitionScanner.JAVA_DOC);
...
return assistant;
}
Content assist behavior is defined in the interface
IContentAssistant.
Setting up a content assistant is somewhat similar to setting up syntax
highlighting. The assistant should be configured with different phrase completion strategies for different
document content types. The completion strategies are implemented
using
IContentAssistProcessor.
A processor proposes completions and computes context information for an offset
within particular content type.
Content assist processors
Not all content types need to have content assistance. In the Java example
editor, content assist processors are provided for the default content type
and javadoc, but not for multi-line comments. Let's look at each of these
processors.
The JavaCompletionProcessor is quite simple. It can only propose
keywords as completion candidates. The keywords are defined in a field,
fgProposals, and these keywords are always proposed as the
candidates:
public ICompletionProposal[] computeCompletionProposals(ITextViewer viewer, int documentOffset) {
ICompletionProposal[] result= new ICompletionProposal[fgProposals.length];
for (int i= 0; i < fgProposals.length; i++) {
IContextInformation info= new ContextInformation(fgProposals[i], MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.Proposal.ContextInfo.pattern"), new Object[] { fgProposals[i] })); //$NON-NLS-1$
result[i]= new CompletionProposal(fgProposals[i], documentOffset, 0, fgProposals[i].length(), null, fgProposals[i], info, MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.Proposal.hoverinfo.pattern"), new Object[] { fgProposals[i]})); //$NON-NLS-1$
}
return result;
}
Completion can be triggered by user request or can be automatically triggered
when the "(" or "." character is typed:
public char[] getCompletionProposalAutoActivationCharacters() {
return new char[] { '.', '(' };
}
In addition to proposing completions, the JavaCompletionProcessor
defines context information that can be requested by the user. Context
information includes a description of the pieces of information available in a
given context and the detailed information message.
In the Java editor example, the information is not really contextual.
An array containing five similar context information objects is computed for the
current offset when the user requests context info. All of these context
information objects define a context that contains the five characters in front
of the offset and the five after the offset. If any one of these five proposals is
selected, the detailed information will appear near the cursor and will stay
as long as the cursor is within the context of the five characters around the offset.
public IContextInformation[] computeContextInformation(ITextViewer viewer, int documentOffset) {
IContextInformation[] result= new IContextInformation[5];
for (int i= 0; i < result.length; i++)
result[i]= new ContextInformation(
MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.ContextInfo.display.pattern"), new Object[] { new Integer(i), new Integer(documentOffset) }),
MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.ContextInfo.value.pattern"), new Object[] { new Integer(i), new Integer(documentOffset - 5), new Integer(documentOffset + 5)}));
return result;
}
This context information is shown automatically when the "#" character
is typed:
public char[] getContextInformationAutoActivationCharacters() {
return new char[] { '#' };
}
Content assist configuration
The appearance and behavior of content assist can be configured using
IContentAssistant.
For example, you can configure the auto activation time out, and the orientation
and color of information popups.
public IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {
ContentAssistant assistant= new ContentAssistant();
...
assistant.enableAutoActivation(true);
assistant.setAutoActivationDelay(500);
assistant.setProposalPopupOrientation(IContentAssistant.PROPOSAL_OVERLAY);
assistant.setContextInformationPopupOrientation(IContentAssistant.CONTEXT_INFO_ABOVE);
assistant.setContextInformationPopupBackground(JavaEditorEnvironment.getJavaColorProvider().getColor(new RGB(150, 150, 0)));
return assistant;
}
Show the content assist action in the menu
If the content assistant is correctly supplied as mentioned above then the key binding (Ctrl+Space per default) will work out of the box.
To make the action appear in the main menu the editor action bar contributor has to be extended:
...
private RetargetTextEditorAction fContentAssist;
public MyEditorActionContributor() {
fContentAssist= new RetargetTextEditorAction();
String commandId= ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS;
fContentAssist.setActionDefinitionId(commandId);
}
public void contributeToMenu(IMenuManager menu) {
IMenuManager editMenu= menu.findMenuUsingPath(M_EDIT);
editMenu.appendToGroup(MB_ADDITIONS, fContentAssist);
}
public void setActiveEditor(IEditorPart part) {
IAction editorAction= getAction(part, ITextEditorActionConstants.CONTENT_ASSIST);
fContentAssist.setAction(editorAction);
}
...
