From 48ad55bf0a390add1807f549627ab8aedd5e7bd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yann=20C=C3=A9bron?= Date: Thu, 8 May 2025 13:09:37 +0200 Subject: [PATCH] icons.md: rework, remove PNG content, smaller fixes --- .../img/toolWindowStructure.png | Bin 432 -> 0 bytes .../img/toolWindowStructure@2x.png | Bin 837 -> 0 bytes .../img/toolWindowStructure@2x_dark.png | Bin 836 -> 0 bytes .../img/toolWindowStructure_dark.png | Bin 432 -> 0 bytes topics/reference_guide/icons.md | 125 ++++++++---------- 5 files changed, 57 insertions(+), 68 deletions(-) delete mode 100644 images/reference_guide/img/toolWindowStructure.png delete mode 100644 images/reference_guide/img/toolWindowStructure@2x.png delete mode 100644 images/reference_guide/img/toolWindowStructure@2x_dark.png delete mode 100644 images/reference_guide/img/toolWindowStructure_dark.png diff --git a/images/reference_guide/img/toolWindowStructure.png b/images/reference_guide/img/toolWindowStructure.png deleted file mode 100644 index 7e9fb4b027b5969dc701cd6e03b40dcda123356a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 432 zcmV;h0Z;ykP)F8+_1e&|0? z@jDnkoRRYHR(aw72i2wjZ&wukKarL4lOc4*(cSS&F8ogbY5>t;GmfFybT&PH_r0R5 z{|`#C|AXjr>GAs+Jp1;^1m700QG1&AL5u_~0W0_C&d)5MS&AJIFf zH2lHZx`@vp8pKCegQ00vZOEY=U2*^S^(X%a(LnxDf||Cr1b;p>DenKVX^H<2PmcS) zwKe!Bh9=}B1H#*yy>}n#5B`5-V#t3Gy}iYIKe`$WP3tOcL zpQVMoimp}2>s|{2cj$y_H;_x2xXngbb6tm>k|NkGEe-;A=saelj}sfFeU`Rmu)bMg zf=;X-3y@2HvzX2?2Q~{G@crfuCg|p^W@?f=uTxVLLl1vdQM5v{F{ddyL)f4fTs)@a63uMT zGbb)Wob;0RV~RRx#>w((i_Q@a2!9CY8U6xw2Q+)?BBY5v;}V7|p{^;^`I8hy;bl&< z@Uyi*>mm3l9A0nZ{_<3C zSDC<5XHmczcj!olkGQCM72fKlGIeiyYzGzH5y>vTnsDLQVE=KhmK@;F0pz@ z%y>EhrWZ?4)VT`go^=VFafc2wPN$P&(WglhCrx>A@QzHaS2WHB4L-Xr+1A6s+`?>G#hi0qEmzodcpZ4N-ogM20e4^ zBE(EDX+NTHJrsVn zmc)Aqeu}55Uid|eqW(t_*IZTfqrEHvI&URIPlZwfXWXGX>a6Ud7Rwby$BlUCt4xF8 zS{-=odI_9yhmK_Uh>O~+3b9{Eg%NueOgH4g>~o_8&bUK|nTU&CSH$|nIt@%avS6km zI|$sN!;I{rPz(t1zVSzDn0lgRf{tYT;qD1r^j^3kj@Ku_ggu!FI?O~|Gg^~N0fdx7_cW`q5Ai8TV#))??iG*E>NOrMu&;JE+(103d@)r&O O0000ry?@)^R7cL_R7gCl=>h-fOXc&q12?b?EQCbNl6$Nn-3baj@Id&~m5wTDR zf{GB@x4EIX>1_ry>`JwGcsPgmFq=V|Y>vllHi4RE zH0bB?(0&f=M+KlJImvMxY7n31>$8!Ce1uT>tqP=-^W6`$d$DP#|hpF<&>TyQbD?`l(ge!tl)G6!zcPAdH2r*F? ztM|W-B!o9YXFYe+v*fQ4;&ub;$Me>5cvdS=(=5Je8HMLGsn{w5yx$7cBxn8|MZGE^ zwZ%Yo+YGk>2BM3qTFa>U%TUf26gcHqL3* 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