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

Merge branch 'main' into ipgp-2.0

Browse Source
This commit is contained in:
Yann Cébron 2024-02-06 15:04:48 +01:00 committed by GitHub
commit fedba94810
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
41 changed files with 361 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/code-samples.yml vendored
View File

@ -18,7 +18,7 @@ jobs:
- name: Fetch Sources
uses: actions/checkout@v4
- name: Gradle Wrapper Validation
uses: gradle/wrapper-validation-action@v1.1.0
uses: gradle/wrapper-validation-action@v2.0.0
samples:
name: Code Samples / ${{ matrix.plugin }}

8
c.list Normal file
View File

@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<!DOCTYPE categories SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
<categories>
<category id="related" name="Related topics" order="1"/>
<category id="external" name="External resources" order="2"/>
</categories>

2
code_samples/action_basics/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/comparing_string_references_inspection/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/conditional_operator_intention/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/editor_basics/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/facet_basics/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/framework_basics/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/kotlin_demo/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
id("org.jetbrains.kotlin.jvm") version "1.9.22"
}

2
code_samples/live_templates/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/max_opened_projects/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/module/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/product_specific/pycharm_basics/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "com.intellij.sdk"

2
code_samples/project_model/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/project_view_pane/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/project_wizard/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/psi_demo/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/run_configuration/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/settings/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/simple_language_plugin/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/tool_window/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

2
code_samples/tree_structure_provider/build.gradle.kts
View File

