hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

inlay_hints.md: Update page with the information about new APIs (#1104)

Browse Source
This commit is contained in:
Karol Lewandowski 2023-09-05 07:13:54 +02:00 committed by GitHub
parent 6b70dc3709
commit 16efc6408d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 90 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
topics/intro/content_updates.md
View File

@ -12,6 +12,12 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma
## 2023 ## 2023
### September
{#september-23}
Inlay Hints
: Update [](inlay_hints.md) page with the information about new APIs.
### June ### June
{#june-23} {#june-23}

123
topics/reference_guide/custom_language_support/inlay_hints.md
View File

@ -18,54 +18,100 @@ Inlay hints are flexible and have a wide range of applications in the IntelliJ P
For instance, the following are well-known examples where inlay hints are used: For instance, the following are well-known examples where inlay hints are used:
- Java uses inlays to display type annotations in Java chained method calls. - Java uses inlays to display type annotations in Java chained method calls.
- Kotlin uses inlays in range expressions to show, e.g. less-than, or less-than-or-equal signs to let developers know if intervals are inclusive or exclusive.
- In version-controlled projects, the author of the code is shown using inlay hints. - In version-controlled projects, the author of the code is shown using inlay hints.
- Kotlin uses inlays in range expressions to show, e.g. less-than, or less-than-or-equal signs to let
developers know if intervals are inclusive or exclusive.
The IntelliJ Platform offers two extension points (EP) that plugin developers can implement to create inlay hints: ## Implementation
- The `com.intellij.codeInsight.parameterNameHints` EP is used to provide simple text inlays for, e.g., The main characteristic of the inlay is the way it is displayed in the editor:
parameter names in method and function calls. - **inline** - inlays displayed in the code between code tokens
- The `com.intellij.codeInsight.inlayProvider` EP is used for more general cases where plugin developers - **block** - inlays displayed above a code block
need extended control or want to implement interactive features for inlay hints.
The main difference between both EPs is that the first one only lets you place string inlays Depending on the requirements and target IntelliJ Platform version, there are several extension points to choose from, when implementing inlay hints.
while the second one allows for the placement of inline and block inlays with customizable representation.
This section describes the available APIs and their use cases.
> To inspect existing Inlays in the IDE, use [UI Inspector](internal_ui_inspector.md#editor). > To inspect existing Inlays in the IDE, use [UI Inspector](internal_ui_inspector.md#editor).
> Corresponding entries from <ui-path>Settings | Editor | Inlay Hints</ui-path> are also available from [](internal_ui_inspector.md#inspecting-settings). > Corresponding entries from <ui-path>Settings | Editor | Inlay Hints</ui-path> are also available from [](internal_ui_inspector.md#inspecting-settings).
## Implementation ### Inlay Parameter Hints Provider
### Simple Text Inlay Hints Inlay parameter hints are simple string **inline** inlays placed before parameter names in method and function calls.
It is not possible to provide advanced presentation and behavior of inlay parameter hints.
Implement To provide inlay parameter hints, implement
[`InlayParameterHintsProvider`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayParameterHintsProvider.java) [`InlayParameterHintsProvider`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayParameterHintsProvider.java)
and register it as `com.intellij.codeInsight.parameterNameHints` EP. and register it in `com.intellij.codeInsight.parameterNameHints` extension point (EP).
The API documentation of `InlayParameterHintsProvider` explains in detail the rationale behind all methods. The API documentation of `InlayParameterHintsProvider` explains in detail the rationale behind all methods.
Examples can be found in the following IntelliJ Platform plugins: **Examples**:
- [`GroovyInlayParameterHintsProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/GroovyInlayParameterHintsProvider.kt) - shows parameter hints in Groovy code
- [`KotlinInlayParameterHintsProvider`](%gh-ic%/plugins/kotlin/idea/src/org/jetbrains/kotlin/idea/codeInsight/hints/KotlinInlayParameterHintsProvider.kt) - shows parameter hints in Kotlin code
- [`GroovyInlayParameterHintsProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/GroovyInlayParameterHintsProvider.kt) To suppress inlay parameter hints in specific places, implement
implements inline hints for Groovy methods. [`ParameterNameHintsSuppressor`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/ParameterNameHintsSuppressor.kt)
- [`KotlinInlayParameterHintsProvider`](%gh-ic%/plugins/kotlin/idea/src/org/jetbrains/kotlin/idea/codeInsight/hints/KotlinInlayParameterHintsProvider.kt) and register it in `com.intellij.codeInsight.parameterNameHintsSuppressor` EP.
implements parameter hints for Kotlin language.
### Advanced Inlay Hints ### Declarative Inlay Hints Provider
Implement > This API is available since 2023.1.
>
{style="note"}
To provide **inline** inlay hints with custom presentation and behavior, implement declarative
[`InlayHintsProvider`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/declarative/InlayHintsProvider.kt)
and register it in `com.intellij.codeInsight.declarativeInlayProvider` EP.
See the API documentation for the details.
**Examples**:
- [`JavaImplicitTypeDeclarativeInlayHintsProvider`](%gh-ic%/java/java-impl/src/com/intellij/codeInsight/hints/JavaImplicitTypeDeclarativeInlayHintsProvider.kt) - shows inferred type for variables declared with the `var` keyword in Java code when the inferred type may not be clear
- [`JavaMethodChainsDeclarativeInlayProvider`](%gh-ic%/java/java-impl/src/com/intellij/codeInsight/hints/JavaMethodChainsDeclarativeInlayProvider.kt) - shows method return types in call chains in Java code
### Code Vision Provider
> This API is available since 2022.1.
> It is still in experimental state and may be changed without preserving backward compatibility.
>
{style="note"}
Code vision provider allows for providing **block** inlay hints for elements like class, method, field, etc.
If there are multiple hints provided for a single element, all will be displayed in the same line to save vertical space.
Code vision hints can be displayed over the element, or on the right, at the end of line.
It is configurable by users in <ui-path>Preferences | Editor | Inlay Hints | Code vision</ui-path> by choosing a value in <control>Default position for metrics</control> combo box, or by selecting <control>Position</control> in specific provider entries.
There are two extension points for implementing a code vision provider:
- [`DaemonBoundCodeVisionProvider`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/codeVision/DaemonBoundCodeVisionProvider.kt) registered in `com.intellij.codeInsight.daemonBoundCodeVisionProvider` EP
- [`CodeVisionProvider`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/codeVision/CodeVisionProvider.kt) registered in `com.intellij.codeInsight.codeVisionProvider` EP
`DaemonBoundCodeVisionProvider` API should be used in cases when code vision entries are related to PSI, so that calculated values are invalidated and recalculated on PSI changes.
`CodeVisionProvider` API should be used for cases when presented information doesn't depend on the PSI.
**Examples**:
- [`JavaInheritorsCodeVisionProvider`](%gh-ic%/java/java-impl/src/com/intellij/codeInsight/daemon/impl/JavaInheritorsCodeVisionProvider.kt) - shows number of Java class or method inheritors. Clicking the inlay hint opens the list of inheritors. This provider is `DaemonBoundCodeVisionProvider`.
- [`JavaReferencesCodeVisionProvider`](%gh-ic%/java/java-impl/src/com/intellij/codeInsight/daemon/impl/JavaReferencesCodeVisionProvider.kt) - shows number of usages of Java class or member. Clicking the inlay opens the list of usages or navigates to the usage if only one exists. This provider is `DaemonBoundCodeVisionProvider`.
- [`VcsCodeVisionProvider`](%gh-ic%/platform/vcs-impl/src/com/intellij/codeInsight/hints/VcsCodeVisionProvider.kt) - shows the author of a given element, e.g., class or method, based on VCS information. This provider is `CodeVisionProvider`.
### Inlay Hints Provider
Inlay hints provider allows for implementing both **inline** and **block** inlay hints with custom presentation and behavior.
See the API documentation for the details.
> For implementing **inline** inlay hints in versions 2023.1 and newer, [](#declarative-inlay-hints-provider) is recommended.
>
> For implementing **block** inlay hints in versions 2022.1 and newer, [](#code-vision-provider) is recommended.
>
{style="warning"}
To provide inlay hints, implement
[`InlayHintsProvider`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt) [`InlayHintsProvider`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt)
and register it as `com.intellij.codeInsight.inlayProvider` EP. and register it in `com.intellij.codeInsight.inlayProvider` EP.
The API documentation of `InlayHintsProvider` explains in detail the rationale behind all methods. See the API documentation for the details.
Examples can be found in the following IntelliJ Platform plugins: **Examples**:
- [`GroovyLocalVariableTypeHintsInlayProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/types/GroovyLocalVariableTypeHintsInlayProvider.kt) - shows local variable types in Groovy code
- Groovy provides several implementations of this EP that can serve as a reference: - [`MarkdownTableInlayProvider`](%gh-ic%/plugins/markdown/core/src/org/intellij/plugins/markdown/editor/tables/ui/MarkdownTableInlayProvider.kt) - _decorates_ tables in Markdown files.
[`GroovyParameterTypeHintsInlayProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/types/GroovyParameterTypeHintsInlayProvider.kt),
[`GroovyLocalVariableTypeHintsInlayProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/types/GroovyLocalVariableTypeHintsInlayProvider.kt),
and [`GroovyImplicitNullArgumentHintProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/GroovyImplicitNullArgumentHintProvider.kt).
- Markdown uses this EP for _decorating_ tables in
[`MarkdownTableInlayProvider`](%gh-ic%/plugins/markdown/core/src/org/intellij/plugins/markdown/editor/tables/ui/MarkdownTableInlayProvider.kt).
- For a more complex example, see - For a more complex example, see
[`KotlinLambdasHintsProvider`](%gh-ic%/plugins/kotlin/idea/src/org/jetbrains/kotlin/idea/codeInsight/hints/KotlinLambdasHintsProvider.kt), [`KotlinLambdasHintsProvider`](%gh-ic%/plugins/kotlin/idea/src/org/jetbrains/kotlin/idea/codeInsight/hints/KotlinLambdasHintsProvider.kt),
its parent class and all implementations. its parent class and all implementations.
@ -75,19 +121,18 @@ Examples can be found in the following IntelliJ Platform plugins:
1. Go to 1. Go to
[Settings | Editor | Inlay Hints](https://www.jetbrains.com/help/idea/inlay-hints.html) and check out inlays that have already been implemented. [Settings | Editor | Inlay Hints](https://www.jetbrains.com/help/idea/inlay-hints.html) and check out inlays that have already been implemented.
It gives insight into what’s possible. It gives insight into what’s possible.
2. If you want to support multiple languages with a single type of inlay hints, please see 2. To support multiple languages with a single type of inlay hints, see declarative
[`InlayHintsProviderFactory`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProviderFactory.kt) [`InlayHintsProviderFactory`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/declarative/InlayHintsProviderFactory.kt) (2023.1+)
3. If you want to suppress inlay hints in specific places, please implement or
[`ParameterNameHintsSuppressor`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/ParameterNameHintsSuppressor.kt) [`InlayHintsProviderFactory`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProviderFactory.kt) (pre-2023.1).
and register it as `com.intellij.codeInsight.parameterNameHintsSuppressor` EP. 3. For testing inlay hints, see
4. For testing inlay hints, see
[`InlayHintsProviderTestCase`](%gh-ic%/platform/testFramework/src/com/intellij/testFramework/utils/inlays/InlayHintsProviderTestCase.kt) [`InlayHintsProviderTestCase`](%gh-ic%/platform/testFramework/src/com/intellij/testFramework/utils/inlays/InlayHintsProviderTestCase.kt)
and [`InlayParameterHintsTest`](%gh-ic%/platform/testFramework/src/com/intellij/testFramework/utils/inlays/InlayParameterHintsTest.kt). and [`InlayParameterHintsTest`](%gh-ic%/platform/testFramework/src/com/intellij/testFramework/utils/inlays/InlayParameterHintsTest.kt).
5. If you need to force inlay hints to update when using 4. To force inlay hints to update when using
[`DaemonCodeAnalyzer.restart()`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInsight/daemon/DaemonCodeAnalyzer.java), [`DaemonCodeAnalyzer.restart()`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInsight/daemon/DaemonCodeAnalyzer.java),
please use use
[`InlayHintsPassFactory.forceHintsUpdateOnNextPass()`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/InlayHintsPassFactory.kt) [`InlayHintsPassFactory.forceHintsUpdateOnNextPass()`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/InlayHintsPassFactory.kt)
or or
[`ParameterHintsPassFactory.forceHintsUpdateOnNextPass()`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/ParameterHintsPassFactory.java) [`ParameterHintsPassFactory.forceHintsUpdateOnNextPass()`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/ParameterHintsPassFactory.java)
when using `InlayParameterHintsProvider` before you call `restart()`. when using `InlayParameterHintsProvider` before you call `restart()`.
If you want to force an update on a specific editor, note that the method also has an overload that takes an `Editor` instance. To force an update on a specific editor, use the method overload that takes an `Editor` instance.