From 9e34d84e4f6ce4daa21698c56702f40997774e32 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Wed, 28 Jun 2023 15:06:36 +0200 Subject: [PATCH] work_with_icons_and_images.md: Clarify referencing icons by paths and icon holder class constants --- .../work_with_icons_and_images.md | 69 ++++++++++++------- 1 file changed, 43 insertions(+), 26 deletions(-) diff --git a/topics/reference_guide/work_with_icons_and_images.md b/topics/reference_guide/work_with_icons_and_images.md index 3faac5ae381..bbcf9c096e3 100644 --- a/topics/reference_guide/work_with_icons_and_images.md +++ b/topics/reference_guide/work_with_icons_and_images.md @@ -29,7 +29,7 @@ Icons from plugins are located in corresponding `Icons` class (e.g. If custom icons are required, please refer to detailed [design guide](https://jetbrains.design/intellij/principles/icons/). To generate SVG icons suited for the IntelliJ-based IDEs, also consider third-party web tool [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/). -## How to organize and how to use icons? +## Organizing Icons > See [Action Basics](%gh-sdk-samples%/action_basics) sample plugin as a reference. > @@ -37,10 +37,12 @@ To generate SVG icons suited for the IntelliJ-based IDEs, also consider third-pa In the case of a Gradle-based project, icons should be placed in the resources folder. 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. -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 `/`. +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. +In case the icons are referenced from the code and/or XML many times, it's convenient to organize them in an [icons holder class](#icons-class). + +### Icons Class -Then 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: @@ -49,9 +51,8 @@ Then define a class/interface in a top-level package called `icons` holding icon package icons; public interface MyIcons { - Icon Action = IconLoader.getIcon("/icons/myAction.png", MyIcons.class); - Icon Structure = IconLoader.getIcon("/icons/myStructure.png", MyIcons.class); - Icon FileType = IconLoader.getIcon("/icons/myFileType.png", MyIcons.class); + Icon MyAction = IconLoader.getIcon("/icons/myAction.png", MyIcons.class); + Icon MyToolWindow = IconLoader.getIcon("/icons/myToolWindow.png", MyIcons.class); } ``` @@ -66,38 +67,53 @@ package icons object MyIcons { @JvmField - val Action = IconLoader.getIcon("/icons/myAction.png", javaClass) - - @JvmField - val Structure = IconLoader.getIcon("/icons/myStructure.png", javaClass) - + val MyAction = IconLoader.getIcon("/icons/myAction.png", javaClass) @JvmField - val FileType = IconLoader.getIcon("/icons/myFileType.png", javaClass) + val MyToolWindow = IconLoader.getIcon("/icons/myToolWindow.png", javaClass) } ``` -> Starting with 2021.2, `*Icons` class is not required to be located in `icons` package but can use plugin's package: `icons.MyIcons` → `my.plugin.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"} -Use these constants inside [plugin.xml](plugin_configuration_file.md) when specifying `icon` attribute for [``](plugin_configuration_file.md#idea-plugin__actions__action) or extension point, as well in [`@Presentation`](%gh-ic%/platform/analysis-api/src/com/intellij/ide/presentation/Presentation.java) `icon` attribute. -Note that the package name `icons` will be automatically prefixed and must not be specified. +## 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 icons holder class + +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: ```xml + + + + + + +``` + +In case of icons 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. +In case of placing the class in a custom package, the full package name must be provided, e.g.: + +```xml - + + - + + ``` @@ -179,9 +195,10 @@ To create a new animated icon, use the If you want to create an icon where frames follow each other with the same delay, use a constructor that accepts a delay and icons: ```java -AnimatedIcon icon = new AnimatedIcon(500, - AllIcons.Ide.Macro.Recording_1, - AllIcons.Ide.Macro.Recording_2); +AnimatedIcon icon = new AnimatedIcon( + 500, + AllIcons.Ide.Macro.Recording_1, + AllIcons.Ide.Macro.Recording_2); ``` To create an icon from frames with different delays, use `AnimatedIcon.Frame`. @@ -206,7 +223,7 @@ This allows supporting both UI variants at the same time — whichever the user -1. Create new expUi folder in your icon root folder ([Reference](#how-to-organize-and-how-to-use-icons)). +1. Create new expUi folder in your icon root folder ([Reference](#organizing-icons)). 2. Copy all icons for _New UI_ in this folder. 3. Create empty $PluginName$IconMappings.json mapping file in the resources root folder. 4. Register $PluginName$IconMappings.json file in plugin.xml via `com.intellij.iconMapper` extension point.