intellij-sdk-code-samples/topics/reference_guide/custom_language_support/code_completion.md

Code Completion

Implementing context-aware code completion in custom languages.

Product Help: Code completion

Providing reference and generic code completion.

Two types of code completion can be provided by custom language plugins: reference completion and contributor-based completion.

Reference completion is easier to implement, but supports only the basic completion action.

Contributor-based completion provides more features, supports all completion types (Code | Code Completion | Basic and Type Matching), and can be used, for example, to implement keyword completion.

Reference Completion

To fill the completion list, the IDE calls PsiReference.getVariants() either on the reference at the caret location or on a dummy reference that would be placed at the caret. This method needs to return an array of objects containing either strings, PsiElement instances or instances of the LookupElement class (see Lookup Items below). If a PsiElement instance is returned in the array, the completion list shows the icon for the element.

A common way to implement getVariants() is to use the same function for walking up the tree as in PsiReference.resolve() using a PsiScopeProcessor which collects all declarations passed to its execute() method and returns them as an array for filling the completion list.

Symbol Reference Completion

This API is currently in development and thus in experimental state. See also .

{style="warning"}

To provide completion variants by a PsiSymbolReference implement PsiCompletableReference.

Contributor-Based Completion

Implementing CompletionContributor gives the greatest control over the operation of code completion. Register in and specify language attribute (unless it works on any supported language).

Note that the Javadoc of that class contains a detailed FAQ for implementing code completion.

{style="note"}

The core scenario of using CompletionContributor consists of calling the extend() method and passing in the Element Pattern specifying the context in which this completion variant is applicable. The CompletionProvider then adds the items to show in the completion list.

Keep in mind that the pattern is checked against the leaf PSI element. If you want to match a composite element, use withParent() or withSuperParent() methods.

If completion items do not depend on indexes (e.g., keywords), it can be marked as dumb aware.

Examples:

• CompletionContributor for completing keywords in MANIFEST.MF files.
• Custom Language Support Tutorial: Completion Contributor

Lookup Items

Items shown in the completion list are represented by instances of the LookupElement interface. These instances are typically created through the LookupElementBuilder class.

If there's only one lookup item to be shown, the behavior can be customized via AutoCompletionPolicy.

Lookup Item Attributes

Text

Shown left-aligned.

Text attributes

Text color/grayed text, Bold, Italic, Underlined, Strikeout

Tail text

Shown next to the main item text (not used for prefix matching). Can be grayed text. Example: parameter list of a method

Type text

Shown right-aligned in the lookup list. Can be grayed text. Example: containing class of a method

Icon/Type icon

See .

Insert handler

The InsertHandler is called when the item is selected and performs additional modifications of the inserted text. It can also show the completion popup after insertion. Example: add parentheses for a method call (ParenthesesInsertHandler)

Runtime Presentation

The item presentation can also be performed via (re-usable) LookupElementRenderer.

For expensive calculations (for example, the presentation of an item to be shown depends on other items) use LookupElementBuilder.withExpensiveRenderer() to invoke the renderer in the background while the completion list is already populating.

Sorting

Use PrioritizedLookupElement to control item sorting if all lookup items are guaranteed to be provided by this CompletionContributor.

Code Completion FAQ

Skipping Completion Popup

To skip completion popup in the current context (for example, inside comments), implement CompletionConfidence registered in .

Showing Completion Popup Programmatically

To trigger completion upon typing a specific character in the editor, override TypedHandlerDelegate.checkAutoPopup() registered in .

If all conditions match, invoke AutoPopupController.scheduleAutoPopup() and return Result.STOP.

Completion Popup Events

Use LookupListener to receive notifications about completion popup lifecycle events.