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

icons.md: rework, remove PNG content, smaller fixes

Browse Source
This commit is contained in:
Yann Cébron 2025-05-08 13:09:37 +02:00
parent dad8146f77
commit 48ad55bf0a
5 changed files with 57 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
images/reference_guide/img/toolWindowStructure.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 432 B

BIN
images/reference_guide/img/toolWindowStructure@2x.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 837 B

BIN
images/reference_guide/img/toolWindowStructure@2x_dark.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 836 B

BIN
images/reference_guide/img/toolWindowStructure_dark.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 432 B

125
topics/reference_guide/icons.md
View File

@ -17,8 +17,7 @@
Icons are used widely by IntelliJ Platform plugins. Icons are used widely by IntelliJ Platform plugins.
Plugins need icons mostly for [actions](action_system.md), custom component renderers, [](tool_windows.md), etc. Plugins need icons mostly for [actions](action_system.md), custom component renderers, [](tool_windows.md), etc.
> A plugin _logo_, which represents the plugin itself, has different requirements than icons used within plugins. > A [](plugin_icon_file.md), which represents the plugin itself, has different requirements than icons used within plugins.
> For more information, see the [](plugin_icon_file.md) section.
## Platform vs. Custom Icons ## Platform vs. Custom Icons
@ -37,11 +36,17 @@ If custom icons are required, refer to detailed [design guide](icons_style.md).
In the case of a Gradle-based project, icons should be placed in the <path>resources</path> directory. In the case of a Gradle-based project, icons should be placed in the <path>resources</path> directory.
If the project is DevKit-based, the recommended approach is to put icons to a dedicated [source root](https://www.jetbrains.com/help/idea/content-roots.html) marked as <control>Resources Root</control>, e.g., <path>icons</path> or <path>resources</path>. If the project is DevKit-based, the recommended approach is to put icons to a dedicated [source root](https://www.jetbrains.com/help/idea/content-roots.html) marked as <control>Resources Root</control>, e.g., <path>icons</path> or <path>resources</path>.
If the icons are referenced only in <path>[plugin.xml](plugin_configuration_file.md)</path> attributes or elements, or in the [`@Presentation`](%gh-ic%/platform/analysis-api/src/com/intellij/ide/presentation/Presentation.java) `icon` attribute, then they can be [referenced](#using-icons) by paths. If the icons are referenced only in <path>[plugin.xml](plugin_configuration_file.md)</path> or via [`@Presentation`](%gh-ic%/platform/analysis-api/src/com/intellij/ide/presentation/Presentation.java) `icon` attribute, then they can be [referenced by paths](#by-path).
In case the icons are referenced from the code and/or XML many times, it's convenient to organize them in an [icon holder class](#icons-class). In case the icons are referenced from the code and/or XML many times, it's convenient to organize them in an [icon holder class](#icons-class).
### Icons Class ### Icons Class
> Starting with 2021.2, the `*Icons` class is not required to be located in the `icons` package but can use the plugin's package:
>
> `icons.MyIcons` &rarr; `com.example.plugin.MyIcons`.
>
{style="note"}
Define a class/interface in a top-level package called `icons` holding icon constants as static fields: Define a class/interface in a top-level package called `icons` holding icon constants as static fields:
<tabs> <tabs>
@ -79,15 +84,12 @@ object MyIcons {
The `getIcon()` method of [`IconLoader`](%gh-ic%/platform/util/ui/src/com/intellij/openapi/util/IconLoader.kt) can be used to access the icons. The `getIcon()` method of [`IconLoader`](%gh-ic%/platform/util/ui/src/com/intellij/openapi/util/IconLoader.kt) can be used to access the icons.
The path to the icon passed in as argument to `IconLoader.getIcon()` **must** start with leading `/`. The path to the icon passed in as argument to `IconLoader.getIcon()` **must** start with leading `/`.
> Starting with 2021.2, `*Icons` class is not required to be located in `icons` package but can use plugin's package: `icons.MyIcons` &rarr; `com.example.plugin.MyIcons`.
>
{style="note"}
## Using Icons ## Using Icons
Icons defined inside <path>plugin.xml</path> with `icon` attribute for [`<action>`](plugin_configuration_file.md#idea-plugin__actions__action) or extension point, as well in `@Presentation`'s `icon` attribute, can be referenced in two ways: Icons defined inside <path>plugin.xml</path> with `icon` attribute for [`<action>`](plugin_configuration_file.md#idea-plugin__actions__action) or [extension point](plugin_extension_points.md),
- by icon file path as well as in [`@Presentation`](%gh-ic%/platform/analysis-api/src/com/intellij/ide/presentation/Presentation.java) `icon` attribute, can be referenced in two ways.
- by icon constant in the icon holder class
### By Path
To reference an icon by path, provide the path relative to the resources directory, e.g., for icons located in <path>my-plugin/src/main/resources/icons</path> directory: To reference an icon by path, provide the path relative to the resources directory, e.g., for icons located in <path>my-plugin/src/main/resources/icons</path> directory:
@ -101,44 +103,47 @@ To reference an icon by path, provide the path relative to the resources directo
</extensions> </extensions>
``` ```
In the case of icon holder class, reference the icon constants. ### By Icons Class
Note that if the class is located in the top-level `icons` package, name `icons` will be automatically prefixed and must not be specified.
In the case of [icon holder class](#icons-class), reference the icon constants.
Note that if the class is located in the top-level `icons` package, the `icons` package name will be automatically prefixed and must not be specified.
In case of placing the class in a custom package, the full package name must be provided, e.g.: In case of placing the class in a custom package, the full package name must be provided, e.g.:
```xml ```xml
<actions> <actions>
<!-- referencing icons from class in top-level 'icons' package --> <!-- referencing icons from 'MyIcons' class
in top-level 'icons' package -->
<action icon="MyIcons.MyAction" ... /> <action icon="MyIcons.MyAction" ... />
</actions> </actions>
<extensions defaultExtensionNs="com.intellij"> <extensions defaultExtensionNs="com.intellij">
<!-- referencing icons from custom package --> <!-- referencing icons from 'MyIcons' in custom package -->
<toolWindow icon="com.example.plugin.MyIcons.MyToolWindow" ... /> <toolWindow icon="com.example.plugin.MyIcons.MyToolWindow" ... />
</extensions> </extensions>
``` ```
## Icon Formats ## Icon Files
IntelliJ Platform supports Retina displays and has a bundled dark theme called [Darcula](https://www.jetbrains.com/help/idea/user-interface-themes.html). The IntelliJ Platform supports HiDPI displays and comes with a bundled [dark theme](https://www.jetbrains.com/help/idea/user-interface-themes.html).
Thus, every icon should have a dedicated variant for Retina devices and Darcula theme. Thus, every icon should have a dedicated variant for dark theme and optionally for [HiDPI](#hidpi-version).
In some cases, you can skip dark variants if the original icon looks good under Darcula. If the original icon works well enough in dark theme, a dark variant is not required.
The platform will load the best matching icon variant (if available) depending on the current environment.
### Icon Sizes
Required icon sizes depend on the usage as listed in the following table: Required icon sizes depend on the usage as listed in the following table:
| Usage | Icon Size (pixels) | | Usage | Icon Size |
|------------------------|--------------------| |-----------------------------------------------------------------------------|-----------------------------------------------------------------|
| Node, Action, Filetype | 16x16 | | Node, Action, Filetype | 16&times;16 |
| Tool window | 13x13 | | Tool window | 13&times;13 |
| Editor gutter | 12x12 | | Tool window for [New UI](https://www.jetbrains.com/help/idea/new-ui.html) | 20&times;20 and 16&times;16 (see [](#new-ui-tool-window-icons)) |
| Editor gutter (New UI) | 14x14 | | Editor gutter | 12&times;12 |
| Editor gutter for [New UI](https://www.jetbrains.com/help/idea/new-ui.html) | 14&times;14 |
### SVG Format As SVG icons can be scaled arbitrarily, they provide good results in HiDPI environments or when used in combination with
bigger screen fonts (e.g., in [Presentation Mode](https://www.jetbrains.com/help/idea/ide-viewing-modes.html)).
> SVG ([Scalable Vector Graphics](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics)) icons are supported since 2018.2.
>
{style="note"}
As SVG icons can be scaled arbitrarily, they provide better results in HiDPI environments or when used in combination with bigger screen fonts (e.g., in presentation mode).
A base size denoting the size (in the user space) of the rendered image in 1x scale should be provided. A base size denoting the size (in the user space) of the rendered image in 1x scale should be provided.
The size is set via the `width` and `height` attributes omitting the size units. The size is set via the `width` and `height` attributes omitting the size units.
@ -147,43 +152,26 @@ If unspecified, it defaults to 16x16 pixels.
A minimal SVG icon file: A minimal SVG icon file:
```xml ```xml
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"> <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16">
<rect width="100%" height="100%" fill="green"/> <rect width="100%" height="100%" fill="green"/>
</svg> </svg>
``` ```
#### HiDPI Version
The naming notation used for PNG icons (see below) is still relevant.
However, the `@2x` version of an SVG icon should still provide the same base size.
The icon graphics of such an icon can be expressed in more details via double precision. The icon graphics of such an icon can be expressed in more details via double precision.
If the icon graphics are simple enough so that it renders perfectly in every scale, then the `@2x` version can be omitted. If the icon graphics are simple enough so that it renders perfectly in every scale, then the HiDPI version can be omitted.
The HiDPI version should still provide the same base size.
### PNG Format (Deprecated) ### Filenames
> Use [SVG icons](#svg-format) for if your plugin targets 2018.2+. All icon files must be placed in the same directory following this naming pattern:
>
{style="warning"}
All icon files must be placed in the same directory following this naming pattern (replace <path>.png</path> with <path>.svg</path> for SVG icons): | Theme/Resolution | Filename | Icon Size |
|---------------------------------|-----------------------------------|-----------------------------|
| Theme/Resolution | File name pattern | Size | | Light | <path>iconName.svg</path> | W&times;H |
|------------------|-----------------------------------|-------------| | Dark | <path>iconName_dark.svg</path> | W&times;H |
| Default | <path>iconName.png</path> | W x H | | Light + [HiDPI](#hidpi-version) | <path>iconName@2x.svg</path> | 2&times;W &times; 2&times;H |
| Darcula | <path>iconName_dark.png</path> | W x H | | Dark + [HiDPI](#hidpi-version) | <path>iconName@2x_dark.svg</path> | 2&times;W &times; 2&times;H |
| Default + Retina | <path>iconName@2x.png</path> | 2\*W x 2\*H |
| Darcula + Retina | <path>iconName@2x_dark.png</path> | 2\*W x 2\*H |
The `IconLoader` class will load the icon that matches the best depending on the current environment.
Here are examples of <path>toolWindowStructure.png</path> icon representations:
| Theme/Resolution | File name | Icon |
|------------------|----------------------------------------------|-------------------------------------------------------------------------|
| Default | <path>toolWindowStructure.png</path> | ![Tool Window Structure](toolWindowStructure.png) |
| Darcula | <path>toolWindowStructure_dark.png</path> | ![Tool Window Structure, dark](toolWindowStructure_dark.png) |
| Default + Retina | <path>toolWindowStructure@2x.png</path> | ![Tool Window Structure, retina](toolWindowStructure@2x.png) |
| Darcula + Retina | <path>toolWindowStructure@2x_dark.png</path> | ![Tool Window Structure, retina, dark](toolWindowStructure@2x_dark.png) |
## Animated Icons ## Animated Icons
@ -215,7 +203,7 @@ This icon has a larger `AnimatedIcon.Big` version.
Register a resource bundle via <include from="snippets.topic" element-id="ep"><var name="ep" value="com.intellij.iconDescriptionBundle"/></include> to provide tooltips automatically for all [`SimpleColoredComponent`](%gh-ic%/platform/platform-api/src/com/intellij/ui/SimpleColoredComponent.java) renderers. Register a resource bundle via <include from="snippets.topic" element-id="ep"><var name="ep" value="com.intellij.iconDescriptionBundle"/></include> to provide tooltips automatically for all [`SimpleColoredComponent`](%gh-ic%/platform/platform-api/src/com/intellij/ui/SimpleColoredComponent.java) renderers.
Create `icon.<icon-path>.tooltip` key in a resource bundle, where `<icon-path>` is the icon path with leading slash and `.svg` removed and slashes replaced with dots (e.g., `/nodes/class.svg` &rarr; `icon.nodes.class.tooltip`). Create `icon.<icon-path>.tooltip` key in the resource bundle, where `<icon-path>` is the icon path with leading slash and `.svg` removed and slashes replaced with dots (e.g., `/nodes/class.svg` &rarr; `icon.nodes.class.tooltip`).
## New UI Icons ## New UI Icons
<primary-label ref="2022.3"/> <primary-label ref="2022.3"/>
@ -276,15 +264,16 @@ Example from [`PlatformIconMappings.json`](%gh-ic%/platform/icons/src/PlatformIc
### New UI Tool Window Icons ### New UI Tool Window Icons
The New UI uses _outlined_ icons for tool windows that have a size of 20x20 pixels and 16x16 pixels in The New UI uses _outlined_ icons for tool windows that have a size of 20&times;20 pixels and 16&times;16 pixels in
[compact mode](https://www.jetbrains.com/help/idea/new-ui.html#compact-mode). [Compact Mode](https://www.jetbrains.com/help/idea/new-ui.html#compact-mode).
Plugin developers who want to provide all necessary variants of their tool window icons To provide all necessary variants of a tool window icon use the following filename scheme:
use the following suffix scheme for their icon filename, here referred to as <path>iconToolWindow</path>:
- <path>iconToolWindow.svg</path>: a 16x16 pixels _compact mode_ variant of the icon for the light theme. | Theme/Mode | Filename | Icon Size |
- <path>iconToolWindow_dark.svg</path>: a 16x16 pixels _compact mode_ variant of the icon for the dark theme. |----------------------|--------------------------------------------|-------------|
- <path>iconToolWindow@20x20.svg</path>: a 20x20 pixels variant of the icon for the light theme. | Light | <path>toolWindowIcon@20x20.svg</path> | 20&times;20 |
- <path>iconToolWindow@20x20_dark.svg</path>: a 20x20 pixels variant of the icon for the dark theme. | Dark | <path>toolWindowIcon@20x20_dark.svg</path> | 20&times;20 |
| Light + Compact Mode | <path>toolWindowIcon.svg</path> | 16&times;16 |
| Dark + Compact Mode | <path>toolWindowIcon_dark.svg</path> | 16&times;16 |
### New UI Icon Colors ### New UI Icon Colors