diff --git a/topics/intro/content_updates.md b/topics/intro/content_updates.md index 05b42519e..2d55f8d69 100644 --- a/topics/intro/content_updates.md +++ b/topics/intro/content_updates.md @@ -12,6 +12,12 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma ## 2023 +### September +{#september-23} + +Inlay Hints +: Update [](inlay_hints.md) page with the information about new APIs. + ### June {#june-23} diff --git a/topics/reference_guide/custom_language_support/inlay_hints.md b/topics/reference_guide/custom_language_support/inlay_hints.md index 69d346a78..e9fb3c7f6 100644 --- a/topics/reference_guide/custom_language_support/inlay_hints.md +++ b/topics/reference_guide/custom_language_support/inlay_hints.md @@ -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: - 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. -- 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., - parameter names in method and function calls. -- The `com.intellij.codeInsight.inlayProvider` EP is used for more general cases where plugin developers - need extended control or want to implement interactive features for inlay hints. +The main characteristic of the inlay is the way it is displayed in the editor: +- **inline** - inlays displayed in the code between code tokens +- **block** - inlays displayed above a code block -The main difference between both EPs is that the first one only lets you place string inlays -while the second one allows for the placement of inline and block inlays with customizable representation. +Depending on the requirements and target IntelliJ Platform version, there are several extension points to choose from, when implementing inlay hints. + +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). > Corresponding entries from Settings | Editor | Inlay Hints 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) -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. -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) - implements inline hints for Groovy methods. -- [`KotlinInlayParameterHintsProvider`](%gh-ic%/plugins/kotlin/idea/src/org/jetbrains/kotlin/idea/codeInsight/hints/KotlinInlayParameterHintsProvider.kt) - implements parameter hints for Kotlin language. +To suppress inlay parameter hints in specific places, implement +[`ParameterNameHintsSuppressor`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/ParameterNameHintsSuppressor.kt) +and register it in `com.intellij.codeInsight.parameterNameHintsSuppressor` EP. -### 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 Preferences | Editor | Inlay Hints | Code vision by choosing a value in Default position for metrics combo box, or by selecting Position 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) -and register it as `com.intellij.codeInsight.inlayProvider` EP. -The API documentation of `InlayHintsProvider` explains in detail the rationale behind all methods. +and register it in `com.intellij.codeInsight.inlayProvider` EP. +See the API documentation for the details. -Examples can be found in the following IntelliJ Platform plugins: - -- Groovy provides several implementations of this EP that can serve as a reference: - [`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). +**Examples**: +- [`GroovyLocalVariableTypeHintsInlayProvider`](%gh-ic%/plugins/groovy/src/org/jetbrains/plugins/groovy/codeInsight/hint/types/GroovyLocalVariableTypeHintsInlayProvider.kt) - shows local variable types in Groovy code +- [`MarkdownTableInlayProvider`](%gh-ic%/plugins/markdown/core/src/org/intellij/plugins/markdown/editor/tables/ui/MarkdownTableInlayProvider.kt) - _decorates_ tables in Markdown files. - For a more complex example, see [`KotlinLambdasHintsProvider`](%gh-ic%/plugins/kotlin/idea/src/org/jetbrains/kotlin/idea/codeInsight/hints/KotlinLambdasHintsProvider.kt), its parent class and all implementations. @@ -75,19 +121,18 @@ Examples can be found in the following IntelliJ Platform plugins: 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. It gives insight into what’s possible. -2. If you want to support multiple languages with a single type of inlay hints, please see - [`InlayHintsProviderFactory`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProviderFactory.kt) -3. If you want to suppress inlay hints in specific places, please implement - [`ParameterNameHintsSuppressor`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/ParameterNameHintsSuppressor.kt) - and register it as `com.intellij.codeInsight.parameterNameHintsSuppressor` EP. -4. For testing inlay hints, 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/declarative/InlayHintsProviderFactory.kt) (2023.1+) + or + [`InlayHintsProviderFactory`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProviderFactory.kt) (pre-2023.1). +3. For testing inlay hints, see [`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). -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), - please use + use [`InlayHintsPassFactory.forceHintsUpdateOnNextPass()`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/InlayHintsPassFactory.kt) or [`ParameterHintsPassFactory.forceHintsUpdateOnNextPass()`](%gh-ic%/platform/lang-impl/src/com/intellij/codeInsight/hints/ParameterHintsPassFactory.java) 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.