diff --git a/images/reference_guide/img/toolWindowStructure.png b/images/reference_guide/img/toolWindowStructure.png deleted file mode 100644 index 7e9fb4b02..000000000 Binary files a/images/reference_guide/img/toolWindowStructure.png and /dev/null differ diff --git a/images/reference_guide/img/toolWindowStructure@2x.png b/images/reference_guide/img/toolWindowStructure@2x.png deleted file mode 100644 index f763ecd30..000000000 Binary files a/images/reference_guide/img/toolWindowStructure@2x.png and /dev/null differ diff --git a/images/reference_guide/img/toolWindowStructure@2x_dark.png b/images/reference_guide/img/toolWindowStructure@2x_dark.png deleted file mode 100644 index 0171b5b6f..000000000 Binary files a/images/reference_guide/img/toolWindowStructure@2x_dark.png and /dev/null differ diff --git a/images/reference_guide/img/toolWindowStructure_dark.png b/images/reference_guide/img/toolWindowStructure_dark.png deleted file mode 100644 index 4937fdf32..000000000 Binary files a/images/reference_guide/img/toolWindowStructure_dark.png and /dev/null differ diff --git a/topics/reference_guide/icons.md b/topics/reference_guide/icons.md index 7ec9077bb..bda8b529c 100644 --- a/topics/reference_guide/icons.md +++ b/topics/reference_guide/icons.md @@ -17,8 +17,7 @@ Icons are used widely by IntelliJ Platform plugins. 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. -> For more information, see the [](plugin_icon_file.md) section. +> A [](plugin_icon_file.md), which represents the plugin itself, has different requirements than icons used within plugins. ## 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 resources 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 Resources Root, e.g., icons or resources. -If the icons are referenced only in [plugin.xml](plugin_configuration_file.md) 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 [plugin.xml](plugin_configuration_file.md) 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). ### 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` → `com.example.plugin.MyIcons`. +> +{style="note"} + Define a class/interface in a top-level package called `icons` holding icon constants as static fields: @@ -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 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` → `com.example.plugin.MyIcons`. -> -{style="note"} - ## Using Icons -Icons defined inside plugin.xml with `icon` attribute for [``](plugin_configuration_file.md#idea-plugin__actions__action) or extension point, as well in `@Presentation`'s `icon` attribute, can be referenced in two ways: -- by icon file path -- by icon constant in the icon holder class +Icons defined inside plugin.xml with `icon` attribute for [``](plugin_configuration_file.md#idea-plugin__actions__action) or [extension point](plugin_extension_points.md), +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 Path To reference an icon by path, provide the path relative to the resources directory, e.g., for icons located in my-plugin/src/main/resources/icons directory: @@ -101,44 +103,47 @@ To reference an icon by path, provide the path relative to the resources directo ``` -In the case of icon holder class, reference the icon constants. -Note that if the class is located in the top-level `icons` package, name `icons` will be automatically prefixed and must not be specified. +### By Icons Class + +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.: ```xml - + - + ``` -## 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). -Thus, every icon should have a dedicated variant for Retina devices and Darcula theme. -In some cases, you can skip dark variants if the original icon looks good under Darcula. +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 dark theme and optionally for [HiDPI](#hidpi-version). +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: -| Usage | Icon Size (pixels) | -|------------------------|--------------------| -| Node, Action, Filetype | 16x16 | -| Tool window | 13x13 | -| Editor gutter | 12x12 | -| Editor gutter (New UI) | 14x14 | +| Usage | Icon Size | +|-----------------------------------------------------------------------------|-----------------------------------------------------------------| +| Node, Action, Filetype | 16×16 | +| Tool window | 13×13 | +| Tool window for [New UI](https://www.jetbrains.com/help/idea/new-ui.html) | 20×20 and 16×16 (see [](#new-ui-tool-window-icons)) | +| Editor gutter | 12×12 | +| Editor gutter for [New UI](https://www.jetbrains.com/help/idea/new-ui.html) | 14×14 | -### SVG Format - -> 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). +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)). 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. @@ -147,43 +152,26 @@ If unspecified, it defaults to 16x16 pixels. A minimal SVG icon file: ```xml - ``` +#### 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. -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+. -> -{style="warning"} +All icon files must be placed in the same directory following this naming pattern: -All icon files must be placed in the same directory following this naming pattern (replace .png with .svg for SVG icons): - -| Theme/Resolution | File name pattern | Size | -|------------------|-----------------------------------|-------------| -| Default | iconName.png | W x H | -| Darcula | iconName_dark.png | W x H | -| Default + Retina | iconName@2x.png | 2\*W x 2\*H | -| Darcula + Retina | iconName@2x_dark.png | 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 toolWindowStructure.png icon representations: - -| Theme/Resolution | File name | Icon | -|------------------|----------------------------------------------|-------------------------------------------------------------------------| -| Default | toolWindowStructure.png | ![Tool Window Structure](toolWindowStructure.png) | -| Darcula | toolWindowStructure_dark.png | ![Tool Window Structure, dark](toolWindowStructure_dark.png) | -| Default + Retina | toolWindowStructure@2x.png | ![Tool Window Structure, retina](toolWindowStructure@2x.png) | -| Darcula + Retina | toolWindowStructure@2x_dark.png | ![Tool Window Structure, retina, dark](toolWindowStructure@2x_dark.png) | +| Theme/Resolution | Filename | Icon Size | +|---------------------------------|-----------------------------------|-----------------------------| +| Light | iconName.svg | W×H | +| Dark | iconName_dark.svg | W×H | +| Light + [HiDPI](#hidpi-version) | iconName@2x.svg | 2×W × 2×H | +| Dark + [HiDPI](#hidpi-version) | iconName@2x_dark.svg | 2×W × 2×H | ## Animated Icons @@ -215,7 +203,7 @@ This icon has a larger `AnimatedIcon.Big` version. Register a resource bundle via to provide tooltips automatically for all [`SimpleColoredComponent`](%gh-ic%/platform/platform-api/src/com/intellij/ui/SimpleColoredComponent.java) renderers. -Create `icon..tooltip` key in a resource bundle, where `` is the icon path with leading slash and `.svg` removed and slashes replaced with dots (e.g., `/nodes/class.svg` → `icon.nodes.class.tooltip`). +Create `icon..tooltip` key in the resource bundle, where `` is the icon path with leading slash and `.svg` removed and slashes replaced with dots (e.g., `/nodes/class.svg` → `icon.nodes.class.tooltip`). ## New UI Icons @@ -276,15 +264,16 @@ Example from [`PlatformIconMappings.json`](%gh-ic%/platform/icons/src/PlatformIc ### 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 -[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 -use the following suffix scheme for their icon filename, here referred to as iconToolWindow: +The New UI uses _outlined_ icons for tool windows that have a size of 20×20 pixels and 16×16 pixels in +[Compact Mode](https://www.jetbrains.com/help/idea/new-ui.html#compact-mode). +To provide all necessary variants of a tool window icon use the following filename scheme: -- iconToolWindow.svg: a 16x16 pixels _compact mode_ variant of the icon for the light theme. -- iconToolWindow_dark.svg: a 16x16 pixels _compact mode_ variant of the icon for the dark theme. -- iconToolWindow@20x20.svg: a 20x20 pixels variant of the icon for the light theme. -- iconToolWindow@20x20_dark.svg: a 20x20 pixels variant of the icon for the dark theme. +| Theme/Mode | Filename | Icon Size | +|----------------------|--------------------------------------------|-------------| +| Light | toolWindowIcon@20x20.svg | 20×20 | +| Dark | toolWindowIcon@20x20_dark.svg | 20×20 | +| Light + Compact Mode | toolWindowIcon.svg | 16×16 | +| Dark + Compact Mode | toolWindowIcon_dark.svg | 16×16 | ### New UI Icon Colors