Development/Tutorials/Plasma5/ThemePortingToPlasma5

While the basic format of Plasma themes has not changed since the first version of Plasma, by the time in Plasma 5 some backward-incompatible changes happened for the range of elements expected in the themes. Here is a list of the changes, please supplement if changes are missing.

KRunner

dialogs/krunner is no longer used by KRunner, instead dialogs/background is applied.

Changes to do:

• remove dialogs/krunner SVGs

Logout/Shutdown dialog

dialogs/shutdowndialog is no longer used. Instead the the implementation of "logoutmainscript" of the active Plasma LookAndFeel package defines the look of that dialog, with the default Breeze implementation not using any special theme elements.

Changes to do:

• remove dialogs/shutdowndialog SVGs

Panel background

The "*-mini-*" variants from the widgets/panel-background SVGs are no longer applied, instead always the normal "[prefix-]*" elements are used.

Changes to do:

• remove all "*-mini-*" variants
• ensure all the "[prefix-]*" elements include the potential borders (e.g. the "north-*" ones have the "*left*", "*bottom*" & "*right*" ones)

(often simply renaming the "*-mini-*" variants to their non-mini counterparts and removing the old ones before is all to do)

Analog clock

The rotation center of a hand (shadow) element now defaults to its "(width/2,width/2)" point from the top-left of the element, no longer is the the y-axis position of the elements with respect to the center of ClockFace taken into account. Since Plasma 5.16 the hints "hint-[hand(shadow)]-rotation-center-offset" (with "[hand(shadow)]" being "hourhand", "hourhandshadow", "minutehand", "minutehandshadow", "secondhand", "secondhandshadow") allow to define a custom relative point (can also be outside the element).

Also has the hard-coded relative offset of the optional shadow elements for the hands been changed a few times. Since Plasma 5.16 it defaults to (0,0) and can be overwritten by the "hint-hands-shadow-offset-to-west/hint-hands-shadows-offset-to-east" and "hint-hands-shadow-offset-to-north/hint-hands-shadow-offset-to-south" hints.

With the change to QtQuick the rendering of the hands also is subject to OpenGL-based rendering usually. Which also means that for rotated rendering of images (like done for the hands) there is no anti-aliasing for the borders of the images, resulting in a jagged outline of the hands in most angles. As one workaround at least still with Qt 5.12/Plasma 5.16 one can add some transparent pixels as outline of the hand elements. The amount of padding needed depends on the size of the hand, as the padding will be scaled as well, so needs some try & error to find what is enough.

Changes to do:

• if the default "(width/2,width/2)" relative rotation center point of a hand does not match: either add transparent padding area to the hand as needed or, recommended for Plasma >= 5.16, define a "hint-[hand(shadow)]-rotation-center-offset" element, e.g. by adding a circle whose center marks the relative rotation center
• if there are shadows elements and the default (0,0) offset does not match the theme's light model: define ""hint-hands-shadow-offset-to-*" elements for the shadow offset
• add some transparent rectangle for padding around the visual hands to the hand element if there is no transparent padding yet

Notes

The notes applet no longer uses the complete widgets/notes SVG file as shape for a note. Instead it expects 10 elements in the widgets/notes SVG, one note shape element with name "[color]-notes" per each supported color: "white", "black", "red", "orange", "yellow", "green", "blue", "pink", "translucent", "translucent-light".

Changes to do:

• name the existing shape with a name for a matching color
• add 9 more variants for all the missing colors

Extender

The widgets/extender-background SVG is no longer used.

Changes to do:

• remove widgets/extender-background SVGs

Progressbar

The height of a progressbar is no longer hard-coded in Plasma code (used to be 20 pixels), but instead read from content of the widgets/bar-meter-[dimension] SVGs (with "dimension" usually "horizontal", use of "vertical" option not spread). The default/implicit height for a horizontal bar is taken from the "hint-bar-size" element. If that hint is not present, then instead the recommended height is calculated by the sum of the heights of the "bar-inactive-top" and "bar-inactive-bottom" elements.

Changes to do:

• add a "hint-bar-size" element with the wanted default height of the bar to widgets/bar-meter-horizontal

Shadows (panels, tooltips, dialogs)

The window/compositing manager no longer automatically adds shadows to windows. But leaves it to the windows to provide shadow pixmaps matching the light model of the current theme.

Changes to do:

• add shadow elements & hints to the SVGs of dialogs/background, widgets/panel-background, widgets/tooltip (see Details)

BlurBehind (panels, tooltips, dialogs)

If KWin, the window manager, is set to do compositing, by default now for any window-like views the visual content behind the view will be blurred, if the KWin BlurBehind effect is enabled (default), using the mask of the painted view. For panels until Plasma 5.16 not the mask, but the full rect is used though, resulting in artifacts for non-full-rect panel shape themes.

As the BlurBehind effect also is applied for non-Plasma windows, users might want to have the effect enabled for non-Plasma windows in any case.

Changes to do:

• if no BlurBehind is wanted or needed for the theme (e.g. with full opaque themes), add to the metadata.desktop file a group "[BlurBehindEffect]" with an entry "enabled=false" (available for Plasma >= 5.16)

Borders and content margins (panels, tooltips, dialogs)

Plasma code now has the assumption that the value of the full width of the border element (or the "[prefix]-hint-[direction]-margin" override) can also be interpreted as content margin when the border is not enabled. So effectively assuming that visual border itself is almost of 0 width, and the margin is just that, the margin between edge and content. This was done to simplify the code when any window-like elements where shown bounded to a screen edge, where then the related border would be disabled (which again would mean another window size if turning off the border would affect the window size).

On the sides where the border is disabled, the content then gets a padding with a value of the border element width (or "[prefix]-hint-[direction]-margin" override) over the center element.

Changes to do:

• make sure the visual borders of frames are as slim as possible, so that the full border element width works also as content margin value when the border element itself is not used (consider also use of "[prefix]-hint-[direction]-margin"), e.g. for dialogs/background, widgets/panel-background, widgets/tooltip