mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-27 16:57:49 +08:00
319 lines
15 KiB
Markdown
319 lines
15 KiB
Markdown
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
|
|
|
# Customizing Themes - Icons and UI Controls
|
|
|
|
<link-summary>Customizing UI controls and icons in a theme plugin.</link-summary>
|
|
|
|
<tldr>
|
|
|
|
**UI Guidelines:** [](icons_style.md), [](platform_theme_colors.md#ui-components)
|
|
|
|
</tldr>
|
|
|
|
A theme is customized by adding information to the theme description file that overrides the base (_Light_ or _Darcula_) theme.
|
|
|
|
For plugin developers, [](themes_metadata.md) discusses the format of customization keys and information about how to provide it to Theme authors.
|
|
|
|
> [Color Highlighter Plugin](https://plugins.jetbrains.com/plugin/13309-color-highlighter) adds additional color preview inside the editor.
|
|
>
|
|
|
|
<include from="developing_themes.md" element-id="themeSamplePlugin"/>
|
|
|
|
## Introduction to Theme Description File Syntax
|
|
|
|
The syntax of a Theme description file follows the JSON open-standard file format of key-value pairs.
|
|
The minimum valid default file is the output of the [DevKit Theme Wizard](creating_theme_project.md).
|
|
Adding key-value pairs customizes a Theme.
|
|
|
|
Theme key-value pairs often use color as the `value`.
|
|
Colors are defined by six-digit RGB or eight-digit RGBA hexadecimal notation.
|
|
|
|
### Theme Reference Implementations
|
|
|
|
When learning a new syntax, it is often useful to have some existing implementations for reference.
|
|
For example, refer to the [Theme description file](%gh-ic%/platform/platform-resources/src/themes/HighContrast.theme.json) for the IntelliJ IDEA _High Contrast_ Theme.
|
|
It may also help to review [themes available](https://plugins.jetbrains.com/search?headline=164-theme&tags=Theme) at the JetBrains Marketplace.
|
|
|
|
## Defining Named Colors
|
|
|
|
Colors can always be defined individually as six-digit RGB or eight-digit RGBA hexadecimal notation.
|
|
However, Theme definitions often use the same color in multiple places.
|
|
Maintaining a Theme is more manageable if _Named Colors_ are globally defined in a `colors {}` block as part of the <path>*.theme.json</path> file.
|
|
After that, the Named Color can be used instead of a hexadecimal description of the color.
|
|
For example, defining the Named Color `basicBackground` and then using it to set the background color of panels.
|
|
(Don't be concerned with the `"ui"` syntax in the example below; it will be discussed in [Custom UI Control Colors](#custom-ui-control-colors).)
|
|
|
|
```json
|
|
{
|
|
"name": "theme_basics",
|
|
"dark": false,
|
|
"author": "IntelliJ Platform SDK",
|
|
"editorScheme": "/Lightning.xml",
|
|
|
|
"colors": {
|
|
"basicBackground": "#E1E1E1"
|
|
},
|
|
"ui": {
|
|
"Panel.background": "basicBackground"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Customizing Icons
|
|
|
|
Themes can customize the color of default IntelliJ Platform UI icons or substitute custom icons for the default ones.
|
|
Customization is done by adding an `"icons": {}` section to the Theme description file.
|
|
|
|
### Overriding the Global Color of Icons
|
|
|
|
Default global icon colors are customized by adding key-value pairs to a `"ColorPalette": {}` section.
|
|
The `ColorPalette` must be inserted in the `icons` section.
|
|
|
|
In the following example, the `key` - the default red color (`#DB5860`) used for `Action` icons in the _Light_ Theme - is overridden to the `value` of a different color (`#D61A26`):
|
|
|
|
```json
|
|
{
|
|
"icons": {
|
|
"ColorPalette": {
|
|
"#DB5860": "#D61A26"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
This color substitution is applied throughout the IDE UI.
|
|
|
|
### Custom Icon Palette Colors
|
|
|
|
Icon Palettes are predefined theme color keys that describe a single color in an `Actions` or `Objects` context.
|
|
|
|
#### Icon Colors in "Actions" and "Objects" Contexts
|
|
|
|
IntelliJ Platform has default icon colors defined for `Actions` and `Objects` contexts.
|
|
* `Actions` are Theme keys for icons that appear in the context of toolbars and represent actions such as _Compile_, _Run_, or _Debug_.
|
|
* `Objects` are Theme keys for icons that appear in the contexts of lists and trees and represent entities like files, symbols, or run and debug configurations.
|
|
|
|
The [UI Guideline for Icons](icons_style.md) defines the default hexadecimal RGB values of colors for `Actions` and `Objects` keys.
|
|
Note that this document refers to `Objects` keys as "Noun icons."
|
|
|
|
#### Customizing "Actions" and "Objects" Icon Colors
|
|
|
|
An icon Palette color is customized by adding an `Actions` or `Objects` `key` and custom color `value` to the `"ColorPalette": {}` section in a Theme description file.
|
|
The list of available icon `Actions` and `Objects` keys are provided by the editor's completion popup:
|
|
|
|
{width="365"}
|
|
|
|
For example, the following key-value pair changes the color for all blue-colored icons on toolbars to the color `#5BC0DE`:
|
|
|
|
```json
|
|
{
|
|
"icons": {
|
|
"ColorPalette": {
|
|
"Actions.Blue": "#5BC0DE"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
This more specific change to the `Actions.Blue` color overrides the default definition.
|
|
In the narrower context of blue `Actions` icons, it will also supersede any global color overrides of the default blue icon color.
|
|
|
|
### Custom Icons
|
|
|
|
The default IntelliJ Platform UI icons can be replaced by custom icons.
|
|
The file format for icons is SVG.
|
|
The [UI Guideline for Icons](icons_style.md) has detailed specifications for icons.
|
|
|
|
An icon replacement is described within the `icon {}` section of a Theme description file.
|
|
Note that icon replacement key-value pairs appear outside the `ColorPalette` section.
|
|
|
|
For icon substitutions, the `key` is the path to the default icon image.
|
|
This path is derived from the `AllIcons.[Group].[IconName]` path in the <control>icon</control> property reported by the [UI Inspector](internal_ui_inspector.md).
|
|
|
|
For example, the _Build_ (hammer) icon in the toolbar has the path `Allcons.Actions.Compile` as reported by the UI Inspector.
|
|
Therefore, the `key` for the _Build_ icon is `/actions/compile.svg`.
|
|
The `value` is the replacement icon's file name, located in the `resources` folder of the theme plugin project:
|
|
|
|
```json
|
|
{
|
|
"icons": {
|
|
"/actions/compile.svg": "/factory.svg"
|
|
}
|
|
}
|
|
```
|
|
|
|
The color of a replaced icon takes precedence over any `ColorPalette` overrides.
|
|
|
|
> For generating the SVG icons suited for the IntelliJ-based IDEs, you may also use the third-party web tool: [IntelliJ Icon Generator](https://bjansen.github.io/intellij-icon-generator/).
|
|
>
|
|
|
|
## Customizing UI Controls
|
|
|
|
Themes can change the appearance of more general controls in the IntelliJ Platform UI.
|
|
Examples of these controls are labels, buttons, checkboxes, trees, lists, and menus.
|
|
|
|
See also [Platform theme colors](platform_theme_colors.md#ui-components) in UI Guidelines.
|
|
|
|
### Custom UI Control Colors
|
|
|
|
A UI control's custom color is specified by adding a key-value pair to the `"ui": {}` section of a Theme description file.
|
|
|
|
A UI control `key` has the compound format `element.property`, where:
|
|
* `element` is the type (label, checkbox, etc.) of the UI control.
|
|
* `property` is how the color is applied.
|
|
Examples include `foreground`, `background`, and `errorForeground`.
|
|
|
|
Note that some UI control keys have more than two parts, for example, `Popup.Advertiser.foreground` or `ScrollBar.Mac.Transparent.thumbColor`.
|
|
The full key must be used to customize that specific button control.
|
|
However, for other purposes, the first section can be considered the `element`, and the last section considered the `property`.
|
|
|
|
Methods for finding UI control keys are in the [Finding Attribute Keys for UI Controls](#finding-attribute-keys-for-ui-controls) section.
|
|
|
|
#### Customizing All UI Control Colors with the Same Property
|
|
|
|
All UI Controls with the same `property` part of their key can be set to the same color.
|
|
This customization is done using the wildcard `"*": {}` section in the Theme description file.
|
|
A key-value pair is inserted in this section, but only the `property` portion of the key is specified.
|
|
The `value` is the custom color.
|
|
|
|
The following example would change the default background color to `#AED7E3` for all UI controls:
|
|
|
|
```json
|
|
{
|
|
"ui": {
|
|
"*": {
|
|
"background": "#AED7E3"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Note that the wildcard `"*": {}` section must be within the `"ui": {}` section.
|
|
|
|
#### Customizing the Color of Specific UI Control Types
|
|
|
|
The color of a specific UI control type is changed by adding a key-value pair to the `"ui": {}` section of a Theme description file.
|
|
The `key` is the full `element.property` format, and the `value` is the custom color.
|
|
|
|
The following example sets the background color for all labels to the color `#F6E9C9`.
|
|
|
|
```json
|
|
{
|
|
"ui": {
|
|
"*": {
|
|
"background": "#AED7E3"
|
|
},
|
|
"Label.background": "#F6E9C9"
|
|
}
|
|
}
|
|
```
|
|
|
|
The `Label.background` entry supersedes, in the narrower context of label backgrounds, any default color, and any wildcard color assigned to backgrounds.
|
|
|
|
#### Customizing the Color of UI Tabs
|
|
|
|
UI Tab colors are changed by [key-value pairs](#custom-ui-control-colors) in a Theme description file.
|
|
|
|
There are two implementations of tabs in the IntelliJ Platform:
|
|
* Editor Tabs, which represent open files in the [Editor window](https://www.jetbrains.com/help/idea/using-code-editor.html), and in [Tool Window bars](https://www.jetbrains.com/help/idea/tool-windows.html#bars_and_buttons).
|
|
* Tabbed Panes, which are used for the [Run/Debug Configurations dialog](https://www.jetbrains.com/help/idea/run-debug-configurations-dialog.html).
|
|
|
|
The control keys for UI Tabs were expanded from release 2019.1 to 2019.2 of the IntelliJ Platform.
|
|
The 2019.1 release control keys are compatible with release 2019.2 and later versions of the IntelliJ Platform.
|
|
|
|
| Release 2019.1 Element | Release 2019.2 Element | Description of Release 2019.2 Element |
|
|
|------------------------|------------------------|------------------------------------------------------------------------------------------------------------------------|
|
|
| N/A | `DefaultTabs` | Applied to all tabs except `TabbedPane`, _unless_ overridden by a more specific Tab control element. |
|
|
| `EditorTabs` | `EditorTabs` | Applied only to Editor tabs. Overrides any `DefaultTab` settings. 192 has many more `property` settings than 191. |
|
|
| `ToolWindow.HeaderTab` | `ToolWindow.HeaderTab` | Applied only to Tool Window tabs. Overrides any `DefaultTab` settings. 192 has many more `property` settings than 191. |
|
|
| `DebuggerTabs` | `DefaultTabs` | `DefaultTab` settings are used instead of `DebuggerTabs`, except for key `DebuggerTabs.underlineHeight`. |
|
|
| `TabbedPane` | `TabbedPane` | Applied only to Tabbed Panes. |
|
|
| `Plugins.Tab` | `TabbedPane` | Use `TabbedPane` instead. |
|
|
| `SearchEverywhere.Tab` | `SearchEverywhere.Tab` | No change. |
|
|
|
|
Methods for identifying UI control keys are in the [Finding Attribute Keys for UI Controls](#finding-attribute-keys-for-ui-controls) section.
|
|
|
|
For example, here is an excerpt from the IntelliJ Platform [High Contrast Theme](%gh-ic%/platform/platform-resources/src/themes/HighContrast.theme.json):
|
|
Note that a Theme file can mix versions of `property` identifiers:
|
|
* The first three `property` entries are recognized by release 2019.1 and ignored by newer releases because they are defined by new `property` identifiers.
|
|
* The `underlineColor` `property` is recognized by release 2019.1 and newer releases.
|
|
* The `underlineHeight` `property` was introduced in release 2019.2 and is ignored by previous releases.
|
|
* The `underlinedTabBackground` `property` was introduced in release 2019.2, replaces the 2019.1 `selectedBackground`, and is ignored by previous releases.
|
|
* The `inactiveColoredFileBackground` `property` was introduced in release 2019.2, replaces the 2019.1 `inactiveMaskColor`, and is ignored by previous releases.
|
|
|
|
```json
|
|
{
|
|
"ui": {
|
|
"EditorTabs": {
|
|
"selectedForeground": "#FFFFFF",
|
|
"selectedBackground": "#0e5d73",
|
|
"inactiveMaskColor": "#000000FF",
|
|
|
|
"underlineColor": "#1AEBFF",
|
|
"underlineHeight": 4,
|
|
|
|
"underlinedTabBackground": "#000000",
|
|
"inactiveColoredFileBackground": "#00000000"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Customizing the Borders of UI Controls
|
|
|
|
The color and geometry of borders used in UI controls can be customized by key-value pairs in a Theme description file.
|
|
The format of keys for borders is `element.property`, where:
|
|
* `element` is the type of UI control containing a border, such as a window or a popup menu.
|
|
* `property` is the desired border appearance, for example:
|
|
* `border` is the border width (in pixels) specified as top, left, bottom, and right widths.
|
|
Border color is also (optionally) specified as hexadecimal RGB, e.g. `E6E6E6` with no `#` character.
|
|
* `borderInsets` is the inset distance (in pixels) from the edge of the `element` to the border.
|
|
It is specified as top, left, bottom, and right insets.
|
|
|
|
Methods for identifying UI control keys are in the [Finding Attribute Keys for UI Controls](#finding-attribute-keys-for-ui-controls) section.
|
|
|
|
#### Customizing the Border Appearance of Specific UI Controls
|
|
|
|
Adding a key-value pair to the `ui` section of a theme description file customizes the appearance of borders for specific UI control types.
|
|
|
|
The following example sets a new border width and color for all windows:
|
|
|
|
```json
|
|
{
|
|
"ui": {
|
|
"Window.border" : "4,4,4,4,E6E6E6"
|
|
}
|
|
}
|
|
```
|
|
|
|
In this example, the customized border supersedes the default definition and any global color override.
|
|
|
|
## Finding Attribute Keys for UI Controls
|
|
|
|
There are hundreds of UI control `element.property` keys defined in the IntelliJ Platform UI.
|
|
Some keys and strategies for applying them can be found in the [theme reference implementations](#theme-reference-implementations).
|
|
The sections below describe suggested methods for locating UI control keys.
|
|
|
|
### Finding a UI Control Key Using Code Completion in the Editor
|
|
|
|
The preferred method of finding UI control keys is to use the [Code Completion](https://www.jetbrains.com/help/idea/auto-completing-code.html#Auto-Completing_Code.xml) feature in the editor.
|
|
Note that some of the completed keys may be deprecated.
|
|
New entries in the `"ui": {}` section will invoke the code completion popup, as shown below:
|
|
|
|
{width="600"}
|
|
|
|
Code completion and [quick documentation](https://www.jetbrains.com/help/idea/viewing-reference-information.html#inline-quick-documentation) popup items include information about the versions in which specific UI control keys started being supported.
|
|
For example, in the above screenshot, <control>ToolWindow.background</control> property is supported since 2021.3.
|
|
|
|
### Finding a UI Control Key Using Laf Defaults UI
|
|
|
|
Using the [Laf Defaults](internal_ui_laf_defaults.md) inspector, enter the `element` portion of the key.
|
|
The Laf Defaults inspector will prompt with a list of UI Control keys and their default color.
|
|
|
|
### Using the UI Inspector
|
|
|
|
[Use the UI Inspector](internal_ui_inspector.md#using-the-ui-inspector) and check the <control>foreground</control> and <control>background</control> property values.
|
|
If an inspected component can be styled with the UI control key, it will include its name, for example:
|
|
|
|
{width="710"}
|