Understanding Plasma Styles (2024)

Essentials of making a Plasma Style

Plasma Frameworkprovides thePlasma::Themeclass so Plasma elements and otherapplications, such as KRunner, can graphically hint or themeinterface elements. This is not a replacement for QStyle, but ratherprovides standard elements for things such as box backgrounds.

This allows for easy re-theming of the desktop while also keeping elementson the desktop more consistent with each other.

Theme Location, Structure and Definition

Themes are stored in:

System/Default: /usr/share/plasma/desktoptheme/
User Installed: ~/.local/share/plasma/desktoptheme/ (KDE Store Category)

Each theme is stored in its own sub-folder following the name of the theme.

Example: ~/.local/share/plasma/desktoptheme/electrostorm/

A theme is described by a metadata.json file in the top-level directory ofthe theme folder (so electrostorm/metadata.json in this case). Additional properties are defined in a separate plasmarc file.

Beneath this directory you will find the following file structure:

dialogs/: images for dialogs.
icons/: optional directory images for icons.
widgets/: images for widgets.
opaque/: optional directory containing images appropriate for non-compositing environments.
translucent/: optional directory containing images appropriate for whenbackground contrast and blur effect is supported.
wallpapers/: wallpaper image packages.
metadata.json: theme name, version, and credits.
plasmarc: optional theme properties.
colors: optional configuration file defining a color scheme that blends well with images.

All SVG images are optional. If a theme is missing an SVG file, it will fall back to the default Breeze theme.

The contents of the metadata.json file might look like this:

~/.local/share/plasma/desktoptheme/electrostorm/metadata.json

{ "KPlugin": { "Authors": [ { "Name": "A Plasma Style Designer", "Email": "my@mail.address", } ], "Name": "Electrostorm", "Description": "Brings a very dynamic electrical energy atmosphere to the desktop", "Id": "electrostorm", "Version": "0.1", "Category": "", "EnabledByDefault": true, "License": "GPL", "Website": "" }, "X-Plasma-API": "5.0"}

Tip

There is an online tool available to get a general idea of how these values interact with each other: https://niccolo.venerandi.com/backstage/files/ownopacity/main.html

Blurring what is behind windows, panels or tooltips.This is enabled by default. Since Plasma Frameworks 5.57, this can be disabled like so:

[BlurBehindEffect]enabled=false

Deprecation Note

Prior to KDE Frameworks 6, themes used a metadata.desktop file instead of metadata.json + plasmarc.

For porting reasons, here is how the old metadata.desktop would look like:

Default Theme Wallpaper

Themes may optionally provide wallpaper image packages to be used with the theme.These wallpaper image packages must appear in the wallpapers/ directory within the theme.

A theme may also define a default wallpaper image, image size and image file extensionto be used in conjunction with the theme. It will then be automatically used as wallpaperimage, if the current wallpaper type supports the settings (like the "Image" wallpaper type) and theuser has not yet chosen a custom image.

The default wallpaper image may either beinstalled in the standard location for wallpaper image packages or may be shipped with thetheme itself. The default wallpaper image settings should appear in the theme'splasmarc file and contain the following entries:

[Wallpaper]defaultWallpaperTheme=<name of default wallpaper package>defaultFileSuffix=<wallpaper file suffix, e.g. .jpg>defaultWidth=<width in pixels of default wallpaper file>defaultHeight=<height in pixels of default wallpaper file>

Colors

The colors file follows the standard Plasma color scheme file format andallows a theme to define what colors work best with its theme elements.The colors in this file can be edited with the color scheme editor available in System Settings.

Make a new color scheme using the editor in System Settings -> Appearance -> Colors.
Save it with a unique name.
You will see the new color scheme in ~/.local/share/color-schemes/[theme-name].colors.
Copy everything to your Plasma Style colors file except the [ColorEffects:Disabled]and [ColorEffects:Inactive] sections.

The most common use of the colors file is to ensure that text is readable on various backgrounds.

Here is a non-comprehensive list of the main color entries in the colors file that are currently actively used in a Plasma Style:

[Colors:Window]
- ForegroundNormal: the text color applied to text on the standard background elements; maps toTheme::TextColor
- BackgroundNormal: the default background color used for items that paint a background themselves, allowing them to blend in with the theme; maps toTheme::BackgroundColor
- DecorationHover: the color used for text highlighting; maps toTheme::HighlightColor
[Colors:Button]
- ForegroundNormal: the text color to use on push buttons
- ForegroundActive: the color used to tint BackgroundNormal for final button hinting color
- BackgroundNormal: the background color used for hinting buttons
[Colors:View]
- ForegroundLink: the text color used for clickable links
- ForegroundVisited: the text color used for visited links
- ForegroundNormal: the text color used most non-title text in applications
- ForegroundInactive: the text color used for secondary text, like placeholders in text fields ("Search…")
- DecorationFocus: the color used for outlines revolving content panes (like Dolphin or Kate), outlines for checkboxes, and the background tint of hovered menu options.
- DecorationHover: the color used in the outline of text fields or checkboxes, or to highlight the background of tabs and menu buttons when hovered.
[Colors:Header]
- ForegroundNormal: the text color used for the titlebar and headerbar
- BackgroundNormal: the background color used for the titlebar and headerbar
[ColorsSelection]
- ForegroundNormal: the text color used in text fields
- BackgroundNormal: the background color used in text fields
[Colors:Tooltip]
- ForegroundNormal: the primary text color used for tooltips from Plasma
- ForegroundInactive: the color used for secondary text in tooltips, such as the "Press Shift for More" text
- BackgroundNormal: the color used for the background of tooltips

Other colors in the file may be used by individual widgets or used in the future, so you are encouraged to provide a complete color scheme file.

The following colors are currently also used by individual plasmoids, which should give a good idea of additional usage patterns:

[Colors:View]
- BackgroundNormal: used as a background color for the digital clock and the dictionary plasmoid search field.
- ForegroundNormal: used by the digital clock for most of its minute indicators and arrows, as well as the text color used in the search field of the dictionary plasmoid.
- DecorationFocus: used to outline the dictionary plasmoid search field.
- DecorationHover: used when hovering the dictionary plasmoid search field.
[Colors:Complementary]
- Same roles as Colors:Window, those are used in areas such as the logout screen, the screen locker, and other areas in order for them to have independent colors compared to normal plasmoids.

Note that some of these may end up folded back intoPlasma::Themeproperly at some point.

Image Access from C++

Theme elements can be accessed from C++ code by path. Whether this maps to literal paths on diskor not is not guaranteed and considered an implementation detail ofPlasma::Theme.

For example, to access the dialog background, one might create an SVG in this manner:

Plasma::Theme theme;Plasma::Svg svg("dialogs/background");svg.resize(size());

By usingPlasma::Svg, changes to the theme are automatically picked up.