Syntax Highlighting and Error Highlighting

The class used to specify how a particular range of text should be highlighted is called TextAttributesKey. An instance of this class is created for every distinct type of item which should be highlighted (keyword, number, string and so on). The TextAttributesKey defines the default attributes which are applied to items of the corresponding type (for example, keywords are bold, numbers are blue, strings are bold and green). The mapping of the TextAttributesKey to specific attributes used in an editor is defined by the EditorColorsScheme class, and can be configured by the user if the plugin provides an appropriate configuration interface. Highlighting from multiple TextAttributesKey items can be layered - for example, one key may define an item’s boldness and another its color.

Note: New functionality about Language Defaults and support for additional color schemes as detailed in Color Scheme Management.

The syntax and error highlighting is performed on multiple levels: Lexer, Parser and (External) Annotator.

Lexer

The first level of syntax highlighting is based on the lexer output, and is provided through the SyntaxHighlighter interface. The syntax highlighter returns the TextAttributesKey instances for each token type which needs special highlighting. For highlighting lexer errors, the standard TextAttributesKey for bad characters HighlighterColors.BAD_CHARACTER can be used.

Examples:

• SyntaxHighlighter implementation for Properties language plugin
• Custom Language Support Tutorial: Syntax Highlighter

Parser

The second level of error highlighting happens during parsing. If a particular sequence of tokens is invalid according to the grammar of the language, the PsiBuilder.error() method can be used to highlight the invalid tokens and display an error message showing why they are not valid.

Annotator

The third level of highlighting is performed through the Annotator interface. A plugin can register one or more annotators in the com.intellij.annotator extension point, and these annotators are called during the background highlighting pass to process the elements in the PSI tree of the custom language. Annotators can analyze not only the syntax, but also the semantics using PSI, and thus can provide much more complex syntax and error highlighting logic. The annotator can also provide quick fixes to problems it detects.

When the file is changed, the annotator is called incrementally to process only changed elements in the PSI tree.

To highlight a region of text as a warning or error, the annotator calls createErrorAnnotation() or createWarningAnnotation() on the AnnotationHolder object passed to it, and optionally calls registerFix() on the returned Annotation object to add a quick fix for the error or warning. To apply additional syntax highlighting, the annotator can call AnnotationHolder.createInfoAnnotation() with an empty message and then call Annotation.setTextAttributes() to specify the text attributes key for the highlighting.

Examples:

• Annotator for Properties language plugin
• Custom Language Support Tutorial: Annotator

External tool

Finally, if the custom language employs external tools for validating files in the language (for example, uses the Xerces library for XML schema validation), it can provide an implementation of the ExternalAnnotator interface and register it in com.intellij.externalAnnotator extension point. The ExternalAnnotator highlighting has the lowest priority and is invoked only after all other background processing has completed. It uses the same AnnotationHolder interface for converting the output of the external tool into editor highlighting.

Color settings

The plugin can also provide a configuration interface to allow the user to configure the colors used for highlighting specific items. In order to do that, it should provide an implementation of ColorSettingPage and register it in the com.intellij.colorSettingsPage extension point.

The Export to HTML feature uses the same syntax highlighting mechanism as the editor, so it will work automatically for custom languages which provide a syntax highlighter.

Examples:

• ColorSettingsPage for Properties language plugin
• Custom Language Support Tutorial: Color Settings Page