mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-30 10:17:50 +08:00
[md] syntax and error highlighting separated
This commit is contained in:
Anna Bulenkova
parent
ef3687cbad
commit
8b12b64d3e
@ -50,6 +50,7 @@
|
||||
* [Registering File Type](registering_file_type.html)
|
||||
* [Implementing Lexer](implementing_lexer.html)
|
||||
* [Implementing Parser and PSI](implementing_parser_and_psi.html)
|
||||
* [Syntax Highlighting and Error Highlighting](syntax_highlighting_and_error_highlighting.html)
|
||||
* [XML DOM API](xml_dom_api.html)
|
||||
* [Spring API](spring_api.html)
|
||||
* [VCS Integration Plugins](vcs_integration_for_plugins.html)
|
||||
|
||||
@ -22,111 +22,7 @@ Providing custom language support includes the following major steps:
|
||||
* [Registering File Type](registering_file_type.html)
|
||||
* [Implementing Lexer](implementing_lexer.html)
|
||||
* [Implementing Parser and PSI](implementing_parser_and_psi.html)
|
||||
|
||||
|
||||
## Syntax Highlighting and Error Highlighting
|
||||
|
||||
The class used to specify how a particular range of text should be highlighted is called
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java).
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
to specific attributes used in an editor is defined by the
|
||||
[EditorColorsScheme](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/colors/EditorColorsScheme.java)
|
||||
class, and can be configured by the user if the plugin provides an appropriate configuration interface.
|
||||
Highlighting from multiple
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
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](color_scheme_management.html).
|
||||
|
||||
|
||||
### Lexer
|
||||
|
||||
The syntax and error highlighting is performed on multiple levels.
|
||||
The first level of syntax highlighting is based on the lexer output, and is provided through the
|
||||
[SyntaxHighlighter](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighter.java)
|
||||
interface.
|
||||
The syntax highlighter returns the
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
instances for each token type which needs special highlighting.
|
||||
For highlighting lexer errors, the standard
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
for bad characters
|
||||
[HighlighterColors.BAD_CHARACTER](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/HighlighterColors.java)
|
||||
can be used.
|
||||
|
||||
**Example:**
|
||||
[SyntaxHighlighter](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesHighlighter.java)
|
||||
implementation for
|
||||
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
|
||||
|
||||
|
||||
### 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()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
|
||||
object passed to it, and optionally calls ```registerFix()``` on the returned
|
||||
[Annotation](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
|
||||
object to add a quick fix for the error or warning.
|
||||
To apply additional syntax highlighting, the annotator can call
|
||||
[AnnotationHolder.createInfoAnnotation()](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
|
||||
with an empty message and then call
|
||||
[Annotation.setTextAttributes()](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
|
||||
to specify the text attributes key for the highlighting.
|
||||
|
||||
**Example:**
|
||||
[Annotator](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesAnnotator.java)
|
||||
for
|
||||
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
|
||||
|
||||
|
||||
### 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](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
|
||||
interface and register it in `com.intellij.externalAnnotator` extension point.
|
||||
The
|
||||
[ExternalAnnotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
|
||||
highlighting has the lowest priority and is invoked only after all other background processing has completed.
|
||||
It uses the same
|
||||
[AnnotationHolder](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java)
|
||||
and register it in the ```com.intellij.colorSettingsPage``` extension point.
|
||||
|
||||
**Example**:
|
||||
[ColorSettingsPage](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/openapi/options/colors/pages/PropertiesColorsPage.java)
|
||||
for
|
||||
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
|
||||
|
||||
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.
|
||||
* [Syntax Highlighting and Error Highlighting](syntax_highlighting_and_error_highlighting.html)
|
||||
|
||||
## References and Resolve
|
||||
|
||||
|
||||
106
syntax_highlighting_and_error_highlighting.md
Normal file
106
syntax_highlighting_and_error_highlighting.md
Normal file
@ -0,0 +1,106 @@
|
||||
---
|
||||
layout: editable
|
||||
title: Syntax Highlighting and Error Highlighting
|
||||
---
|
||||
|
||||
The class used to specify how a particular range of text should be highlighted is called
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java).
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
to specific attributes used in an editor is defined by the
|
||||
[EditorColorsScheme](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/colors/EditorColorsScheme.java)
|
||||
class, and can be configured by the user if the plugin provides an appropriate configuration interface.
|
||||
Highlighting from multiple
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
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](color_scheme_management.html).
|
||||
|
||||
|
||||
### Lexer
|
||||
|
||||
The syntax and error highlighting is performed on multiple levels.
|
||||
The first level of syntax highlighting is based on the lexer output, and is provided through the
|
||||
[SyntaxHighlighter](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighter.java)
|
||||
interface.
|
||||
The syntax highlighter returns the
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
instances for each token type which needs special highlighting.
|
||||
For highlighting lexer errors, the standard
|
||||
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
|
||||
for bad characters
|
||||
[HighlighterColors.BAD_CHARACTER](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/HighlighterColors.java)
|
||||
can be used.
|
||||
|
||||
**Example:**
|
||||
[SyntaxHighlighter](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesHighlighter.java)
|
||||
implementation for
|
||||
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
|
||||
|
||||
|
||||
### 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()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
|
||||
object passed to it, and optionally calls ```registerFix()``` on the returned
|
||||
[Annotation](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
|
||||
object to add a quick fix for the error or warning.
|
||||
To apply additional syntax highlighting, the annotator can call
|
||||
[AnnotationHolder.createInfoAnnotation()](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
|
||||
with an empty message and then call
|
||||
[Annotation.setTextAttributes()](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
|
||||
to specify the text attributes key for the highlighting.
|
||||
|
||||
**Example:**
|
||||
[Annotator](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesAnnotator.java)
|
||||
for
|
||||
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
|
||||
|
||||
|
||||
### 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](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
|
||||
interface and register it in `com.intellij.externalAnnotator` extension point.
|
||||
The
|
||||
[ExternalAnnotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
|
||||
highlighting has the lowest priority and is invoked only after all other background processing has completed.
|
||||
It uses the same
|
||||
[AnnotationHolder](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
|
||||
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](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java)
|
||||
and register it in the ```com.intellij.colorSettingsPage``` extension point.
|
||||
|
||||
**Example**:
|
||||
[ColorSettingsPage](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/openapi/options/colors/pages/PropertiesColorsPage.java)
|
||||
for
|
||||
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
|
||||
|
||||
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.
|
||||
Loading…
x
Reference in New Issue
Block a user