@ -2,7 +2,7 @@
plugins {
id("java")
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "org.intellij.sdk"

21
reference_guide/api_changes_list_2024.md
View File

@ -102,6 +102,27 @@ NOTE: Entries not starting with code quotes (`name`) can be added to document no
`com.intellij.vcs.log.VcsLogFileHistoryHandler.getSupportedVcs()` abstract method added
: Must be implemented.
Method `com.intellij.psi.util.PsiTreeUtilKt.getFirstLeaf(PsiElement)` renamed to `com.intellij.psi.util.PsiTreeUtilKt.firstLeaf(PsiElement)`
: Update code usages.
Method `com.intellij.psi.util.PsiTreeUtilKt.getLastLeaf(PsiElement)` renamed to `com.intellij.psi.util.PsiTreeUtilKt.lastLeaf(PsiElement)`
: Update code usages.
Method `com.intellij.psi.util.PsiTreeUtilKt.getChildLeafs(PsiElement)` renamed to `com.intellij.psi.util.PsiTreeUtilKt.childLeafs(PsiElement)`
: Update code usages.
`org.apache.tools` package removed
: Please provide all necessary libraries in your plugin distribution.
`com.intellij.openapi.projectRoots.impl.ProjectJdkImpl.readExternal(Element, ProjectJdkTable)` method removed
: Use `com.intellij.openapi.projectRoots.impl.ProjectJdkImpl.readExternal(Element, Function<String, SdkTypeId>)` instead.
`com.intellij.openapi.projectRoots.impl.SdkConfigurationUtil.createSdk(Collection<Sdk>, String, SdkType, SdkAdditionalData, String)` method return type changed from `ProjectJdkImpl` to `Sdk`
: Update code usages.
`com.intellij.openapi.projectRoots.impl.SdkConfigurationUtil.createSdk(Collection<Sdk>, VirtualFile, SdkType, SdkAdditionalData, String)` method return type changed from `ProjectJdkImpl` to `Sdk`
: Update code usages.
### Django Plugin 2024.1
Package `com.jetbrains.jinja2` renamed to `com.intellij.jinja`

9
topics/_generated/android_studio_releases.md
View File

@ -6,12 +6,15 @@
| Release Name | Channel | Release Date | Version | IntelliJ IDEA Version |
|--------------|:-------:|--------------|---------|-----------------------|
| Jellyfish \| 2023.3.1 Canary 8 | ![Canary][canary] | February 5, 2024 | **2023.3.1.8**<p>AI-233.14015.106.2331.11392117</p> | **2023.3.3**<p>233.14015.106</p> |
| Jellyfish \| 2023.3.1 Canary 7 | ![Canary][canary] | January 26, 2024 | **2023.3.1.7**<p>AI-233.13135.103.2331.11360849</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 6 | ![Canary][canary] | January 24, 2024 | **2023.3.1.6**<p>AI-233.13135.103.2331.11350331</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 5 | ![Canary][canary] | January 22, 2024 | **2023.3.1.5**<p>AI-233.13135.103.2331.11329247</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 4 | ![Canary][canary] | January 12, 2024 | **2023.3.1.4**<p>AI-233.13135.103.2331.11301475</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 3 | ![Canary][canary] | January 4, 2024 | **2023.3.1.3**<p>AI-233.13135.103.2331.11273936</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 2 | ![Canary][canary] | January 2, 2024 | **2023.3.1.2**<p>AI-233.13135.103.2331.11259770</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 1 | ![Canary][canary] | December 28, 2023 | **2023.3.1.1**<p>AI-233.13135.103.2331.11247450</p> | **2023.3.2**<p>233.13135.103</p> |
| Iguana \| 2023.2.1 RC 1 | ![RC][rc] | February 5, 2024 | **2023.2.1.21**<p>AI-232.10227.8.2321.11379558</p> | **2023.2.5**<p>232.10227.8</p> |
| Iguana \| 2023.2.1 Beta 2 | ![Beta][beta] | January 10, 2024 | **2023.2.1.20**<p>AI-232.10227.8.2321.11280706</p> | **2023.2.5**<p>232.10227.8</p> |
| Iguana \| 2023.2.1 Beta 1 | ![Beta][beta] | December 26, 2023 | **2023.2.1.19**<p>AI-232.10227.8.2321.11231672</p> | **2023.2.5**<p>232.10227.8</p> |
| Iguana \| 2023.2.1 Canary 18 | ![Canary][canary] | December 13, 2023 | **2023.2.1.18**<p>AI-232.10227.8.2321.11203637</p> | **2023.2.5**<p>232.10227.8</p> |
@ -494,10 +497,10 @@
| Release Name | Channel | Release Date | Version | IntelliJ IDEA Version |
|--------------|:-------:|--------------|---------|-----------------------|
| Jellyfish \| 2023.3.1 Canary 8 | ![Canary][canary] | February 5, 2024 | **2023.3.1.8**<p>AI-233.14015.106.2331.11392117</p> | **2023.3.3**<p>233.14015.106</p> |
| Jellyfish \| 2023.3.1 Canary 7 | ![Canary][canary] | January 26, 2024 | **2023.3.1.7**<p>AI-233.13135.103.2331.11360849</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 6 | ![Canary][canary] | January 24, 2024 | **2023.3.1.6**<p>AI-233.13135.103.2331.11350331</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 5 | ![Canary][canary] | January 22, 2024 | **2023.3.1.5**<p>AI-233.13135.103.2331.11329247</p> | **2023.3.2**<p>233.13135.103</p> |
| Jellyfish \| 2023.3.1 Canary 4 | ![Canary][canary] | January 12, 2024 | **2023.3.1.4**<p>AI-233.13135.103.2331.11301475</p> | **2023.3.2**<p>233.13135.103</p> |
| Iguana \| 2023.2.1 Beta 2 | ![Beta][beta] | January 10, 2024 | **2023.2.1.20**<p>AI-232.10227.8.2321.11280706</p> | **2023.2.5**<p>232.10227.8</p> |
| Iguana \| 2023.2.1 RC 1 | ![RC][rc] | February 5, 2024 | **2023.2.1.21**<p>AI-232.10227.8.2321.11379558</p> | **2023.2.5**<p>232.10227.8</p> |
| Hedgehog \| 2023.1.1 Patch 2 | ![Patch][patch] | January 23, 2024 | **2023.1.1.28**<p>AI-231.9392.1.2311.11330709</p> | **2023.1.5**<p>231.9392.1</p> |
[release]: https://img.shields.io/badge/-Release-blue?style=flat-square

2
topics/_shared/snippets.md
View File

@ -73,7 +73,7 @@ _Early Access Program_ (EAP) releases of upcoming versions are available [here](
>
> Please make sure to always upgrade `gradle-intellij-plugin` to the latest version [%gradle-intellij-plugin-version%](https://github.com/jetbrains/gradle-intellij-plugin/releases)
>
{style="note"}
{title="IDE and Java Versions" style="note"}
</snippet>

30
topics/basics/bundling_plugin_openapi_sources.md
View File

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Bundling Plugin API Sources
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Exposing plugin's API sources for other plugins.</link-summary>
If a plugin exposes its own API that is meant to be used by other plugins, it is worth considering bundling the plugin's API sources in the ZIP distribution.
@ -17,16 +17,26 @@ Being able to see API sources drastically improves the development experience, a
The API source JARs must be located in the <path>example-plugin.zip!/plugin/lib/src</path> directory in the plugin ZIP distribution, e.g.:
```text
example-plugin.zip
└── example-plugin
└── lib
├── example-plugin.jar
└── src
└── example-plugin-api-src.jar
```plantuml
@startuml
skinparam TitleFontName JetBrains Sans
skinparam TitleFontStyle plain
skinparam TitleFontSize 16
skinparam DefaultTextAlignment left
title
example-plugin.zip // (Plugin distribution file) //
|_ example-plugin
|_ lib
|_ example-plugin.jar // (Plugin) //
|_ src
|_ example-plugin-api-src.jar // (API sources JAR) //
end title
@enduml
```
The plugin ZIP can contain multiple source JARs, and there are no strict rules for the source JAR names.
The plugin distribution ZIP file can contain multiple source JARs, and there are no strict rules for the source JAR names.
## Defining Plugin API

96
topics/basics/disposers.md
View File

@ -1,4 +1,4 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Disposer and Disposable
@ -14,7 +14,7 @@ The most common resource type managed by `Disposer` is listeners, but there are
The `Disposer` is a singleton that manages a tree of [`Disposable`](%gh-ic%/platform/util/src/com/intellij/openapi/Disposable.java) instances.
A `Disposable` is an interface for any object providing a `Disposable.dispose()` method to release heavyweight resources after a specific lifetime.
The `Disposer` supports chaining `Disposables` in parent-child relationships.
The `Disposer` supports chaining `Disposable` objects in parent-child relationships.
## Automatically Disposed Objects
@ -31,6 +31,60 @@ The primary purpose of the [`Disposer`](%gh-ic%/platform/util/src/com/intellij/o
The `Disposer` organizes `Disposable` objects in a tree of parent-child relationships.
The tree of `Disposable` objects ensures the `Disposer` releases children of a parent first.
Parent objects always live longer than their children.
The following diagram shows a simplified example of `Disposer`'s tree:
```plantuml
@startuml
skinparam DefaultFontName JetBrains Sans
skinparam DefaultFontSize 13
skinparam DefaultTextAlignment center
hide empty members
hide circle
rectangle "Root\nDisposable" as root
rectangle "Application" as application
rectangle "App\nListener" as listener
rectangle "Dialog\nWrapper" as dialogDisposable
rectangle "Dialog\nResource" as dialogResource
rectangle "Services of\nApplication" as applicationServices
rectangle "App\nService 1" as appService1
rectangle "App\nService 2" as appService2
rectangle "My\nProject" as project
rectangle "My\nListener" as projectListener
rectangle "My\nAlarm" as projectAlarm
rectangle "Services of\nMy Project" as projectServices
rectangle "Project\nService A" as projectService1
rectangle "Project\nService B" as projectService2
root -- application
root -- applicationServices
root -- project
root -- projectServices
application -- listener
application -- dialogDisposable
dialogDisposable -- dialogResource
applicationServices -- appService1
applicationServices -- appService2
project -- projectListener
project -- projectAlarm
projectServices -- projectService1
projectServices -- projectService2
@enduml
```
When _My Project_ is closed and its disposal is triggered by the platform, the Disposer API will dispose _My Listener_ and _My Alarm_ before _My Project_, and _Project Service A_ and _Project Service B_ before _Services of My Project_.
See [The Disposable Interface](#implementing-the-disposable-interface) for more information about creating `Disposable` classes.
@ -47,7 +101,7 @@ One of the parent `Disposables` provided by the IntelliJ Platform can be chosen,
Use the following guidelines to choose the correct parent:
* For resources required for a plugin's entire lifetime, use an application or project level [service](plugin_services.md).
* For resources required for a plugin's entire lifetime, use an application or project level [service](plugin_services.md). Example: [`PythonPluginDisposable`](%gh-ic%/python/openapi/src/com/jetbrains/python/PythonPluginDisposable.java).
* For resources required while a [dialog](dialog_wrapper.md) is displayed, use `DialogWrapper.getDisposable()`.
* For resources required while a [tool window](tool_windows.md) tab is displayed, pass your instance implementing `Disposable` to `Content.setDisposer()`.
* For resources with a shorter lifetime, create a disposable using `Disposer.newDisposable()` and dispose it manually using `Disposable.dispose()`.
@ -56,11 +110,37 @@ Use the following guidelines to choose the correct parent:
> Even though `Application` and `Project` implement `Disposable`, they must NEVER be used as parent disposables in plugin code.
> Disposables registered using those objects as parents will not be disposed when the plugin is unloaded, leading to memory leaks.
>
> Consider a case of a disposable resource created by a plugin and registered with a project as its parent.
> The following lifetime diagram shows that the resource will outlive the plugin and live as long as the project.
> ```mermaid
> %%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': 'green', 'background': 'yellow'}}}%%
> gantt
> dateFormat X
> %% do not remove trailing space in axisFormat
> axisFormat ‎
> section Lifetimes
> Project : 0, 10
> Plugin : 2, 5
> Plugin Resource : crit, 2, 10
> ```
>
> If the resource used, e.g., a plugin's project-level service (if shorter living parents are possible, prefer them), the resource would be disposed together with the plugin:
> ```mermaid
> gantt
> dateFormat X
> %% do not remove trailing space in axisFormat
> axisFormat ‎
> section Lifetimes
> Project : 0, 10
> Plugin : 2, 5
> Plugin Resource : 2, 5
> ```
>
> Inspection <control>Plugin DevKit | Code | Incorrect parentDisposable parameter</control> will highlight such problems.
>
{style="warning"}
{style="warning" title="Plugin disposable leaks"}
The `Disposer` API's flexibility means that if the parent instance is chosen unwisely, the child may consume resources for longer than required.
The `Disposer` API flexibility means that if the parent instance is chosen unwisely, the child may consume resources for longer than required.
Continuing to use resources when they are no longer needed can be a severe source of contention due to leaving some zombie objects behind due to each invocation.
An additional challenge is that these kinds of issues won't be reported by the regular leak checker utilities, because technically, it's not a memory leak from the test suite perspective.
@ -92,7 +172,7 @@ Always pass a parent disposable to `MessageBus.connect()`, and make sure it has
### Determining Disposal Status
You can use `Disposer.isDisposed()` to check whether a `Disposable` has already been disposed.
This check is useful, for example, for an asynchronous callback to a `Disposable` that may be disposed before the callback is executed.
This check is useful, for example, for an asynchronous callback to a `Disposable` that may be disposed before the callback is executed.
In such a case, the best strategy is usually to do nothing and return early.
> Non-disposed objects shouldn't hold onto references to disposed objects, as this constitutes a memory leak.
@ -135,7 +215,7 @@ public class Foo<T> extends JBFoo implements Disposable {
}
```
A lot of code setting-up all the conditions requiring release in `dispose()` has been omitted for simplicity.
A lot of code setting up all the conditions requiring release in `dispose()` has been omitted for simplicity.
Regardless, it illustrates the basic pattern, which is:
* In this case, the parent disposable is passed into the constructor,
@ -153,7 +233,7 @@ When the application exits, it performs a final sanity check to verify everythin
If something was registered with the `Disposer` but remains undisposed, the IntelliJ Platform reports it before shutting down.
In test and Debug mode (`idea.disposer.debug` is set to `on`), registering a `Disposable` with the `Disposer` also registers a stack trace for the object's allocation path.
The `Disposer` accomplishes this by creating a dummy `Throwable` at the time of registration.
The `Disposer` accomplishes this by creating a `Throwable` at the time of registration.
The following snippet represents the sort of "memory leak detected" error encountered in practice:

37
topics/basics/getting_started/theme/creating_theme_project.md
View File

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Creating a Theme Project
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Creating a theme plugin project with Plugin DevKit wizard and generated project overview.</link-summary>
This documentation page describes a DevKit-based theme project generated with the [New Project Wizard](https://www.jetbrains.com/help/idea/new-project-wizard.html).
@ -25,22 +25,33 @@ Launch the <control>New Project</control> wizard via the <ui-path>File | New | P
For the example `my_theme` created with the steps describes above, the _IDE Plugin_ generator creates the following directory content:
```text
my_theme
├── resources
│ ├── META-INF
│ │ └── plugin.xml
│ │ └── pluginIcon.svg
│ └── theme
│ └── my_theme.theme.json
└── my_theme.iml
```plantuml
@startuml
skinparam TitleFontName JetBrains Sans
skinparam TitleFontStyle plain
skinparam TitleFontSize 16
skinparam DefaultTextAlignment left
title
my_theme
|_ resources
|_ META-INF
|_ plugin.xml // (Plugin Configuration File) //
|_ pluginIcon.svg // (Plugin Logo) //
|_ ...
|_ theme
|_ my_theme.theme.json // (Theme description file) //
|_ my_theme.iml // (IntelliJ IDEA Module configuration file) //
end title
@enduml
```
- <path>META-INF</path> directory with:
<path>META-INF</path> directory with:
- <path>[plugin.xml](plugin_configuration_file.md)</path> configuration file containing preconfigured theme provider
- <path>pluginIcon.svg</path> file that is a [plugin logo](plugin_icon_file.md)
It is recommended to replace it with a custom icon.
Replace it with a custom logo representing the Theme.
- <path>my_theme.theme.json</path> - a minimal [theme description file](themes_customize.md#introduction-to-theme-description-file-syntax)
- <path>my_theme.iml</path> - [IntelliJ IDEA Module](https://www.jetbrains.com/help/idea/creating-and-managing-modules.html) configuration file

90
topics/basics/plugin_structure/plugin_content.md
View File

@ -1,18 +1,19 @@
# Plugin Content
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Layout and contents of a plugin distribution file.</link-summary>
Plugin distribution will be built using [Gradle](tools_gradle_intellij_plugin.md#tasks-buildplugin) or [Plugin DevKit](deploying_theme.md).
The plugin <path>.jar</path> file must contain:
The plugin distribution <path>.jar</path> file contains:
- the configuration file (<path>META-INF/plugin.xml</path>) ([Plugin Configuration File](plugin_configuration_file.md))
- the classes that implement the plugin functionality
- configuration file (<path>META-INF/plugin.xml</path>) ([Plugin Configuration File](plugin_configuration_file.md))
- classes implementing the plugin functionality
- recommended: plugin logo file(s) (<path>META-INF/pluginIcon*.svg</path>) ([Plugin Logo](plugin_icon_file.md))
See [](plugin_user_experience.md#distribution-size) for important steps to optimize the plugin distribution file.
> See [](plugin_user_experience.md#distribution-size) for important steps to optimize the plugin distribution file.
Targeting a plugin distribution to a specific OS is not possible ([issue](https://youtrack.jetbrains.com/issue/MP-1896)).
@ -20,17 +21,28 @@ Targeting a plugin distribution to a specific OS is not possible ([issue](https:
A plugin consisting of a single <path>.jar</path> file is placed in the <path>/plugins</path> directory.
```text
.IntelliJIDEAx0/
└── plugins
└── sample.jar
├── com/company/sample/SamplePluginService.class
│ ...
│ ...
└── META-INF
├── plugin.xml
├── pluginIcon.svg
└── pluginIcon_dark.svg
```plantuml
@startuml
skinparam TitleFontName JetBrains Sans
skinparam TitleFontStyle plain
skinparam TitleFontSize 16
skinparam DefaultTextAlignment left
title
.IntelliJIDEAx0
|_ plugins
|_ sample.jar // (Plugin distribution) //
|_ com
|_ company
|_ Sample.class // (Class ""com.company.Sample"") //
|_ ...
|_ META-INF
|_ plugin.xml // (Plugin Configuration File) //
|_ pluginIcon.svg // (Plugin Logo) //
|_ pluginIcon_dark.svg // (Plugin Logo, dark variant) //
end title
@enduml
```
### Plugin With Dependencies
@ -42,23 +54,33 @@ All jars from the <path>/lib</path> folder are automatically added to the classp
> Do not repackage libraries into the main plugin archive (<path>sample.jar</path> in the sample below).
> Otherwise, [Plugin Verifier](verifying_plugin_compatibility.md) will yield false positives for unresolved classes and methods.
>
{style="warning"}
{title="Do Not Repackage Libraries" style="warning"}
```text
.IntelliJIDEAx0/
└── plugins
└── sample
└── lib
├── lib_foo.jar
├── lib_bar.jar
│ ...
│ ...
└── sample.jar
├── com/company/sample/SamplePluginService.class
│ ...
│ ...
└── META-INF
├── plugin.xml
├── pluginIcon.svg
└── pluginIcon_dark.svg
```plantuml
@startuml
skinparam TitleFontName JetBrains Sans
skinparam TitleFontStyle plain
skinparam TitleFontSize 16
skinparam DefaultTextAlignment left
title
.IntelliJIDEAx0
|_ plugins
|_ sample
|_ lib
|_ lib_foo.jar // (Required bundled library #1) //
|_ lib_bar.jar // (Required bundled library #2) //
|_ ...
|_ sample.jar // (Plugin distribution) //
|_ com
|_ company
|_ Sample.class // (Class ""com.company.Sample"") //
|_ ...
|_ META-INF
|_ plugin.xml // (Plugin Configuration File) //
|_ pluginIcon.svg // (Plugin Logo) //
|_ pluginIcon_dark.svg // (Plugin Logo, dark variant) //
end title
@enduml
```

16
topics/reference_guide/custom_language_support/documentation.md
View File

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Documentation
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Providing code documentation displayed in the popup invoked by hovering over a symbol or invoking the "View | Quick Documentation" action.</link-summary>
<tldr>
@ -26,9 +26,9 @@ Detailed information on implementing these EPs can be found in the [](#documenta
> Plugins targeting versions earlier than 2023.1 must use the [Documentation Provider API](#documentation-provider-api).
> Note that as long as the transition to the new API is
> not complete, the [custom language tutorial](documentation_provider.md) will use `DocumentationProvider`.
> not complete, the [custom language tutorial](documentation_provider.md) will continue using `DocumentationProvider`.
>
{style="note"}
{title="Targeting IDEs before 2023.1" style="note"}
## Documentation Target API
@ -85,7 +85,7 @@ before, then `computeDocumentation()` should do the work that was formerly done
In addition to showing the documentation, the `computeDocumentationHint()` method returns the text to be displayed
when the user hovers over an element with <shortcut>Ctrl</shortcut>/<shortcut>Cmd</shortcut> pressed or when
<ui-path>Preferences | Editor | Code Editing | "Show quick documentation on hover"</ui-path> is enabled.
<ui-path>Settings | Editor | Code Editing | Show quick documentation on hover</ui-path> is enabled.
In the old framework, this method was called `DocumentationProvider.getQuickNavigateInfo()`.
The `createPointer()` method manages instance restoration and ensures access to the entity across different read actions.
@ -105,10 +105,10 @@ as a reference.
## Documentation Provider API
> As of IntelliJ Platform version 2023.1 the Documentation Provider API is deprecated and plugin
> authors should use the [](#documentation-target-api).
> As of IntelliJ Platform version 2023.1, the Documentation Provider API is deprecated and plugin
> authors should use the [](#documentation-target-api) instead.
>
{style="note"}
{title="Deprecation Notice" style="note"}
Custom language developers usually extend from
[`AbstractDocumentationProvider`](%gh-ic%/platform/analysis-api/src/com/intellij/lang/documentation/AbstractDocumentationProvider.java)

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

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Inlay Hints
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Providing additional code information directly in the editor without changing the document content.</link-summary>
<tldr>
@ -81,7 +81,7 @@ Code vision provider allows for providing **block** inlay hints for elements lik
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.
It is configurable by users in <ui-path>Settings | 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
@ -105,7 +105,7 @@ See the API documentation for the details.
>
> For implementing **block** inlay hints in versions 2022.1 and newer, [](#code-vision-provider) is recommended.
>
{style="warning"}
{title="Deprecation Notice" style="warning"}
To provide inlay hints, implement
[`InlayHintsProvider`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/hints/InlayHintsProvider.kt)

18
topics/reference_guide/custom_language_support/language_injection.md
View File

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Language Injection
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Injecting a language into different language elements.</link-summary>
<tldr>
@ -134,13 +134,13 @@ For instance, injecting SQLite into Python code is specified by the following op
Inside an injection, the following tags can be used:
| XML Tag | Description |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<display-name>` | A short name for the injection. |
| `<place>` | The element pattern that defines where an injection will take place. The content is wrapped in `![CDATA[...]]`. |
| `<prefix>` and `<suffix>` | Static content that is wrapped around the injected code, e.g., to make it a valid expression. For example, to a CSS color specification inside a string, it can be wrapped with the prefix `div { color:` and the suffix `;}` to make it a valid CSS expression. |
| XML Tag | Description |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<display-name>` | A short name for the injection. |
| `<place>` | The element pattern that defines where an injection will take place. The content is wrapped in `![CDATA[...]]`. |
| `<prefix>` and `<suffix>` | Static content that is wrapped around the injected code, e.g., to make it a valid expression. For example, to a CSS color specification inside a string, it can be wrapped with the prefix `div { color:` and the suffix `;}` to make it a valid CSS expression. |
| `<value-pattern>` | A regex for the content that specifies when this injection should be applied. Regex groups can specify the text range of the injection (e.g. `^javascript:(.+)`, see [`xmlInjections-html.xml`](%gh-ic%/plugins/IntelliLang/xml-support/resources/xmlInjections-html.xml)). |
| `<ignore-pattern>` | A regex for the content that specifies when this injection should not be applied. |
| `<ignore-pattern>` | A regex for the content that specifies when this injection should not be applied. |
#### Create an XML File to Load the Configuration
@ -312,4 +312,4 @@ To control delegation of formatting to containing file, implement [`InjectedForm
## Injection Highlighting
To suppress highlighting from <control>Code | Injected language fragment</control> setting in <ui-path>Preferences | Editor | Color Scheme | General</ui-path>, injection host must implement [`InjectionBackgroundSuppressor`](%gh-ic%/platform/analysis-impl/src/com/intellij/psi/impl/source/tree/injected/InjectionBackgroundSuppressor.java).
To suppress highlighting from <control>Code | Injected language fragment</control> setting in <ui-path>Settings | Editor | Color Scheme | General</ui-path>, injection host must implement [`InjectionBackgroundSuppressor`](%gh-ic%/platform/analysis-impl/src/com/intellij/psi/impl/source/tree/injected/InjectionBackgroundSuppressor.java).

8
topics/reference_guide/settings_guide.md
View File

@ -1,6 +1,6 @@
# Settings Guide
<!-- Copyright 2000-2024 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
<!-- Copyright 2000-2023 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
# Settings Guide
<link-summary>Adding entries in Settings.</link-summary>
@ -198,4 +198,6 @@ In that case the IntelliJ Platform calls `ConfigurableProvider.createConfigurabl
By choosing not to provide a `Configuration` implementation in some circumstances, the `ConfigurableProvider` opts out of the Settings display and modification process.
The use of `ConfigurableProvider` as a basis for a Settings implementation is declared using [attributes](#table-of-attributes) in the EP declaration.
**Example**: [`RunToolbarSettingsConfigurableProvider`](%gh-ic%/platform/execution-impl/src/com/intellij/execution/runToolbar/RunToolbarSettingsConfigurableProvider.kt)
**Examples**:
- [`RunToolbarSettingsConfigurableProvider`](%gh-ic%/platform/execution-impl/src/com/intellij/execution/runToolbar/RunToolbarSettingsConfigurableProvider.kt)
- [`VcsManagerConfigurableProvider`](%gh-ic%/platform/vcs-impl/src/com/intellij/openapi/vcs/configurable/VcsManagerConfigurableProvider.java)

56
topics/tutorials/build_system/creating_plugin_project.md
View File

@ -46,27 +46,37 @@ Launch the <control>New Project</control> wizard via the <ui-path>File | New | P
For the example `my_plugin` created with the steps describes above, the _IDE Plugin_ generator creates the following directory content:
```text
my_plugin
├── .run
│ └── Run IDE with Plugin.run.xml
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── src
│ └── main
│ ├── kotlin
│ └── resources
│ └── META-INF
│ ├── plugin.xml
│ └── pluginIcon.svg
├── .gitignore
├── build.gradle.kts
├── gradle.properties
├── gradlew
├── gradlew.bat
└── settings.gradle.kts
```plantuml
@startuml
skinparam TitleFontName JetBrains Sans
skinparam TitleFontStyle plain
skinparam TitleFontSize 16
skinparam DefaultTextAlignment left
title
my_plugin
|_ .run
|_ Run IDE with Plugin.run.xml
|_ gradle
|_ wrapper
|_ gradle-wrapper.jar
|_ gradle-wrapper.properties
|_ src
|_ main
|_ kotlin
|_ resources
|_ META-INF
|_ plugin.xml
|_ pluginIcon.svg
|_ .gitignore
|_ build.gradle.kts
|_ gradle.properties
|_ gradlew
|_ gradlew.bat
|_ settings.gradle.kts
end title
@enduml
```
* The default IntelliJ Platform <path>build.gradle.kts</path> file (see next paragraph).
@ -74,7 +84,7 @@ my_plugin
* The <path>settings.gradle.kts</path> file, containing a definition of the `rootProject.name` and required repositories.
* The Gradle Wrapper files, and in particular the <path>gradle-wrapper.properties</path> file, which specifies the version of Gradle to be used to build the plugin.
If needed, the IntelliJ IDEA Gradle plugin downloads the version of Gradle specified in this file.
* The <path>META-INF</path> directory under the default `main` [source set](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](plugin_configuration_file.md) and [plugin icon](plugin_icon_file.md).
* The <path>META-INF</path> directory under the default `main` [source set](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](plugin_configuration_file.md) and [plugin logo](plugin_icon_file.md).
* The _Run Plugin_ [run configuration](https://www.jetbrains.com/help/idea/run-debug-configuration.html).
The generated `my_plugin` project <path>build.gradle.kts</path> file:
@ -83,7 +93,7 @@ The generated `my_plugin` project <path>build.gradle.kts</path> file:
plugins {
id("java")
id("org.jetbrains.kotlin.jvm") version "1.9.21"
id("org.jetbrains.intellij") version "1.17.0"
id("org.jetbrains.intellij") version "1.17.1"
}
group = "com.example"

14
topics/tutorials/custom_language_support/custom_language_support_tutorial.md
View File

@ -1,6 +1,6 @@
# Custom Language Support Tutorial
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Tutorial for creating a .properties-like custom language.</link-summary>
@ -13,12 +13,13 @@ In this tutorial, we will add support for a [.properties](https://en.wikipedia.o
>
> The accompanying [](writing_tests_for_plugins.md) tutorial covers testing the functionality; corresponding parts are linked under **Testing**.
>
{title="Navigating this tutorial"}
> The complete and fully working example plugin used in this tutorial is the [`simple_language_plugin`](%gh-sdk-samples%/simple_language_plugin) code sample.
>
> See [](code_samples.md) on how to build and run it.
>
{style="note"}
{title="Accessing the code" style="note"}
This a step-by-step tutorial, and it requires completing each step, in order:
@ -45,3 +46,10 @@ This a step-by-step tutorial, and it requires completing each step, in order:
* [](spell_checking_strategy.md)
<include from="snippets.md" element-id="missingContent"/>
<seealso style="cards">
<category ref="related">
<a href="custom_language_support.md"/>
<a href="writing_tests_for_plugins.md"/>
</category>
</seealso>

30
topics/tutorials/writing_tests_for_plugins/tests_prerequisites.md
View File

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# 1. Tests Prerequisites
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Setting up the test folders structure and mocking the project's SDK.</link-summary>
<snippet id="custom_language_testing_tutorial_header">
@ -17,14 +17,24 @@ This page discusses the steps to configure a plugin project for creating tests.
Open the plugin project and create a separate folder named <path>test</path> under the <path>src</path> directory.
Under <path>test</path>, create the <path>java</path> folder for test source code, and the folder <path>testData</path> for [test data files](test_project_and_testdata_directories.md) and reimport the Gradle project.
```text
└── src
├── main
│ ├── java
│ └── resources
└── test
├── java
└── testData
```plantuml
@startuml
skinparam TitleFontName JetBrains Sans
skinparam TitleFontStyle plain
skinparam TitleFontSize 16
skinparam DefaultTextAlignment left
title
src
|_ main
|_ java
|_ resources
|_ test
|_ java
|_ testData
end title
@enduml
```
## Set the Run Configuration Parameters

32
topics/tutorials/writing_tests_for_plugins/writing_tests_for_plugins.md
View File

@ -1,7 +1,7 @@
<!-- Copyright 2000-2023 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
# Testing a Custom Language Plugin
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
<link-summary>Tutorial demonstrating how to develop tests for custom language plugin features.</link-summary>
> Please see [](testing_plugins.md) for a general introduction.
@ -15,14 +15,20 @@ As an example, the plugin implemented in the [Custom Language Support Tutorial](
> Corresponding parts are linked under **Tested Functionality** on top of each page in this tutorial.
>
* [](tests_prerequisites.md)
* [](parsing_test.md)
* [](completion_test.md)
* [](annotator_test.md)
* [](formatter_test.md)
* [](rename_test.md)
* [](folding_test.md)
* [](find_usages_test.md)
* [](commenter_test.md)
* [](reference_test.md)
* [](documentation_test.md)
* [](tests_prerequisites.md)
* [](parsing_test.md)
* [](completion_test.md)
* [](annotator_test.md)
* [](formatter_test.md)
* [](rename_test.md)
* [](folding_test.md)
* [](find_usages_test.md)
* [](commenter_test.md)
* [](reference_test.md)
* [](documentation_test.md)
<seealso style="cards">
<category ref="related">
<a href="testing_plugins.md"/>
</category>
</seealso>

2
topics/user_interface_components/dialog_wrapper.md
View File

@ -26,6 +26,8 @@ It provides the following features:
* <shortcut>Y</shortcut>/<shortcut>N</shortcut> for <control>Yes</control>/<control>No</control> actions if they exist in the dialog
* Optional <control>Do not ask again</control> checkbox
> There's also a DSL-like API via [`DialogBuilder`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogBuilder.java).
### Usage
When using the [`DialogWrapper`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) class for a dialog, follow these required steps:

2
v-releases.list
View File

@ -3,6 +3,6 @@
SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
<vars>
<var name="gradle-intellij-plugin-version" value="1.17.0"/>
<var name="gradle-intellij-plugin-version" value="1.17.1"/>
<var name="gradle-grammar-kit-plugin-version" value="2022.3.2.1"/>
</vars>

6
v.list
View File

@ -3,8 +3,8 @@
SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
<vars>
<var name="ijPlatform" value="2023.3.2"/>
<var name="ijPlatformBuild" value="233.13135.103"/>
<var name="ijPlatform" value="2023.3.3"/>
<var name="ijPlatformBuild" value="233.14015.106"/>
<var name="gh-sdk-samples" value="https://github.com/JetBrains/intellij-sdk-code-samples/tree/main"/>
@ -21,7 +21,7 @@
<var name="gh-ijpgp" value="https://github.com/JetBrains/gradle-intellij-plugin/blob/2.0"/>
<var name="gradle-intellij-plugin-version" value="1.17.0"/>
<var name="gradle-intellij-plugin-version" value="1.17.1"/>
<var name="gradle-grammar-kit-plugin-version" value="2022.3.2.1"/>
<var name="intellij-platform-gradle-plugin-version" value="2.0.0-SNAPSHOT"/>
</vars>

1
writerside.cfg
View File

@ -14,5 +14,6 @@
<vars src="v.list" />
<vars src="v-releases.list" />
<snippets dir="code_samples"/>
<categories src="c.list"/>
<instance src="ijs.tree" keymaps-mode="none" id="intellij" web-path="/intellij/"/>
</ihp>