8. Line Marker Provider
Edit pageLast modified: 14 May 2024Code: SimpleLineMarkerProvider
tip
This page is part of multi-step Custom Language Support Tutorial. All previous steps must be executed in sequence for the code to work.
Line markers help annotate code with icons on the gutter. These markers can provide navigation targets to related code.
Define a Line Marker Provider
A line marker provider annotates usages of Simple Language properties within Java code and provides navigation to the definition of these properties. The visual marker is a Simple Language icon in the gutter of the Editor window.
The SimpleLineMarkerProvider
subclasses RelatedItemLineMarkerProvider
. For this example, override the collectNavigationMarkers()
method to collect usage of a Simple Language key and separators:
final class SimpleLineMarkerProvider extends RelatedItemLineMarkerProvider {
@Override
protected void collectNavigationMarkers(@NotNull PsiElement element,
@NotNull Collection<? super RelatedItemLineMarkerInfo<?>> result) {
// This must be an element with a literal expression as a parent
if (!(element instanceof PsiJavaTokenImpl) || !(element.getParent() instanceof PsiLiteralExpression literalExpression)) {
return;
}
// The literal expression must start with the Simple language literal expression
String value = literalExpression.getValue() instanceof String ? (String) literalExpression.getValue() : null;
if ((value == null) ||
!value.startsWith(SimpleAnnotator.SIMPLE_PREFIX_STR + SimpleAnnotator.SIMPLE_SEPARATOR_STR)) {
return;
}
// Get the Simple language property usage
Project project = element.getProject();
String possibleProperties = value.substring(
SimpleAnnotator.SIMPLE_PREFIX_STR.length() + SimpleAnnotator.SIMPLE_SEPARATOR_STR.length()
);
final List<SimpleProperty> properties = SimpleUtil.findProperties(project, possibleProperties);
if (!properties.isEmpty()) {
// Add the property to a collection of line marker info
NavigationGutterIconBuilder<PsiElement> builder =
NavigationGutterIconBuilder.create(SimpleIcons.FILE)
.setTargets(properties)
.setTooltipText("Navigate to Simple language property");
result.add(builder.createLineMarkerInfo(element));
}
}
}
Extending from GutterIconDescriptor
allows configuring gutter icons to be shown via Settings | Editor | General | Gutter Icons.
Best Practices for Implementing Line Marker Providers
This section addresses important details about implementing a marker provider.
The collectNavigationMarkers()
method should:
Only return line marker information consistent with the element passed into the method. For example, do not return a class marker if
getLineMarkerInfo()
was called with an element that corresponds to a method.Return line marker information for the appropriate element at the correct scope of the PSI tree. Return leaf elements only - i.e., the smallest possible elements. For example, do not return method marker for
PsiMethod
. Instead, return it for thePsiIdentifier
which contains the name of the method.

What happens when a LineMarkerProvider
returns marker information for a PsiElement
that is a higher node in the PSI tree? For example, if MyWrongLineMarkerProvider()
erroneously returns a PsiMethod
instead of a PsiIdentifier
element:
final class MyWrongLineMarkerProvider implements LineMarkerProvider {
public LineMarkerInfo getLineMarkerInfo(@NotNull PsiElement element) {
if (element instanceof PsiMethod) {
return new LineMarkerInfo(element, ...);
}
return null;
}
}
The consequences of the MyWrongLineMarkerProvider()
implementation have to do with how the IntelliJ Platform performs inspections. For performance reasons, inspection, and specifically the LineMarkersPass
queries all LineMarkerProviders
in two phases:
The first pass is for all elements visible in the Editor window,
The second pass is for the rest of the elements in the file.
If providers return nothing for either area, the line markers get cleared. However, if a method like actionPerformed()
is not completely visible in the Editor window (as shown in the image above,) and MyWrongLineMarkerProvider()
returns marker info for the PsiMethod
instead of PsiIdentifier
, then:
The first pass removes line marker info because whole
PsiMethod
isn't visible.The second pass tries to add a line marker because
MyWrongLineMarkerProvider()
is called for thePsiMethod
.
As a result, the line marker icon would blink annoyingly. To fix this problem for this case, rewrite MyWrongLineMarkerProvider
to return info for PsiIdentifier
instead of PsiMethod
as shown below:
final class MyCorrectLineMarkerProvider implements LineMarkerProvider {
public LineMarkerInfo getLineMarkerInfo(@NotNull PsiElement element) {
if (element instanceof PsiIdentifier &&
element.getParent() instanceof PsiMethod) {
return new LineMarkerInfo(element, ...);
}
return null;
}
}
Register the Line Marker Provider
The SimpleLineMarkerProvider
implementation is registered with the IntelliJ Platform in the plugin configuration file using the com.intellij.codeInsight.lineMarkerProvider
extension point.
<extensions defaultExtensionNs="com.intellij">
<codeInsight.lineMarkerProvider
language="JAVA"
implementationClass="org.intellij.sdk.language.SimpleLineMarkerProvider"/>
</extensions>
Run the Project
Run the plugin by using the Gradle runIde
task.
Open the Java Test file. Now the icon appears next to line 3 on the gutter. A user can click on the icon to navigate to the property definition.

Thanks for your feedback!